Docbasic

User’s Guide

January, 1996

DOC3-DQDUG-3000

 

Copyright © 1996
by Documentum, Inc.
5671 Gibraltar Drive
Pleasanton, CA 94588-8547

All Rights Reserved

Restricted Rights Legend

All other products mentioned in this document are identified by the trademarks,
service marks, or product names as designated by the companies who market
those products.
 Table of Contents
Preface

Chapter 1 Using Docbasic

What is Docbasic? ........................................................................................................ 1-2

Benefits of Using Docbasic .................................................................................. 1-2
Using Docbasic with Workspace ............................................................................... 1-3
Redirecting Workspace Method Calls ............................................................... 1-3
Customizing Workspace Method Calls............................................................. 1-4
Passing the Method ....................................................................................... 1-4
Preprocessing ................................................................................................. 1-4
Postprocessing ............................................................................................... 1-4
Pre- and Postprocessing ............................................................................... 1-5
Overriding ...................................................................................................... 1-5
Calling Workspace or Server API Methods ...................................................... 1-5
Working With Workspace Objects ..................................................................... 1-6
Modifying Objects ......................................................................................... 1-7
Obtaining the Values of Objects .................................................................. 1-8
Opening Dialog Boxes .................................................................................. 1-8
Closing Dialog Boxes .................................................................................... 1-8
Example: Modifying a Button...................................................................... 1-8
Using Docbasic with the Server ............................................................................... 1-10
Writing Docbasic Programs for the Server ..................................................... 1-10
Running Docbasic Programs from the Server ................................................ 1-10
Storing the Program as Content ................................................................ 1-10
Storing the Program Externally ................................................................. 1-11
Using dmbasic.............................................................................................. 1-11

i
 Examples .............................................................................................................. 1-12
For Programs Stored as Content................................................................ 1-12
For Programs Stored Externally ................................................................ 1-12

Chapter 2 Editing and Debugging Docbasic Procedures

Procedure Editor Basics............................................................................................... 2-2

Procedure Editor's Application Window .......................................................... 2-2
Toolbar.................................................................................................................... 2-2
Toolbar Tools.................................................................................................. 2-3
Keyboard Shortcuts .............................................................................................. 2-3
Editing Your Procedures............................................................................................. 2-6
Navigating within a Procedure........................................................................... 2-6
To move the insertion point with the mouse............................................. 2-6
To move the insertion point to a specified line in your procedure ........ 2-7
Performing Editing Operations with Procedure Editor .................................. 2-7
Inserting Text.................................................................................................. 2-7
Selecting Text.................................................................................................. 2-8
To select text with the mouse................................................................ 2-8
To select text with the keyboard........................................................... 2-9
To select an entire line of text with the keyboard .............................. 2-9
Deleting Text.......................................................................................................... 2-9
To delete text ................................................................................................ 2-10
To delete the end-of-line character............................................................ 2-10
Cutting and Copying Text ................................................................................. 2-10
To cut a selection.......................................................................................... 2-11
To copy a selection....................................................................................... 2-11
Pasting Text.......................................................................................................... 2-11
Undoing Editing Operations............................................................................. 2-11
Adding Comments to a Procedure................................................................... 2-12
To add a full-line comment ........................................................................ 2-12
To add a comment at the end of a line of code........................................ 2-12
Breaking a Docbasic Statement across Multiple Lines .................................. 2-13
Searching and Replacing.................................................................................... 2-13
Finding Text in Your Procedure ................................................................ 2-13
Replacing Text in a Procedure ................................................................... 2-14
Checking the Syntax of a Procedure ................................................................ 2-15

ii
 Running a Procedure................................................................................................. 2-17
To run your procedure ............................................................................... 2-17
To pause an executing procedure ............................................................. 2-17
To stop an executing procedure ................................................................ 2-17
Debugging a Procedure ............................................................................................ 2-18
Using the Docbasic Debugger........................................................................... 2-18
Tracing Procedure Execution ............................................................................ 2-18
To step through your procedure ............................................................... 2-18
To trace procedure calls.............................................................................. 2-19
To resume execution at another line within a subroutine ..................... 2-19
Setting and Removing Breakpoints......................................................................... 2-21
Setting Breakpoints............................................................................................. 2-21
To debug selected portions of your procedure ....................................... 2-21
To start debugging partway through a procedure ................................. 2-22
To move the pointer to a line outside the current subroutine .............. 2-22
Removing Breakpoints....................................................................................... 2-23
To remove a single breakpoint manually ................................................ 2-23
To remove all breakpoints manually........................................................ 2-23
Using Watch Variables .............................................................................................. 2-24
To add a watch variable ............................................................................. 2-24
To select a watch variable........................................................................... 2-25
To delete a watch variable.......................................................................... 2-26
Modifying the Value of a Variable .......................................................................... 2-27
To modify the value of a variable on the watch variable list ................ 2-27
Exiting from Procedure Editor................................................................................. 2-29
Menu Reference.......................................................................................................... 2-30
File Menu ...................................................................................................... 2-30
Edit Menu ..................................................................................................... 2-30
Run Menu ..................................................................................................... 2-31
Debug Menu................................................................................................. 2-31
Help Menu.................................................................................................... 2-31

Chapter 3 A-Z Reference

& (operator)................................................................................................................... 3-2

' (keyword) .................................................................................................................... 3-3
() (keyword) .................................................................................................................. 3-4

iii
 * (operator) .................................................................................................................... 3-6
+ (operator) ................................................................................................................... 3-8
- (operator)................................................................................................................... 3-10
. (keyword) .................................................................................................................. 3-12
/ (operator) ................................................................................................................. 3-13
< (operator) ................................................................................................................. 3-15
= (statement) ............................................................................................................... 3-16
\ (operator) ................................................................................................................. 3-18
^ (operator) ................................................................................................................. 3-19
_ (keyword) ................................................................................................................. 3-20
Abs (function) ............................................................................................................. 3-21
And (operator) ............................................................................................................ 3-23
Any (data type)........................................................................................................... 3-25
ArrayDims (function) ................................................................................................ 3-26
Arrays (topic) .............................................................................................................. 3-27
ArraySort (statement) ................................................................................................ 3-30
Asc (function).............................................................................................................. 3-32
Atn (function) ............................................................................................................. 3-33
Basic.Capability (method)......................................................................................... 3-34
Basic.Eoln$ (property) ............................................................................................... 3-36
Basic.FreeMemory (property) .................................................................................. 3-37
Basic.HomeDir$ (property)....................................................................................... 3-38
Basic.OS (property) .................................................................................................... 3-39
Basic.PathSeparator$ (property) .............................................................................. 3-41
Basic.Version$ (property).......................................................................................... 3-42
Beep (statement) ......................................................................................................... 3-43
Boolean (data type) .................................................................................................... 3-44
ByRef (keyword)......................................................................................................... 3-46
ByVal (keyword) ........................................................................................................ 3-47
Call (statement)........................................................................................................... 3-49
CBool (function) ......................................................................................................... 3-51
CCur (function)........................................................................................................... 3-53
CDate, CVDate (functions) ....................................................................................... 3-54
CDbl (function)........................................................................................................... 3-56
ChDir (statement)....................................................................................................... 3-57
ChDrive (statement)................................................................................................... 3-59

iv
Choose (function)....................................................................................................... 3-61
Chr, Chr$ (functions)................................................................................................. 3-62
CInt (function) ............................................................................................................ 3-64
Clipboard$ (function) ................................................................................................ 3-66
Clipboard$ (statement).............................................................................................. 3-67
Clipboard.Clear (method)......................................................................................... 3-68
Clipboard.GetFormat (method) ............................................................................... 3-69
Clipboard.GetText (method) .................................................................................... 3-71
Clipboard.SetText (method) ..................................................................................... 3-72
CLng (function) .......................................................................................................... 3-73
Close (statement)........................................................................................................ 3-75
Command, Command$ (functions)......................................................................... 3-76
Comments (topic)....................................................................................................... 3-77
Comparison Operators (topic) ................................................................................. 3-78
Const (statement) ....................................................................................................... 3-81
Constants (topic) ........................................................................................................ 3-83
Cos (function) ............................................................................................................. 3-84
CreateObject (function) ............................................................................................. 3-85
Cross-Platform Procedures (topic) .......................................................................... 3-87
CSng (function) .......................................................................................................... 3-92
CStr (function) ............................................................................................................ 3-94
CurDir, CurDir$ (functions) ..................................................................................... 3-96
Currency (data type).................................................................................................. 3-98
CVar (function)........................................................................................................... 3-99
CVErr (function)....................................................................................................... 3-101
Date (data type) ........................................................................................................ 3-103
Date, Date$ (functions)............................................................................................ 3-105
Date, Date$ (statements) ......................................................................................... 3-106
DateAdd (function).................................................................................................. 3-108
DateDiff (function)................................................................................................... 3-110
DatePart (function) .................................................................................................. 3-112
DateSerial (function)................................................................................................ 3-114
DateValue (function) ............................................................................................... 3-115
Day (function)........................................................................................................... 3-116
DDB (function) ......................................................................................................... 3-117
DDEExecute (statement) ......................................................................................... 3-119

v
 DDEInitiate (function) ............................................................................................. 3-121
DDEPoke (statement) .............................................................................................. 3-123
DDERequest, DDERequest$ (functions) ............................................................... 3-125
DDESend (statement) .............................................................................................. 3-127
DDETerminate (statement) ..................................................................................... 3-129
DDETerminateAll (statement) ............................................................................... 3-131
DDETimeout (statement) ........................................................................................ 3-132
Declare (statement) .................................................................................................. 3-134
DefType (statement) ................................................................................................ 3-144
Dim (statement) ........................................................................................................ 3-147
Dir, Dir$ (functions)................................................................................................. 3-151
DiskDrives (statement)............................................................................................ 3-154
DiskFree (function) .................................................................................................. 3-155
dmAPIExec (function) ............................................................................................. 3-156
dmAPIGet (function) ............................................................................................... 3-157
dmAPISet (function) ................................................................................................ 3-159
dmExit (function) ..................................................................................................... 3-160
Do...Loop (statement) .............................................................................................. 3-162
Double (data type) ................................................................................................... 3-165
ebBoolean (constant)................................................................................................ 3-167
ebCancel (constant) .................................................................................................. 3-168
ebCritical (constant) ................................................................................................. 3-169
ebCurrency (constant) ............................................................................................. 3-170
ebDataObject (constant) .......................................................................................... 3-171
ebDate (constant)...................................................................................................... 3-172
ebEmpty (constant) .................................................................................................. 3-173
ebError (constant)..................................................................................................... 3-174
ebHidden (constant) ................................................................................................ 3-175
ebInteger (constant) ................................................................................................. 3-176
ebLong (constant)..................................................................................................... 3-177
ebNone (constant) .................................................................................................... 3-178
ebNormal (constant) ................................................................................................ 3-179
ebNull (constant) ...................................................................................................... 3-180
ebObject (constant)................................................................................................... 3-181
ebReadOnly (constant) ............................................................................................ 3-182
ebSingle (constant) ................................................................................................... 3-183

vi
ebString (constant) ................................................................................................... 3-184
ebSystem (constant) ................................................................................................. 3-185
ebSystemModal (constant) ..................................................................................... 3-186
ebVariant (constant) ................................................................................................ 3-187
ebVolume (constant)................................................................................................ 3-188
Empty (constant) ...................................................................................................... 3-189
End (statement) ........................................................................................................ 3-190
Environ, Environ$ (functions)................................................................................ 3-191
EOF (function) .......................................................................................................... 3-192
Eqv (operator)........................................................................................................... 3-193
Erase (statement)...................................................................................................... 3-195
Erl (function)............................................................................................................. 3-197
Err (function) ............................................................................................................ 3-198
Err (statement) .......................................................................................................... 3-199
Error (statement) ...................................................................................................... 3-200
Error Handling (topic)............................................................................................. 3-201
Error, Error$ (functions).......................................................................................... 3-203
Exit Do (statement) .................................................................................................. 3-205
Exit For (statement).................................................................................................. 3-207
Exit Function (statement)........................................................................................ 3-209
Exit Sub (statement)................................................................................................. 3-210
Exp (function) ........................................................................................................... 3-211
Expression Evaluation (topic) ................................................................................ 3-212
External (function) ................................................................................................... 3-214
False (Constant)........................................................................................................ 3-215
FileAttr (function) .................................................................................................... 3-216
FileCopy (statement) ............................................................................................... 3-218
FileDateTime (function) .......................................................................................... 3-220
FileDirs (statement) ................................................................................................. 3-222
FileExists (function) ................................................................................................. 3-224
FileLen (function)..................................................................................................... 3-225
FileList (statement) .................................................................................................. 3-226
FileParse$ (function) ................................................................................................ 3-229
FileType (function)................................................................................................... 3-231
Fix (function)............................................................................................................. 3-233
For...Next (statement) .............................................................................................. 3-234

vii
 Format, Format$ (functions)................................................................................... 3-237
FreeFile (function) ................................................................................................... 3-244
Function...End Function (statement) ..................................................................... 3-245
Fv (function).............................................................................................................. 3-2 50
Get (statement) ......................................................................................................... 3-252
GetAppInfo (function)............................................................................................. 3-255
GetAttr (function)..................................................................................................... 3-256
GetObject (function)................................................................................................. 3-258
GetSession (function)............................................................................................... 3-260
Global (statement) .................................................................................................... 3-261
Goto (statement) ....................................................................................................... 3-263
Hex, Hex$ (functions).............................................................................................. 3-265
Hour (function)......................................................................................................... 3-266
If...Then...Else (statement)....................................................................................... 3-267
IIf (function) .............................................................................................................. 3-269
Imp (operator)........................................................................................................... 3-270
Inline (statement) ..................................................................................................... 3-272
Input# (statement) .................................................................................................... 3-273
Input, Input$ (functions)......................................................................................... 3-276
InputBox, InputBox$ (functions)............................................................................ 3-278
InStr (function).......................................................................................................... 3-280
Int (function) ............................................................................................................. 3-282
Integer (data type).................................................................................................... 3-283
IPmt (function).......................................................................................................... 3-284
IRR (function) ........................................................................................................... 3-286
Is (operator)............................................................................................................... 3-288
IsDate (function)....................................................................................................... 3-290
IsEmpty (function) ................................................................................................... 3-291
IsError (function)...................................................................................................... 3-292
IsMissing (function) ................................................................................................. 3-293
IsNull (function) ....................................................................................................... 3-294
IsNumeric (function) ............................................................................................... 3-295
IsObject (function).................................................................................................... 3-297
Item$ (function) ........................................................................................................ 3-298
ItemCount (function) ............................................................................................... 3-300
Keywords (topic) ...................................................................................................... 3-301

viii
Kill (statement) ......................................................................................................... 3-302
LBound (function).................................................................................................... 3-304
LCase, LCase$ (functions) ...................................................................................... 3-306
Left, Left$ (functions) .............................................................................................. 3-307
Len (function) ........................................................................................................... 3-308
Let (statement).......................................................................................................... 3-310
Like (operator) .......................................................................................................... 3-311
Line Input# (statement)........................................................................................... 3-313
Line Numbers (topic) .............................................................................................. 3-315
Line$ (function) ........................................................................................................ 3-316
LineCount (function) ............................................................................................... 3-318
Literals (topic)........................................................................................................... 3-3 19
Loc (function)............................................................................................................ 3-321
Lock (statement) ....................................................................................................... 3-323
Lof (function) ............................................................................................................ 3-325
Log (function) ........................................................................................................... 3-326
Long (data type) ....................................................................................................... 3-327
LSet (statement)........................................................................................................ 3-328
LTrim, LTrim$ (functions) ...................................................................................... 3-330
MacID (function) ...................................................................................................... 3-331
MacScript (statement).............................................................................................. 3-332
Main (statement) ...................................................................................................... 3-333
Mci (function) ........................................................................................................... 3-334
Mid, Mid$ (functions) ............................................................................................. 3-337
Mid, Mid$ (statements) ........................................................................................... 3-339
Minute (function) ..................................................................................................... 3-341
MIRR (function) ....................................................................................................... 3-342
MkDir (statement).................................................................................................... 3-344
Mod (operator) ......................................................................................................... 3-345
Month (function) ...................................................................................................... 3-347
MsgBox (function).................................................................................................... 3-348
MsgBox (statement) ................................................................................................. 3-350
Name (statement)..................................................................................................... 3-351
New (keyword) ........................................................................................................ 3-353
Not (operator)........................................................................................................... 3-354
Nothing (constant) ................................................................................................... 3-356

ix
 Now (function) ......................................................................................................... 3-357
NPer (function) ......................................................................................................... 3-358
Npv (function) .......................................................................................................... 3-360
Null (constant) .......................................................................................................... 3-362
Object (data type) ..................................................................................................... 3-363
Objects (topic) ........................................................................................................... 3-365
Oct, Oct$ (functions) ................................................................................................ 3-368
On Error (statement) ................................................................................................ 3-369
Open (statement) ...................................................................................................... 3-372
OpenFilename$ (function) ...................................................................................... 3-375
Operator Precedence (topic) ................................................................................... 3-377
Operator Precision (topic)....................................................................................... 3-378
Option Base (statement) .......................................................................................... 3-379
Option Compare (statement).................................................................................. 3-380
Option CStrings (statement) ................................................................................... 3-382
Or (operator) ............................................................................................................. 3-384
Pi (constant)............................................................................................................... 3-386
Pmt (function) ........................................................................................................... 3-387
PPmt (function)......................................................................................................... 3-389
Print (statement) ....................................................................................................... 3-391
Print# (statement) ..................................................................................................... 3-393
Private (statement) ................................................................................................... 3-396
Public (statement)..................................................................................................... 3-398
Put (statement).......................................................................................................... 3-401
Pv (function) ............................................................................................................. 3-404
Random (function) ................................................................................................... 3-406
Randomize (statement) ........................................................................................... 3-407
Rate (function) .......................................................................................................... 3-408
ReadIni$ (function) .................................................................................................. 3-410
ReadIniSection (statement) ..................................................................................... 3-411
Redim (statement) .................................................................................................... 3-413
Rem (statement)........................................................................................................ 3-415
Reset (statement) ...................................................................................................... 3-416
Resume (statement).................................................................................................. 3-417
Return (statement) ................................................................................................... 3-419
Right, Right$ (functions) ......................................................................................... 3-420

x
RmDir (statement) ................................................................................................... 3-421
Rnd (function)........................................................................................................... 3-422
RSet (statement)........................................................................................................ 3-423
RTrim, RTrim$ (functions) ..................................................................................... 3-425
SaveFilename$ (function) ....................................................................................... 3-426
Second (function) ..................................................................................................... 3-429
Seek (function).......................................................................................................... 3-430
Seek (statement) ....................................................................................................... 3-432
Select...Case (statement).......................................................................................... 3-434
Set (statement) .......................................................................................................... 3-436
SetAppInfo (function).............................................................................................. 3-438
SetAttr (statement) ................................................................................................... 3-440
Sgn (function) ........................................................................................................... 3-442
Shell (function) ......................................................................................................... 3-443
Sin (function) ............................................................................................................ 3-445
Single (data type) ..................................................................................................... 3-446
Sleep (statement) ...................................................................................................... 3-448
Sln (function) ............................................................................................................ 3-449
Space, Space$ (functions) ........................................................................................ 3-451
Spc (function)............................................................................................................ 3-452
Sqr (function) ............................................................................................................ 3-453
Stop (statement)........................................................................................................ 3-454
Str, Str$ (functions) .................................................................................................. 3-455
StrComp (function) .................................................................................................. 3-456
String (data type)...................................................................................................... 3-458
String, String$ (functions) ....................................................................................... 3-460
Sub...End Sub (statement)....................................................................................... 3-462
Switch (function) ...................................................................................................... 3-466
SYD (function) .......................................................................................................... 3-467
Tab (function) ........................................................................................................... 3-469
Tan (function) ........................................................................................................... 3-471
Time, Time$ (functions) .......................................................................................... 3-472
Time, Time$ (statements)........................................................................................ 3-473
Timer (function) ....................................................................................................... 3-475
TimeSerial (function) ............................................................................................... 3-476
TimeValue (function)............................................................................................... 3-477

xi
 Trim, Trim$ (functions) ........................................................................................... 3-479
True (constant).......................................................................................................... 3-480
Type (statement)....................................................................................................... 3-481
UBound (function) ................................................................................................... 3-483
UCase, UCase$ (functions) ..................................................................................... 3-485
Unlock (statement) ................................................................................................... 3-486
User-Defined Types (topic)..................................................................................... 3-489
Val (function) ............................................................................................................ 3-491
Variant (data type) ................................................................................................... 3-493
VarType (function)................................................................................................... 3-498
Weekday (function) ................................................................................................. 3-500
While...Wend (statement) ....................................................................................... 3-502
Width# (statement) .................................................................................................. 3-504
Word$ (function) ...................................................................................................... 3-506
WordCount (function) ............................................................................................. 3-508
Write# (statement).................................................................................................... 3-509
WriteIni (statement) ................................................................................................. 3-511
Xor (operator) ........................................................................................................... 3-513
Year (function) .......................................................................................................... 3-515

Appendix A Code Examples

Example 1: Checkin handler...................................................................................... A-2

Example 2: File distribution....................................................................................... A-7
Code File Listings...................................................................................................... A-10

Appendix B Runtime Error Messages

Visual Basic Compatible Error Messages ................................................................. B-2

Docbasic-Specific Error Messages.............................................................................. B-5

Appendix C Compiler Error Messages

Appendix D Language Elements by Platform

Appendix E Docbasic Limitations

Appendix F Docbasic/Visual Basic Differences

xii
 Preface
Purpose of the Manual

This book helps application developers create Docbasic procedures. It presents an

overview of how Docbasic relates to Workspace, describes how to edit Docbasic
procedures, provides an alphabetical reference of Docbasic language elements and
topics, and walks through an extended code example.

The book assumes the Documentum server and Workspace (if used) are installed
and configured. For help with installation and configuration, refer to the
Installation Guide and System Administrator’s Guide.

Intended Audience

This book is intended for application developers who are implementing Docbasic
procedures to modify or extend the normal behavior of Workspace. The book
assumes you are familiar with Workspace.

Docbasic User’s Guide xiii

Organization of the Manual

The table below describes the information you can expect to find in each chapter
and appendix.

Chapter Content

1 Introduces Docbasic and describes how Docbasic and Workspace function

together.

2 Explains how to use Procedure Editor, a tool that enables you to edit and
debug Docbasic procedures.

3 Provides a complete, alphabetical listing of all keywords in the Docbasic

language, including statements, functions, constants, methods, properties, and
data types. Also contains encyclopedia-style topics, such as Cross-Platform
Procedures.

Appendix A Contains two annotated code examples illustrating the use of Docbasic.

Appendix B Lists all Docbasic runtime errors. The appendix is divided into two sections, the
first describing error messages compatible with standard Basic as implemented
by Microsoft Visual Basic and the second describing error messages specific to
Docbasic.

Appendix C Lists all the errors generated by the Docbasic compiler.

Appendix D Lists all Docbasic language elements and on which platforms these language
elements are supported.

Appendix E Describes Docbasic limitations, such as unsupported features, maximum string

lengths, and so on.

Appendix F Describes differences between Docbasic 1.0 and Visual Basic 3.0 (VB) or Visual
Basic for Applications 1.0 (VBA).

Command Syntax Conventions

This manual uses the following conventions in the command syntax specifications
and examples:

Notation Description

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

text$ The presence of a type-declaration character following a parameter

signifies that the parameter must be a variable of that type or an
expression that evaluates to that type.
If a parameter does not appear with a type-declaration character, then
its type is described in the text.

xiv Docbasic User’s Guide

 Notation Description

[parameter] Square brackets indicate that the enclosed items are optional.
In Docbasic, you cannot end a statement with a comma, even if the
parameters are optional:
MsgBox "Hello",,"Message" 'OK
MsgBox "Hello",, 'Not valid

{Input | Binary} Braces indicate that you must choose one of the enclosed items, which
are separated by a vertical bar.

... Ellipses indicate that the preceeding expression can be repeated any
number of times.

Docbasic User’s Guide xv

xvi Docbasic User’s Guide
 1 Using Docbasic
This chapter describes how Docbasic and Workspace function together. For
complete details on how to customize Workspace behavior, see the Workspace
Customizing Guide.

The chapter covers these topics:

What is Docbasic?

Using Docbasic with Workspace

Redirecting Workspace Method Calls

Customizing Workspace Method Calls

Calling Workspace or Server API Methods

Working With Workspace Objects

Using Docbasic with the Server

Writing Docbasic Programs for the Server

Running Docbasic Programs from the Server

Examples

Docbasic User’s Guide 1-1

What is Docbasic? Using Docbasic

What is Docbasic?

Docbasic is a powerful, easy-to-use programming language that Documentum

provides. You use Docbasic to modify or extend the normal behavior of
Workspace. You can also write Docbasic procedures to interact directly with a
Documentum server. You write Docbasic procedures using the Docbasic Editor,
which is described in Chapter 2, Editing and Debugging Docbasic Procedures.

You can use all of the Workspace and Server API methods from a Docbasic
procedure. You can intercept any method sent by Workspace and redirect
execution to a Docbasic procedure. You can also execute any method from within
a Docbasic procedure.

Benefits of Using Docbasic

Although you can use an external application to modify or extend Workspace, as
described in the Workspace Customizing Guide, Docbasic provides several benefits
that make it preferable in some situations. For example, with Docbasic, you can:

Avoid using the interprocess communication protocol required by an
external application. Depending on your platform, external applications
communicate with Workspace using Dynamic Data Exchange (DDE),
AppleEvents, or ToolTalk.

Provide extra functionality that is executed after a defined method. A
Docbasic procedure can take action after Workspace executes the default
behavior for a method. In contrast, when you use an external application to
modify the default behavior for a particular method, you cannot perform
postprocessing.

Ensure portability to all platforms supported by Workspace.

Write procedures in a language similar to Visual Basic for Applications
(VBA). If you are already familiar with VBA, you will find Docbasic easy to
use.

1-2 Docbasic User’s Guide

Using Docbasic Using Docbasic with Workspace

Using Docbasic with Workspace

This section describes how to use Docbasic to customize Workspace behavior.

Redirecting Workspace Method Calls

To change the default behavior of a Workspace method, you use the Define method
to intercept the method and redirect it to a procedure. The Define method instructs
Workspace to redirect a specified method to a specified application, which in this
case is your Docbasic procedure.

You call Define from a procedure or external application. For more information
about how to use Define, refer to the Workspace Customizing Guide.

The following illustration shows how to use Define to redirect a method to a

Docbasic procedure.

1. define,c,method,*,basic,/ProcCabinet/ProcFile,proc

2. Workspace event

method
3.

4. Sub proc(Mthd As String)

REM Mthd= “method”

Figure 1-1 Using Define to Redirect a Method to a Docbasic Procedure

1. The Define method tells Workspace to redirect the method. The keyword
basic tells Workspace to redirect the method to a Docbasic routine, not an
external application. The last two parameters specify which procedure
receives the method.

2. An event occurs in Workspace (for example, the user checks in a

document).

3. Workspace sends the appropriate method call to handle the event (for
example, the Checkindw method).

4. The method is passed into the procedure as a parameter.

Docbasic User’s Guide 1-3

Using Docbasic with Workspace Using Docbasic

Customizing Workspace Method Calls

Your procedure can perform preprocessing, postprocessing, or both. It can also
completely override the method’s default behavior. The following illustration
summarizes how to write a Docbasic procedure to change the behavior of a
Workspace method.

Workspace

Redirected method (Optional)

Sub Procedure(Mthd As String)

' Pre-processing code
... ' use any DocBasic commands
ret$ = dmAPIGet(method, ...) 'execute Workspace methods
ret% = dmAPISet(method, ...)
ret% = dmAPIExec(method, ...)
' Optional -- send method back to Workspace to
' execute default behavior using the following command
ret% = dmAPIExec(Mthd)
' Post-processing code
... ' use any DocBasic commands
End Sub

Figure 1-2 Summary of Procedure Code to Override a Method

Passing the Method

In a Docbasic routine, the Mthd parameter provides a mechanism for passing the
defined method and its arguments, if any, into the procedure. You should include
this parameter in all procedure declarations so that your procedures are ready to
accept redirected Workspace methods. If you do not declare the routine with the
Mthd parameter, the Define method will cause a runtime error.

Preprocessing

To perform preprocessing, a procedure follows these steps:

1. Executes preprocessing code.

2. Sends the method to Workspace to execute the default behavior.

The following function must be the last line in the procedure:

dmAPIExec(Mthd)

Postprocessing

To perform postprocessing, a procedure follows these steps:

1-4 Docbasic User’s Guide

Using Docbasic Using Docbasic with Workspace

1. Sends the method to Workspace to execute the default behavior.

2. Executes postprocessing code.

The following function must be the first line in the procedure:

ret% = dmAPIExec(Mthd)

The procedure pauses at this line while Workspace performs the default behavior
and resumes after Workspace is finished.

Pre- and Postprocessing

To perform both pre- and postprocessing, a procedure follows these steps:

1. Executes preprocessing code.

2. Sends the method to Workspace to execute the default behavior.

3. Executes postprocessing code.

The following function is called after the code that performs Step 1 and before the
code that performs Step 2:
ret% = dmAPIExec(Mthd)

The procedure pauses at this line while Workspace performs the default behavior
and resumes after Workspace is finished.

Overriding

To completely override default behavior, a procedure simply skips the step of

sending the method back to Workspace. The following function call is not in the
procedure:
ret% = dmAPIExec(Mthd)

Calling Workspace or Server API Methods

To execute a Workspace or Server API method from within a Docbasic procedure,
use the dmAPIGet, dmAPISet, or dmAPIExec function, depending on which
method you want to call. For information about which types of methods you can
call with each function, refer to the entries for dmAPIGet, dmAPISet, and
dmAPIExec in Chapter 3, A-Z Reference.

Docbasic User’s Guide 1-5

Using Docbasic with Workspace Using Docbasic

The following illustration summarizes how Workspace handles methods you call
from Docbasic procedures.

Sub Procedure(Mthd As String)

ret$ = dmAPIGet(method, ...) 'execute Workspace methods

Procedure ret% = dmAPISet(method, ...)
ret% = dmAPIExec(method, ...)

...

End Sub

Workspace Server API

API method method
Workspace

Action
code

Client
Library

Server

Figure 1-3 How Workspace Handles Method Calls from Procedures

In this illustration, the dmAPIGet, dmAPISet, or dmAPIExec function specifies

that a method be handled by Workspace. The method is passed from the procedure
to Workspace using the Workspace messaging system. If the method is part of the
Workspace API, Workspace sends the message to the appropriate Workspace code.
If the method is part of the Server API, Workspace sends the call to the client
library, which handles interaction with the server.

Working With Workspace Objects

You can retrieve or modify the values of Workspace objects from within a Docbasic
procedure. For example, you can intercept a dialog box display event and modify
button labels on the dialog box before it is displayed. (For more information about
the different types of Workspace objects, refer to the Workspace Customizing Guide.)

1-6 Docbasic User’s Guide

Using Docbasic Using Docbasic with Workspace

The following illustration summarizes the sequence of events when you use a
Docbasic procedure to customize a dialog box.

1. Define method. For example,

define,c,modal,*,basic,/Cabinet/ProcFile,HandleModal

2. Creation of dialog box

Modal method

3. Sub HandleModal(Mthd As String)

ret$ = dmAPIGet(getdata, ...) 'retrieves object attribute values
ret% = dmAPISet(setdata, ...) 'modifies object attributes
ret% = dmAPIExec(Mthd) ' returns Modal method to Workspace
End Sub

4. Workspace displays modified dialog box

Figure 1-4 Summary of Procedure Code to Customize a Dialog Box

1. The Define method intercepts the Modal method and sends it to the
HandleModal procedure.

2. A dialog box is created, and Workspace sends a Modal method call.

3. HandleModal customizes the dialog box.

4. HandleModal sends the Modal method back to Workspace.

5. Workspace displays the dialog box as customized by HandleModal.

Modifying Objects

To modify the values of Workspace objects, use the Setdata method, which is
executed with the dmAPISet function. The syntax is:
ret% = dmAPISet("setdata,session,object_id,attribute","value")

For example, the following code changes the text on the Cancel button in the
Attributes dialog box from Cancel to Done. The object_id argument,
DdaAttributes.pButCancel, is a combination of the dialog box name and the
control name.
ret% = dmAPISet("setdata,c,DdaAttributes.pButCancel,text","Done")

Docbasic User’s Guide 1-7

Using Docbasic with Workspace Using Docbasic

Obtaining the Values of Objects

To determine the value of a Workspace object, use the Getdata method, which is
executed with the dmAPIGet function. The syntax is:
text$ = dmAPIGet("getdata,session,object_id,attribute")

For example, the following code returns the label text on the Cancel button in the
Attributes dialog box.
text$ = dmAPIGet("getdata,c,DdaAttributes.pButCancel,text")

Opening Dialog Boxes

When Workspace attempts to open a dialog box, you can intercept the Modal
method call that is generated and customize the dialog box, as described in
“Working With Workspace Objects” earlier in this chapter. To display the dialog
box after customizing it, use the Modal method, which is executed with the
dmAPIExec function. The syntax is:
retval% = dmAPIExec("modal,session,object_id")

For example:
retval% = dmAPIExec("modal,s0,8000001F0000001D")

You could also use the following code instead of the numeric object ID:
DdaAttributes.dm_document

For details about the Modal method, refer to the Workspace Customizing Guide.

Closing Dialog Boxes

You can close any dialog box that you opened. (To open a dialog box, use the Modal
method, as described in “Opening Dialog Boxes.”) You cannot close a dialog box
opened by Workspace.

To close a dialog box, use the Endmodal method, which is executed with the
dmAPIExec function. The syntax is:
retval% = dmAPIExec("endmodal,session,object_id")

For example:
retval% = dmAPIExec("endmodal,s0,8000001F0000001D")

Example: Modifying a Button

The following example shows how to modify the Save button in a dialog box
before it is displayed.

1-8 Docbasic User’s Guide

Using Docbasic Using Docbasic with Workspace

When a dialog box is created, Workspace calls the Modal method. The following
code redirects the Modal method to the HideSave procedure in the file
HideSaveProc.
define,c,dcapp,modal,DdaAttributes,basic,/Cabinet/HideSaveProc,HideSave

The HideSave procedure accepts the Modal method as a parameter. It uses the
dmAPISet function to change the Enabled and Visible attributes of the Save button.
Then it uses the dmAPIExec function to return the Modal method to Workspace,
which displays the modified dialog box.
Sub HideSave(Mthd As String)

retval% = dmAPISet(setdata,c,Ddaattributes.pButSave,Enabled","F" )

retval% = dmAPISet(setdata,c,Ddaattributes.pButSave,Visible","F" )

retval% = dmAPIExec(Mthd)

End Sub

Docbasic User’s Guide 1-9

Using Docbasic with the Server Using Docbasic

Using Docbasic with the Server

In addition to using Docbasic programs to customize Workspace, you can also use
Docbasic to add features and functionality at the server level. For example, you
may want to write a program that automatically retrieves archived content when
a user requests an archived document or a program that performs data validation
when a document moves from one task to another in a router.

(The System Administrator’s Guide contains detailed instructions for using Docbasic
to restore archived content. Instructions for using Docbasic procedures in
workflows are found in the Server User’s Guide.)

Writing Docbasic Programs for the Server

Writing Docbasic programs for the server is very similar to writing GAWK scripts.
Observe the following rules:

Your program needs to establish a connection to a docbase before working
with its objects and end the connection when finished.

You cannot execute Workspace API methods.

You cannot create dialog boxes or other user interface elements.

Running Docbasic Programs from the Server

Docbasic programs are executed on the server by a program called dmbasic. To
execute Docbasic programs stored in method objects (as content or externally), you
can invoke dmbasic with the DO_METHOD function in either an EXECUTE DQL
statement or an Apply server API method. You can also run dmbasic directly from
the operating system command line to execute Docbasic programs stored in
external files.

Docbasic programs written for Workspace are stored in procedure objects.

Docbasic programs written for the server are stored in method objects. You can
store the actual program file as an external file referenced by the method object or
as the method’s own content. How you store the file determines how you set the
method object’s attributes. The following sections describe the differences.

Storing the Program as Content

If you create a method object with a Docbasic program as content, specify the
following attribute values:

Set the method_verb attribute to: dmbasic.

You can also include any of the arguments accepted by dmbasic (such as -e
to specify and entry point and -p to specify parameters) as listed in Table 1-
1. Do not include the -f argument.

1-10 Docbasic User’s Guide

Using Docbasic Using Docbasic with the Server

Set the use_method_content attribute to: TRUE.

Set the method_type attribute to: dmbasic.

Setting the method_type is necessary so the server will know how to pass
arguments to dmbasic. Setting method_type to “dmbasic” causes the server to add
“-f” in front of the content file name and to add the “--” flag before any arguments
specified on the DO_METHOD command line. The -- flag directs dmbasic to pass
those arguments to the Docbasic program.

Storing the Program Externally

If you create a method object to represent a Docbasic program stored in an external

file, specify the following attribute values:

Set the method_verb attribute to: dmbasic -ffilename.

For filename, enter the full path and name of the Docbasic program file. You
can also include any of the other arguments accepted by dmbasic as listed in
Table 1-1.

Set the use_method_content attribute to: FALSE.

Set the method_type attribute to: dmbasic.

Using dmbasic

Dmbasic is the program that executes Docbasic programs at the server level. You
can use dmbasic the same way you use gawk to execute a GAWK script. The
forward slash (/) is not accepted as an argument separator in dmbasic.

Table 1-1 lists the arguments that Dmbasic accepts:

Table 1-1 Dmbasic arguments

Argument Description

-flist_of_file_names Specifies one or more Docbasic program files that you want to execute.
Separate the file names with spaces. This argument is required if the
Docbasic program or programs are stored in an external file. If the
Docbasic program is stored as the content of the method, do not specify
this argument; the server will add the argument when it executes the
method.

-eentrypoint Specifies the name of a procedure in the program to run. If the -f argument
specifies multiple files, then the program containing the procedure must
be first in the list.

-pparameter Specifies a parameter to pass to the program or entry point. You can
repeat this argument to specify more than one parameter.

--arguments Directs dmbasic to pass all remaining command-line text as parameter(s)

to the program or entry point. This must be the last argument on the
dmbasic command-line.

Docbasic User’s Guide 1-11

Using Docbasic with the Server Using Docbasic

Table 1-1 Dmbasic arguments

Argument Description

-c Directs dmbasic to only compile the file and not to execute it.

Note: The Main() procedure in a Docbasic program cannot accept parameters. If

you need to pass parameters to a Docbasic procedure, name the procedure
something other than Main.

Examples
This section contains some examples of the command line generated by different
combinations of method attributes and EXECUTE commands.

For Programs Stored as Content

Assume a Docbasic program is stored as content in a method object called

“MyMethod.” The object has method_verb set to “dmbasic -eMy_Main” which
specifies the MyMain procedure as the entry point. In addition, assume the
MyMain procedure expects four arguments.

If the following command is used to execute the program:

EXECUTE do_method WITH METHOD = 'MyMethod' WITH ARGUMENTS =
'tribble3 dist_component1 0600164680000571 server_config_1'

the generated command line looks like this:

dmbasic -eMyMethod -f/u30/install/dmadmin/share/data/common/000015b3/
80/00/15/a2/00000000.txt -- tribble3 dist_component1 0600164680000571
server_config_1

For Programs Stored Externally

Now assume that the Docbasic program is stored as an external file, and the
method_verb attribute is set to:
dmbasic -eMyMain -f/myhome/docbasic/myprogram.txt

If the following command is used to execute the program (the same as the previous
example):
EXECUTE do_method WITH METHOD = 'MyMethod' WITH ARGUMENTS =
'tribble3 dist_component1 0600164680000571 server_config_1'

the generated command line looks like:

dmbasic -eMyMethod -f/myhome/docbasic/myprogram.txt -- tribble3
dist_component1 0600164680000571 server_config_1

Suppose you added the first two of the four arguments to the method_verb
attribute as follows:

1-12 Docbasic User’s Guide

Using Docbasic Using Docbasic with the Server

dmbasic -eMyMain -f/myhome/docbasic/myprogram.txt -ptribble3

-pdist_component1

You can specify the remaining two arguments in the EXECUTE command:
EXECUTE do_method WITH METHOD = 'MyMethod' WITH ARGUMENTS =
'0600164680000571 server_config_1'

and the following command line would be generated:

dmbasic -eMyMethod -f/myhome/docbasic/myprogram.txt -ptribble3
-pdist_component1 -- 0600164680000571 server_config_1

Docbasic User’s Guide 1-13

Using Docbasic with the Server Using Docbasic

1-14 Docbasic User’s Guide

 2 Editing and
Debugging
Docbasic
Procedures
This chapter explains how to use Procedure Editor, a tool that enables you to edit
and debug Docbasic procedures. It begins with some general information about
working with Procedure Editor and then describes how to edit procedures, run
your procedures to make sure they work properly, debug them if necessary, and
exit from Procedure Editor. It then summarizes the items on the Procedure Editor
menus.

The chapter covers these topics:

Procedure Editor Basics

Editing Your Procedures

Running Your Procedures

Debugging Your Procedures

Exiting from Procedure Editor

Menu Reference

Docbasic User’s Guide 2-1

Procedure Editor Basics Editing and Debugging Docbasic Procedures

Procedure Editor Basics

This section provides general information that will help you work most effectively
with Procedure Editor. It includes an overview of Procedure Editor's application
window—the interface you'll use to edit, run, and debug your Docbasic
procedures—as well as lists of keyboard shortcuts and information on using the
Help system.

Procedure Editor's Application Window

Procedure Editor's application window contains the following elements:

Toolbar—a collection of tools that you can use to provide instructions to
Procedure Editor.

Edit pane—a window containing the Docbasic procedure you are currently
editing.

Watch pane—a window that displays a list of watch variables. The watch
pane is available only after you have added one or more variables to the list.

Pane separator—a divider that appears between the edit pane and the watch
pane when the watch pane is open.

Status bar—an area that identifies the current location of the insertion point
within your procedure.

Toolbar
The following list briefly explains the purpose of each of the tools on Procedure
Editor's toolbar. The use of these tools is described in more detail later in the
chapter.

2-2 Docbasic User’s Guide

Editing and Debugging Docbasic Procedures Procedure Editor Basics

Toolbar Tools
Table 2-1 Toolbar Buttons

Button Face Tool Function

Start Runs a procedure.

End Stops execution of a procedure.

Toggle Breakpoint Adds or removes a breakpoint on a line of Docbasic code.

Add Watch Displays the Add Watch dialog box, in which you can
specify the name of a Docbasic variable. Procedure Editor
then displays the value of that variable, if any, in the watch
pane of its application window.

Calls Displays the list of procedures called by the currently

executing Docbasic procedure. Available only during
break mode.

Single Step Executes the next line of a Docbasic procedure and then
suspends execution of the procedure. If the procedure calls
another Docbasic procedure, execution will continue into
each line of the called procedure.

Procedure Step Executes the next line of a Docbasic procedure and then
suspends execution of the procedure. If the procedure calls
another Docbasic procedure, Docbasic will run the called
procedure in its entirety.

Keyboard Shortcuts
The following lists summarize the various types of keyboard shortcuts,
including general shortcuts, navigating shortcuts, editing shortcuts, and
debugging shortcuts.

Table 2-2 General Shortcuts

Key(s) Function

Ctrl+F Displays the Find dialog box, which allows you to specify text for which
you want to search.

F3 Searches for the next occurrence of previously specified text. If you have
not previously specified text, displays the Find dialog box.

F4 Displays the Goto Line dialog box.

Esc Deactivates the Help pointer if it is active. Otherwise, compiles your

procedure and returns you to the host application.

Docbasic User’s Guide 2-3

Procedure Editor Basics Editing and Debugging Docbasic Procedures

Table 2-3 Navigating Shortcuts

Key(s) Function

Up arrow Moves the insertion point up one line.

Down arrow Moves the insertion point down one line.

Left arrow Moves the insertion point left by one character position.

Right arrow Moves the insertion point right by one character position.

PgUp Moves the insertion point up one window.

PgDn Moves the insertion point down one window.

Ctrl+PgUp Moves the insertion point left one window.

Ctrl+PgDn Moves the insertion point right one window.

Ctrl + Left arrow Moves the insertion point to the start of the next word to the left.

Ctrl + Right arrow Moves the insertion point to the start of the next word to the right.

Home Places the insertion point before the first character in the line.

End Places the insertion point after the last character in the line.

Ctrl+Home Places the insertion point before the first character in the procedure.

Ctrl+End Places the insertion point after the last character in the procedure.

Table 2-4 Editing Shortcuts

Key(s) Function

Del Removes selected text or removes the character following the insertion
point without placing it on the Clipboard.

BkSp Removes selected text or removes the character preceding the insertion
point without placing it on the Clipboard.

Ctrl+Y Removes the entire line containing the insertion point without placing it
on the Clipboard.

Tab Inserts a tab character.

Enter Inserts a new line, breaking the current line.

Ctrl+C Copies selected text without removing it from the procedure and places it
on the Clipboard.

Ctrl+X Removes selected text from the procedure and places it on the Clipboard.

Ctrl+V Places the contents of the Clipboard at the insertion point.

2-4 Docbasic User’s Guide

Editing and Debugging Docbasic Procedures Procedure Editor Basics

Table 2-4 Editing Shortcuts

Key(s) Function

Shift + any navigating Selects all text between the initial location of the insertion point and the
shortcut point to which the keyboard shortcut would normally move the insertion
point. (For example, pressing Shift + Ctrl + Left arrow selects the word to
the left of the insertion point; pressing Shift+Ctrl+Home selects all the text
from the location of the insertion point to the start of your procedure.)

Ctrl+Z Reverses the effect of the preceding editing change(s).

Table 2-5 Debugging Shortcuts

Key(s) Function

Shift+F9 Displays the Add Watch dialog box, in which you can specify the name of
a Docbasic variable. Procedure Editor then displays the value of that
variable, if any, in the watch pane of its application window.

Del Removes the selected watch variable from the watch pane.

Enter or F2 Displays the Modify Variable dialog box for the selected watch variable,
which enables you to modify the value of that variable.

F5 Runs a procedure.

F6 If the watch pane is open, switches the insertion point between the watch
pane and the edit pane.

F8 Activates the Single Step command, which executes the next line of a
Docbasic procedure and then suspends execution of the procedure. If the
procedure calls another Docbasic procedure, execution will continue into
each line of the called procedure.

Shift+F8 Activates the Procedure Step command, which executes the next line of a
Docbasic procedure and then suspends execution of the procedure. If the
procedure calls another Docbasic procedure, Docbasic will run the called
procedure in its entirety.

Ctrl+Break Suspends an executing procedure and places the instruction pointer on

the next line to be executed.

F9 Sets or removes a breakpoint on the line containing the insertion point.

Docbasic User’s Guide 2-5

Editing Your Procedures Editing and Debugging Docbasic Procedures

Editing Your Procedures

This section explains how to use Procedure Editor to edit Docbasic code.
Although in some respects editing code with Procedure Editor is like editing
regular text with a word-processing program, Procedure Editor also has certain
capabilities specifically designed to help you edit Docbasic code.

You'll learn how to move around within your procedure, select and edit text, add
comments to your procedure, break long Docbasic statements across multiple
lines, search for and replace selected text, and perform a syntax check of your
procedure.

Navigating within a Procedure

Procedure Editor differs from most word-processing programs in that it allows
you to place the insertion point anywhere within your procedure, including
"empty" space. (Empty space is any area within the procedure that does not
contain text, such as a tab's expanded space or the area beyond the last character
on a line.)

The keyboard shortcuts listed in the preceding section include a group of

navigating shortcuts, which you can use to move the insertion point around your
procedure. When you move the insertion point using a keyboard shortcut,
Procedure Editor scrolls the new location of the insertion point into view if it is
not already displayed.

You can also reposition the insertion point with the mouse and the Goto Line
command. This approach is especially fast if the area of the screen to which you
want to move the insertion point is currently visible.

To move the insertion point with the mouse

1. If the target area is not visible, use the scroll bars at the right and bottom of
the display to scroll the target area of the procedure into view.

2. Place the mouse pointer where you want to position the insertion point.

3. Click the left mouse button.

The insertion point is repositioned.

Note: When you scroll the display with the mouse, the insertion point remains in
its original position until you reposition it with a mouse click. If you attempt to
perform an editing operation when the insertion point is not in view, Procedure
Editor automatically scrolls the insertion point into view before performing the
operation.

2-6 Docbasic User’s Guide

Editing and Debugging Docbasic Procedures Editing Your Procedures

To move the insertion point to a specified line in your procedure

Here's how to jump directly to a specified line in your procedure. This approach is
especially fast if the area of the screen to which you want to move the insertion
point is not currently visible, but you know the number of the target line.

1. Press F4.

Procedure Editor displays the Goto Line dialog box.

2. Enter the number of the line in your procedure to which you want to move
the insertion point

3. Click OK or press Enter.

The insertion point is positioned at the start of the line you specified. If
that line is not already displayed, Procedure Editor scrolls it into view.

Note: The insertion point cannot be moved so far below the end of a procedure as
to scroll the procedure entirely off the display. When the last line of your procedure
becomes the first line on your screen, the procedure will stop scrolling. You will not
be able to move the insertion point below the bottom of that screen.

Performing Editing Operations with Procedure Editor

This section provides an overview of the editing operations you can perform with
Procedure Editor—including inserting, selecting, deleting, cutting, copying, and
pasting material—and explains how to undo, or reverse, the most recent editing
operations. You may wish to refer to the lists of keyboard shortcuts, which contain
a group of editing shortcuts that can be used to perform many of the operations
discussed here.

Inserting Text

Use Procedure Editor to insert text and other characters such as tabs and line
breaks the same way you would use a word-processing program: position the
insertion point at the desired location in the procedure and start typing.

However, as noted in the preceding section, Procedure Editor lets you position the
insertion point (and therefore text) in "empty" spaces—a feature that comes in
handy when you want to insert a comment in the space beyond the end of a line
in your procedure. When you insert characters beyond the end of a line, the space

Docbasic User’s Guide 2-7

Editing Your Procedures Editing and Debugging Docbasic Procedures

between the insertion point and the last character on the line is backfilled with tab
characters.

Another way in which Procedure Editor differs from word-processing programs

is that in Procedure Editor, text does not wrap. If you keep entering text on a
given line, eventually you will not be able to enter more text. Therefore, you
control the line breaks by pressing Enter when you want to insert a new line in
your procedure. The effect of pressing Enter depends on where the insertion point
is located at the time.

If you press Enter with the insertion point at or beyond the end of a line, a
new line is inserted after the current line.

If you press Enter with the insertion point at the start of a line, a new line is
inserted before the current line.

If you press Enter with the insertion point within a line, the current line is
broken into two lines at that location.

If you press Tab, a tab character is inserted at the location of the insertion point.
Text after the tab is moved to the next tab position. If you insert new text within a
tab, the text that originally appeared on that line is moved to the next tab position
each time the new text that you are entering reaches the start of another tab
position.

Selecting Text

You can use either the mouse or the keyboard to select text and other characters in
your procedure. Regardless of which method you use, you should be aware that
you can select either a portion of one line or one or more whole lines, but you
cannot select a portion of one line plus one or more whole lines. When you select
multiple lines and start or end your selection partway through a line, Procedure
Editor automatically extends the selection to include the entire line.

To select text with the mouse

Method 1

1. Place the mouse pointer where you want your selection to begin.

2. While pressing the left mouse button, drag the mouse until you reach the
end of your selection, and release the mouse button.

Method 2

1. Place the mouse pointer where you want your selection to end.

2. Press Shift and click the left mouse button.

Method 3

2-8 Docbasic User’s Guide

Editing and Debugging Docbasic Procedures Editing Your Procedures

1. Place the mouse pointer in the left margin beside the first line you want to
select.

The pointer becomes a reverse arrow, which points toward the line of text.

2. To select a single line, click the left mouse button.

3. To select multiple lines, press the left mouse button and drag up or down.

The selected text is highlighted.

To select text with the keyboard

Here's how to use keyboard shortcuts to select text in your procedure.

1. Place the insertion point where you want your selection to begin.

2. While pressing Shift, use one of the navigating keyboard shortcuts to extend
the selection to the desired ending point.

The selected text is highlighted.

Note: When you select an entire line of text in your procedure, it is important to
remember to extend your selection far enough to include the hidden end-of-line
character, which is the character that inserts a new line in your procedure.

To select an entire line of text with the keyboard

Here's how to use the keyboard to select one or more whole lines in your
procedure.

1. Place the insertion point at the beginning of the line you want to select.

2. Press Shift + Down arrow.

The entire line, including the end-of-line character, is selected.

3. To extend your selection to include additional lines of text, repeat step 2.

Once you have selected text within your procedure, you can perform a variety of
other editing operations on it, including deleting the text, placing it on the
Clipboard (either by cutting the text or copying it), and pasting it.

Deleting Text
When you delete material, it is removed from your procedure without being
placed on the Clipboard.

Docbasic User’s Guide 2-9

Editing Your Procedures Editing and Debugging Docbasic Procedures

To delete text

Here's how to remove one or more characters, selected text, or entire lines from
your procedure.

1. To remove one or more characters,

a. To remove a single character to the left of the insertion point, press BkSp
once.

b. To remove a single character to the right of the insertion point, press Del
once.

c. To remove multiple characters, hold down BkSp or Del.

2. To remove a block of text,

a. Select the text

b. Press BkSp or Del.

3. To remove an entire line,

a. Place the insertion point in that line

b. Press Ctrl+Y.

To delete the end-of-line character

Here's how to remove an unwanted line break from your procedure. This has the
effect of combining the current line with the following line.

1. Place the insertion point after the last character on the current line.

2. Press Del once to delete the hidden end-of-line character.

The current line and the following line are combined.

Note: If there are any spaces at the end of the current line, you may have to keep
pressing Del to remove them before you can delete the end-of-line character.

Pressing BkSp with the insertion point at the start of a line has no effect—that is, it
will not combine the current line with the preceding line.

Cutting and Copying Text

You can place material from your procedure on the Clipboard by either cutting it
or copying it.

2-10 Docbasic User’s Guide

Editing and Debugging Docbasic Procedures Editing Your Procedures

To cut a selection

Here's how to cut text from your procedure and place the text on the Clipboard.

1. Select the text.

2. Press Ctrl+X.

The selection is removed from your procedure and placed on the

Clipboard.

To copy a selection

Here's how to copy text from your procedure and place the text on the Clipboard.

1. Select the text.

2. Press Ctrl+C.

The selection remains in your procedure, and a copy of it is placed on the

Clipboard.

Pasting Text
Once you have cut or copied material to the Clipboard, here's how to paste it into
your procedure at another location.

1. Position the insertion point where you want to place the contents of the
Clipboard.

2. Press Ctrl+V.

The contents of the Clipboard appear at the insertion point.

To delete a block of text and insert the contents of the Clipboard in its place,
combine the two operations by first selecting the text you want to remove and
then pressing Ctrl+V to replace it with the contents of the Clipboard.

Undoing Editing Operations

You can undo the most recent editing operation that produced a change in your
procedure, including:

The insertion of a series of characters

The insertion of a block of text from the Clipboard

The deletion of a series of characters

The deletion of a block of text

Docbasic User’s Guide 2-11

Editing Your Procedures Editing and Debugging Docbasic Procedures

You cannot undo operations that don't change your procedure, such as moving
the insertion point, selecting text, or copying material to the Clipboard.

To reverse the effect of the preceding editing operation, press Ctrl+Z.

Your procedure is restored to the way it was before you performed the editing
operation.

Adding Comments to a Procedure

You can add comments to your procedure to remind yourself or others of how
your code works. Comments are ignored when your procedure is executed.

In Docbasic, the apostrophe ( ' ) is used to indicate that text is a comment.

To add a full-line comment

Here's how to designate an entire line as a comment.

1. Type an apostrophe ( ' ) at the start of the line.

2. Type your comment following the apostrophe.

When your procedure is run, the apostrophe at the start of the line will cause the
entire line to be ignored.

To add a comment at the end of a line of code

Here's how to designate the last part of a line as a comment.

Although you can place a comment at the end of a line containing executable
code, you cannot place executable code at the end of a line containing a comment
because the apostrophe at the start of the comment will cause the balance of the
line (including the code) to be ignored.

1. Position the insertion point in the empty space beyond the end of the line of
code.

2. Type an apostrophe ( ' ).

3. Type your comment following the apostrophe.

When your procedure is run, the code on the first portion of the line will be
executed, but the apostrophe at the start of the comment will cause the remainder
of the line to be ignored.

2-12 Docbasic User’s Guide

Editing and Debugging Docbasic Procedures Editing Your Procedures

Breaking a Docbasic Statement across Multiple Lines

By default, a single Docbasic statement can extend only as far as the right margin,
and each line break represents a new statement. However, you can use a line-
continuation character to break a long statement across two or more lines.

Here's how to indicate that two or more lines of Docbasic code should be treated
as a single statement when your procedure is run.

1. Type the Docbasic statement on multiple lines.

2. Place the insertion point at the end of the first line.

3. Press the spacebar once to insert a single space.

4. Type an underscore ( _ ).

The underscore is the line-continuation character, which indicates that the

Docbasic statement continues on the following line.

5. Repeat steps 2-4 to place a line-continuation character at the end of each

line in the statement except the last.

When you run your procedure, the code on this series of lines will be executed as
a single Docbasic statement, just as if you had typed the entire statement on the
same line.

Searching and Replacing

Procedure Editor makes it easy to search for and replace specified text.

Finding Text in Your Procedure

Here's how to locate instances of specified text quickly anywhere within your
procedure.

1. Move the insertion point to where you want to start your search. (To start at
the beginning of your procedure, press Ctrl+Home.)

2. Press Ctrl+F.

Docbasic User’s Guide 2-13

Editing Your Procedures Editing and Debugging Docbasic Procedures

Procedure Editor displays the Find dialog box.

3. In the Find What field, type the text you want to find

4. Select the Match Case check box if you want the search to be case-
sensitive. Otherwise, the search will be case-insensitive.

5. Click Find Next or press Enter.

The Find dialog box remains displayed, and Procedure Editor either
highlights the first instance of the specified text or indicates that it cannot
be found. If the Find dialog box blocks your view of an instance of the
specified text, you can move the dialog box out of your way.

6. If the specified text has been found, repeat step 5 to search for the next
instance of it.

You can also click the Cancel button, which removes the Find dialog box while
maintaining the established search criteria, and then press F3 to find successive
occurrences of the specified text. If you press F3 when you have not previously
specified text for which you want to search, Procedure Editor displays the Find
dialog box so you can specify the desired text.

Replacing Text in a Procedure

Here's how to automatically replace either all instances or selected instances of

specified text.

1. Move the insertion point to where you want to start the replacement
operation. (To start at the beginning of your procedure, press Ctrl+Home.)

2. Choose the Replace command from the Search menu.

2-14 Docbasic User’s Guide

Editing and Debugging Docbasic Procedures Editing Your Procedures

Procedure Editor displays the Replace dialog box.

3. In the Find What field, type the text you want to replace.

4. In the Replace With field, type the replacement text.

5. Select the Match Case check box if you want the replacement operation to
be case-sensitive. Otherwise, it will be case-insensitive.

6. To replace all instances of the specified text, click Replace All.

Procedure Editor either replaces the specified text throughout your

procedure and indicates the number of occurrences it has changed, or it
indicates that the specified text cannot be found.

7. To replace selected instances of the specified text, click Find Next.

Procedure Editor either highlights the first instance of the specified text or
indicates that it cannot be found.

8. If the specified text has been found, either click Replace to replace that
instance of it or click Find Next to highlight the next instance (if any).

Each time you click Replace, Procedure Editor replaces that instance of the
specified text and automatically highlights the next instance.

Checking the Syntax of a Procedure

If you try to run or debug a procedure without first checking the syntax,
Procedure Editor performs a syntax check automatically.

Here's how to perform a syntax check manually when you are editing your
procedure, without having to run it.

1. From the Run menu, choose the Syntax Check command.

Procedure Editor either indicates that no errors have been found or

displays an error message that identifies the first line in your procedure
where an error has been found and briefly describes the nature of the error.

Docbasic User’s Guide 2-15

Editing Your Procedures Editing and Debugging Docbasic Procedures

2. Click OK or press Enter.

If Procedure Editor has found a syntax error, the line containing the error
is highlighted.

3. Correct the syntax error.

4. Repeat steps 1-3 until you have found and corrected all syntax errors.

2-16 Docbasic User’s Guide

Editing and Debugging Docbasic Procedures Running a Procedure

Running a Procedure

Once you have finished editing your procedure, you will want to run it to make
sure it performs the way you intended. You can pause or stop an executing
procedure.

During procedure execution, Procedure Editor's application window is available

only in a limited manner. Some of the menu commands may be disabled, and the
toolbar tools may be inoperative.

To run your procedure

To compile your procedure, if necessary, and then execute it, click the Start tool on
the toolbar or press F5.

The procedure is compiled (if it has not already been compiled), the focus is
switched to the parent window, and the procedure is executed.

To pause an executing procedure

To suspend the execution of a procedure that you are running, press Ctrl+Break.

Execution of the procedure is suspended, and the instruction pointer (a gray

highlight) appears on the line of code that will be executed next if you resume
running your procedure.

To stop an executing procedure

To stop the execution of a procedure that you are running, click the End tool on
the toolbar.

If you want to stop your procedure but find that the toolbar is currently
inoperative, press Ctrl+Break to pause your procedure, then click the End tool.

Docbasic User’s Guide 2-17

Debugging a Procedure Editing and Debugging Docbasic Procedures

Debugging a Procedure

This section presents some general information that will help you work most
effectively with Procedure Editor's debugging capabilities. It then explains how to
trace the execution of a procedure, how to set and remove breakpoints, and how
to add watch variables and modify their value.

Using the Docbasic Debugger

While you are debugging a procedure, you are actually executing the code line by
line. Therefore, to prevent any modifications to your procedure while it is being
run, the edit pane is read-only. You are free to move the insertion point
throughout the procedure, select text and copy it to the Clipboard as necessary, set
breakpoints, and add and remove watch variables, but you cannot change the
procedure until you stop running it.

To let you follow and control the debugging process, Procedure Editor displays an
instruction pointer on the line of code that is about to be executed—that is, the
line that will be executed next if you either proceed with the debugging process or
run your procedure. When the instruction pointer is on a line of code, the text on
that line appears in black on a gray background that spans the width of the entire
line.

Tracing Procedure Execution

Procedure Editor gives you two ways to trace procedure execution: single step
and procedure step. Both involve stepping through your procedure code line by
line. The distinction between the two is that the single step process traces into
calls to user-defined functions and subroutines, whereas the procedure step
process does not trace into these calls (although it does execute them).

To step through your procedure

Here's how to trace the execution of your procedure with either the single step or
procedure step method.

Note: Before Procedure Editor executes your procedure using either of these
methods, the procedure will first be compiled, if necessary. Therefore, there may be
a slight pause before execution actually begins. If your procedure contains any
compile errors, it will not be executed. To debug your procedure, first correct any
compile errors, then initiate execution again.

1. Click the Single Step or Procedure Step tool on the toolbar.

-Or-

Press F8 (Single Step) or Shift+F8 (Procedure Step).

2-18 Docbasic User’s Guide

Editing and Debugging Docbasic Procedures Debugging a Procedure

Procedure Editor places the instruction pointer on the sub main line of
your procedure.

2. To continue tracing the execution of your procedure line by line, repeat step
1.

Each time you repeat step 1, Procedure Editor executes the line at the
instruction pointer and moves the instruction pointer to the next line to be
executed.

3. When you finish tracing the steps of interest in your procedure, either click
the Start tool on the toolbar or press F5 to run the balance of the procedure,
or click the End tool to halt execution of the procedure.

To trace procedure calls

When you are stepping through a subroutine, you may need to determine the
procedure calls by which you arrived at a certain point in your procedure. Here's
how to use the Calls dialog box to obtain this information.

1. Click the Calls tool on the toolbar.

Procedure Editor displays the Calls dialog box, which lists the procedure
calls made by your procedure in the course of arriving at the present
subroutine.

2. From the Calls dialog box, select the name of the procedure you wish to
view

3. Click Show.

Procedure Editor highlights the currently executing line in the procedure

you selected, scrolling that line into view if necessary. (During this process,
the instruction pointer remains at its original location in the subroutine.)

To resume execution at another line within a subroutine

When you are stepping through a subroutine, you may want to repeat or skip
execution of a section of code. Here's how to use the Set Next Statement command
to move the instruction pointer to another line within that subroutine.

Docbasic User’s Guide 2-19

Debugging a Procedure Editing and Debugging Docbasic Procedures

You can only use the Set Next Statement command to move the instruction pointer
within the same subroutine. If you place the insertion point on a line that is not in
the same subroutine, the Set Next Statement command is disabled.

1. Place the insertion point in the line where you want to resume stepping
through the procedure.

2. From the Debug menu, choose the Set Next Statement command.

The instruction pointer moves to the line you selected, and you can resume
stepping through your procedure from there.

2-20 Docbasic User’s Guide

Editing and Debugging Docbasic Procedures Setting and Removing Breakpoints

Setting and Removing Breakpoints

If you want to start the debugging process at the first line of your procedure and
then step through your code line by line until you reach the end of the code that
you need to debug, the method described in the preceding section works fine. But
if you only need to debug one or more portions of a long procedure, that method
can be cumbersome.

An alternate strategy is to set one or more breakpoints at selected lines in your

procedure. Procedure Editor suspends execution of your procedure just before it
reaches a line containing a breakpoint, allowing you to step through the
procedure from that point.

Setting Breakpoints
You can set breakpoints to begin the debugging process partway through your
procedure, to continue debugging at a line outside the current subroutine, and to
debug only selected portions of your procedure.

Valid breakpoints can only be set on lines in your procedure that contain code,
including lines in functions and subroutines. Although you can set a breakpoint
anywhere within a procedure prior to execution, when you compile and run the
procedure, invalid breakpoints (that is, breakpoints on lines that don't contain
code) are automatically removed. While you are debugging your procedure,
Procedure Editor will beep if you try to set a breakpoint on a line that does not
contain code.

Note: Up to 255 lines in your procedure can contain breakpoints.

To debug selected portions of your procedure

If you only need to debug parts of your procedure, here's how to facilitate the task
by using breakpoints.

1. Place a breakpoint at the start of each portion of your procedure that you
want to debug.

2. To run the procedure, click the Start tool on the toolbar or press F5.

The procedure executes until it reaches the line containing the first
breakpoint and then pauses with the instruction pointer on that line.

3. Step through as much of the code as you need to.

4. To resume running your procedure, click the Start tool on the toolbar or press
F5.

The procedure executes until it reaches the line containing the second
breakpoint and then pauses with the instruction pointer on that line.

Docbasic User’s Guide 2-21

Setting and Removing Breakpoints Editing and Debugging Docbasic Procedures

5. Repeat steps 3 and 4 until you have finished debugging the selected
portions of your procedure.

To start debugging partway through a procedure

Here's how to begin the debugging process at a selected point in your procedure.

1. Place the insertion point in the line where you want to start debugging.

2. To set a breakpoint on that line, click the Toggle Breakpoint tool on the
toolbar.

-Or-

Press F9.

The line on which you set the breakpoint now appears in contrasting type.

3. Click the Start tool on the toolbar.

-Or-

Press F5.

Procedure Editor executes your procedure from the beginning and pauses
prior to executing the line containing the breakpoint. It places the
instruction pointer on that line to designate it as the line that will be
executed next.

4. If you want to continue debugging at another line in your procedure, use

the Set Next Statement command in the Debug menu to move the
instruction pointer to the desired line.

If you want to continue debugging at a line that isn't within the same subroutine,
use the procedure in the next section to move the pointer.

To move the pointer to a line outside the current subroutine

Here’s how to continue debugging starting with code outside the current
subroutine.

1. Place the insertion point in the line where you want to continue debugging.

2. To set a breakpoint on that line, press F9.

3. To run your procedure, click the Start tool on the toolbar or press F5.

The procedure executes until it reaches the line containing the breakpoint
and then pauses with the instruction pointer on that line. You can now
resume stepping through your procedure from that point.

2-22 Docbasic User’s Guide

Editing and Debugging Docbasic Procedures Setting and Removing Breakpoints

Removing Breakpoints
Breakpoints can be removed either manually or automatically.

Breakpoints are removed automatically in the following circumstances: (1) When

your procedure is compiled and executed, breakpoints are removed from lines
that don't contain code. (2) When you exit from Procedure Editor, all breakpoints
are cleared.

To remove a single breakpoint manually

Here's how to delete breakpoints manually one at a time.

1. Place the insertion point on the line containing the breakpoint that you want
to remove.

2. Click the Toggle Breakpoint tool on the toolbar.

-Or-

Press F9.

The breakpoint is removed, and the line no longer appears in contrasting

type.

To remove all breakpoints manually

Here's how to delete all breakpoints manually in a single operation.

1. Select the Clear All Breakpoints command from the Debug menu.

Procedure Editor removes all breakpoints from your procedure.

Docbasic User’s Guide 2-23

Using Watch Variables Editing and Debugging Docbasic Procedures

Using Watch Variables

As you debug your procedure, you can use Procedure Editor's watch pane to
monitor the variables on the watch variable list. Each time you enter break mode,
the values of the watch variables are updated. For each watch variable, Procedure
Editor displays the name of the variable, where it is defined, its value (if the
variable is not in scope, its value is shown as <not in context>), and other key
information such as its type and length (if it is a string).

The list of watch variables is maintained between procedure executions.

Depending on the implementation, it may also be maintained between
invocations of Procedure Editor.

You can only watch variables defined with fundamental data types, such as
Integer, Long, Variant, and so on; you cannot watch complex variables such as
structures or arrays. However, you can watch individual elements of arrays or
structure members using the following syntax.
[variable [(index,...)] [.member [(index,...)]]...]

where variable is the name of the structure or array variable, index is a literal
number, and member is the name of a structure member.

For example, the following are valid watch expressions:

Table 2-6 Example Watch Expressions

Watch Variable Description

a(1) Element 1 of array a

person.age Member age of structure person

company(10,23).person. Member age of structure person that is at element 10,23 within the array of
age structures called company

To add a watch variable

Here's how to add a variable to Procedure Editor's watch variable list.

1. Click the Add Watch tool on the toolbar.

-Or-

Press Shift+F9.

2-24 Docbasic User’s Guide

Editing and Debugging Docbasic Procedures Using Watch Variables

Procedure Editor displays the Add Watch dialog box.

2. Use the controls in the Context box to specify where the variable is defined
(locally, publicly, or privately) and, if it is defined locally, in which routine it is
defined.

3. In the Variable Name field, enter the name of the variable.

Note: If you are executing the procedure, use the drop-down Variable
Name list to display the names of all the variables that are "in scope," or
defined within the current function or subroutine, and select the variable
you want from that list.

4. Click OK or press Enter.

If this is the first variable you are placing on the watch variable list, the
watch pane opens far enough to display that variable. If the watch pane
was already open, it expands far enough to display the variable you just
added.

Note: Although you can add as many watch variables to the list as you want, the
watch pane only expands until it fills half of Procedure Editor's application
window. If your list of watch variables is longer than that, use the watch pane's
scroll bars to view hidden portions of the list.

To select a watch variable

In order to delete a variable from Procedure Editor's watch variable list or modify
the value of a variable on the list, you must first select the desired variable. Here's
how to select a variable on the list.

1. Use one of the following procedures:

a. Place the mouse pointer on the variable you want to select and click
the left mouse button.

-Or-

Docbasic User’s Guide 2-25

Using Watch Variables Editing and Debugging Docbasic Procedures

b. If one of the variables on the watch list is already selected, use the
arrow keys to move the selection highlight to a different variable.

-Or-

c. If the insertion point is in the edit pane, press F6 to highlight the most
recently selected variable on the watch list and then use the arrow keys
to move the selection highlight to a different variable.

2. To return the insertion point to its previous position in the edit pane, press F6
again.

To delete a watch variable

Here's how to delete a selected variable from Procedure Editor's watch variable
list.

1. Select the variable on the watch list.

2. Press Del.

The selected variable is removed from the watch list.

2-26 Docbasic User’s Guide

Editing and Debugging Docbasic Procedures Modifying the Value of a Variable

Modifying the Value of a Variable

When the debugger has control, you can modify the value of any of the variables
on Procedure Editor's watch variable list.

When you change the value of a variable, Procedure Editor converts the new
value to be of the same type as the variable being changed. For example, if you
change the value of an Integer variable to 1.7, Procedure Editor converts the
floating-point number to an Integer and assigns the value 2 to the variable.

When you modify a Variant variable, Procedure Editor needs to determine both
the type and value of the data. Procedure Editor uses the following logic to
perform this assignment (in this order):

Table 2-7 Results of Modifying a Variant

If the new value is Then

Null The variable is assigned Null (VarType 1)

Empty The variable is assigned Empty (VarType 0).

True The variable is assigned True (VarType 11).

False The variable is assigned False (VarType 11).

number The variable is assigned the value of number. The type of the variant is the
smallest data type that fully represents that number.
You can force the data type of the variable using a type-declarator letter
following number, such as %, #, &, !, or @.

date The variable is assigned the value of the new date (VarType 7)

Anything else The variable is assigned a String (VarType 8).

Procedure Editor will not assign a new value if it cannot be converted to the same
type as the specified variable.

To modify the value of a variable on the watch variable list

Here's how to change the value of a selected watch variable.

1. Use one of the following procedures:

a. Place the mouse pointer on the name of the variable whose value you
want to modify and double-click the left mouse button.

-Or-

b. Select the name of the variable whose value you want to modify and
press Enter or F2.

Docbasic User’s Guide 2-27

Modifying the Value of a Variable Editing and Debugging Docbasic Procedures

Procedure Editor displays the Modify Variable dialog box

Note: The name of the variable you selected appears in the Name field. If you
want to change a different variable, you can either enter the variable name in the
Name field or select the variable from the Variables list box, which shows the
names of all variables that are defined within the current function or subroutine.

When you use the Modify Variable dialog box to change the value of a variable,
you don't have to specify the context. Procedure Editor first searches locally for
the definition of that variable, then privately, then publicly.

2. Enter the new value for your variable in the Value field.

3. Click OK.

The new value of your variable appears on the watch variable list.

2-28 Docbasic User’s Guide

Editing and Debugging Docbasic Procedures Exiting from Procedure Editor

Exiting from Procedure Editor

What happens when you exit from Procedure Editor depends on (1) whether you
have made changes to your procedure and (2) whether your procedure contains
errors.

If you have made changes to your procedure, Procedure Editor displays a dialog
box asking whether you want to save the procedure. If you either click the No
button or click the Yes button and your procedure contains no errors, you exit from
Procedure Editor immediately. If you click the Yes button and your procedure
contains errors, Procedure Editor highlights the line containing the first error and
displays a dialog box asking whether you want to exit anyway. If you click the Yes
button, Procedure Editor saves your procedure, errors and all, and then you exit
from Procedure Editor.

If you haven't made any changes to your procedure, you exit from Procedure
Editor immediately, regardless of whether the procedure contains errors from a
previous editing session.

To exit from Procedure Editor, choose the Exit and Return command from the File
menu.

Docbasic User’s Guide 2-29

Menu Reference Editing and Debugging Docbasic Procedures

Menu Reference

File Menu
Table 2-8 File menu commands

Command Keyboard Shortcut Function

Exit and Return Esc Compiles your procedure and returns you to the
host application.

Edit Menu
Table 2-9 Edit menu commands

Command Keyboard Shortcut Function

Undo Ctrl+Z Reverses the preceding editing change.

Cut Ctrl+X Removes selected text from the procedure and

places it on the Clipboard.

Copy Ctrl+C Copies selected text without removing it from

the procedure and places it on the Clipboard.

Paste Ctrl+V Places the contents of the Clipboard at the

insertion point.

Delete Del or BkSp Removes selected text from the procedure.

Find... Ctrl+F Displays the Find dialog box, which allows you
to specify text for which you want to search.

Find Next F3 Searches for the next occurrence of previously

specified text. If you have not previously
specified text, displays the Find dialog box.

Replace... Displays the Replace dialog box, which allows

you to substitute replacement text for instances
of specified text.

Goto Line... F4 Displays the Goto Line dialog box, which allows
you to move the insertion point to the start of a
specified line in your procedure.

2-30 Docbasic User’s Guide

Editing and Debugging Docbasic Procedures Menu Reference

Run Menu
Table 2-10 Run menu commands

Command Keyboard Shortcut Function

Start F5 Begins execution of a procedure.

End Stops execution of a procedure.

Syntax Check Verifies the syntax of the statements in your

procedure by compiling it.

Debug Menu
Table 2-11 Debug menu commands

Command Keyboard Shortcut Function

Add Watch... Shift+F9 Displays the Add Watch dialog box, in which
you can enter the name of a Docbasic variable.
That variable, together with its value (if any), is
then displayed in the watch pane of Procedure
Editor's application window.

Delete Watch Del Deletes a selected variable from the watch

variable list.

Modify... Enter or F2 Displays the Modify Variable dialog box for a

selected variable, which enables you to modify
the value of that variable.

Single Step F8 Steps through the procedure line by line, tracing

into called procedures.

Procedure Step Shift+F8 Steps through the procedure line by line,

without tracing into called procedures.

Toggle Breakpoint F9 Toggles a breakpoint on the line containing the

insertion point.

Clear All Breakpoints Removes all breakpoints previously set with the
Toggle Breakpoint command.

Set Next Statement Enables you to place the instruction pointer on

another line within the current procedure and
resume procedure execution at that point.

Help Menu
Table 2-12 Help menu commands

Command Keyboard Shortcut Function

Contents Displays a list of major topics on which you can

obtain help.

Docbasic User’s Guide 2-31

Menu Reference Editing and Debugging Docbasic Procedures

Table 2-12 Help menu commands

Command Keyboard Shortcut Function

Search for Help on... Displays the Search dialog box, which allows
you to search for Help topics containing specific
keywords.

2-32 Docbasic User’s Guide

 3 A-Z Reference
This chapter of the Docbasic User’s Guide contains a complete, alphabetical listing
of all keywords in the Docbasic language. When syntax is described, the following
notations are used:

Table 3-1 Syntax Notation

Notation Description

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

text$ The presence of a type-declaration character following a parameter

signifies that the parameter must be a variable of that type or an
expression that evaluates to that type.
If a parameter does not appear with a type-declaration character, then
its type is described in the text.

[parameter] Square brackets indicate that the enclosed items are optional.
In Docbasic, you cannot end a statement with a comma, even if the
parameters are optional:
MsgBox "Hello",,"Message" 'OK
MsgBox "Hello",, 'Not valid

{Input | Binary} Braces indicate that you must choose one of the enclosed items, which
are separated by a vertical bar.

... Ellipses indicate that the preceeding expression can be repeated any
number of times.

Docbasic User’s Guide 3-1

& (operator) A-Z Reference

& (operator)

Returns the concatenation of expression1 and expression2.

Syntax
expression1 & expression2

Description
If both expressions are strings, then the type of the result is String. Otherwise, the
type of the result is a String variant.

When nonstring expressions are encountered, each expression is converted to a

String variant. If both expressions are Null, then a Null variant is returned. If only
one expression is Null, then it is treated as a zero-length string. Empty variants are
also treated as zero-length strings.

In many instances, the plus (+) operator can be used in place of &. The difference
is that + attempts addition when used with at least one numeric expression,
whereas & always concatenates.

Example
This example assigns a concatenated string to variable s$ and a string to s2$, then
concatenates the two variables.
Sub Main()
s$ = "This string" & " is concatenated"
s2$ = " with the & operator."
End Sub

Platform(s)
All.

See Also
+ (operator)
Operator Precedence (topic)

3-2 Docbasic User’s Guide

A-Z Reference ' (keyword)

' (keyword)

Causes the compiler to skip all characters between this character and the end of the
current line.

Syntax
'text

Description
This is very useful for commenting your code to make it more readable.

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

Platform(s)
All.

See Also
Rem (statement)
Comments (topic)

Docbasic User’s Guide 3-3

() (keyword) A-Z Reference

() (keyword)

Syntax 1
...(expression)...

Syntax 2
...,(parameter),...Description

Description

Parentheses within Expressions

Parentheses override the normal precedence order of Docbasic operators, forcing

a subexpression to be evaluated before other parts of the expression. For example,
the use of parentheses in the following expressions causes different results:
i = 1 + 2 * 3'Assigns 7.
i = (1 + 2) * 3'Assigns 9.

Use of parentheses can make your code easier to read, removing any ambiguity in
complicated expressions.

Parentheses Used in Parameter Passing

Parentheses can also be used when passing parameters to functions or subroutines

to force a given parameter to be passed by value, as shown below:
ShowForm i 'Pass i by reference.
ShowForm (i)'Pass i by value.

Enclosing parameters within parentheses can be misleading. For example, the

following statement appears to be calling a function called ShowForm without
assigning the result:
ShowForm(i)

The above statement actually calls a subroutine called ShowForm, passing it the
variable i by value. It may be clearer to use the ByVal keyword in this case, which
accomplishes the same thing:
ShowForm ByVal i

Note: The result of an expression is always passed by value.

3-4 Docbasic User’s Guide

A-Z Reference () (keyword)

Example
This example uses parentheses to clarify an expression.
Sub Main()
bill = False
dave = True
jim = True

If (dave And bill) Or (jim And bill) Then

Msgbox "The required parties for the meeting are here."
Else
MsgBox "Someone is late again!"
End If
End Sub

Platform(s)
All.

See Also
ByVal (keyword)
Operator Precedence (topic)

Docbasic User’s Guide 3-5

* (operator) A-Z Reference

* (operator)

Returns the product of expression1 and expression2.

Syntax
expression1 * expression2

Description
The result is the same type as the most precise expression, with the following
exceptions:

Table 3-2 Effect of Expression Type on Multiplication

If one expression is and the other then the type of the

expression is result is

Single Long Double

Boolean Boolean Integer

Date Date Double

When the * operator is used with variants, the following additional rules apply:

Empty is treated as 0.

If the type of the result is an Integer variant that overflows, then the result is
automatically promoted to a Long variant.

If the type of the result is a Single, Long, or Date variant that overflows, then
the result is automatically promoted to a Double variant.

If expression1 is Null and expression2 is Boolean, then the result is Empty.
Otherwise, If either expression is Null, then the result is Null.

Example
This example assigns values to two variables and their product to a third variable.
Sub Main()
s# = 123.55
t# = 2.55
u# = s# * t#
End Sub

3-6 Docbasic User’s Guide

A-Z Reference * (operator)

Platform(s)
All.

See Also
Operator Precedence (topic)

Docbasic User’s Guide 3-7

+ (operator) A-Z Reference

+ (operator)

Adds or concatenates two expressions.

Syntax
expression1 + expression2

Description
Addition operates differently depending on the type of the two expressions:

Table 3-3 Effect of Expression Type on Addition

If one expression is and the other then the type of the result is
expression is

Numeric Numeric Perform a numeric add (see below)

String String Concatenate, returning a string

Numeric String A Runtime error is generated

Variant String Concatenate, runing a String variant

Variant Numeric Perform a variant add (see below)

Empty variant Empty variant Return an Integer variant, value 0

Empty variant Any data type Return the non-Empty operand unchanged

Null variant Any data type Return Null

Variant Variant Add if either is numeric, else concatenate

When using + to concatenate two variants, the result depends on the types of each
variant at runtime. You can remove any ambiguity by using the & operator.

Numeric Add

A numeric add is performed when both expressions are numeric (i.e., not variant
or string). The result is the same type as the most precise expression, with the
exceptions shown in Table 3-4

Table 3-4 Effect of Expression Type on Numeric Addition

If one expression is and the other then the type of the

expression is result is

Single Long Double

3-8 Docbasic User’s Guide

A-Z Reference + (operator)

Table 3-4 Effect of Expression Type on Numeric Addition

If one expression is and the other then the type of the

expression is result is

Boolean Boolean Integer

A runtime error is generated if the result overflows its legal range.

Variant Add

If both expressions are variants, or one expression is numeric and the other
expression is Variant, then a variant add is performed. The rules for variant add are
the same as those for normal numeric add, with the following exceptions:

If the type of the result is an Integer variant that overflows, then the result is
a Long variant.

If the type of the result is a Long, Single, or Date variant that overflows, then
the result is a Double variant.

Example
This example assigns string and numeric variable values and then uses the +
operator to concatenate the strings and form the sums of numeric variables.
Sub Main()
i$ = "Concatenation" + " is fun!"
j% = 120 + 5 'Addition of numeric literals
k# = j% + 2.7 'Addition of numeric variable
MsgBox "This concatenation becomes: '" i$ + Str(j%) + Str(k#) & "'"
End Sub

Platform(s)
All.

See Also
& (operator)
Operator Precedence (topic)

Docbasic User’s Guide 3-9

- (operator) A-Z Reference

- (operator)

Returns the difference between expression1 and expression2 or, in the second syntax,
returns the negation of expression.

Syntax 1
expression1 - expression2

Syntax 2
-expression

Description

Syntax 1

The type of the result is the same as that of the most precise expression, with the
following exceptions:

Table 3-5 Effect of Expression Type on Subtraction

If one expression is and the other then the type of the

expression is result is

Long Single Double

Boolean Boolean Integer

A runtime error is generated if the result overflows its legal range.

When either or both expressions are Variant, then the following additional rules
apply:

If expression1 is Null and expression2 is Boolean, then the result is Empty.
Otherwise, if either expression is Null, then the result is Null.

Empty is treated as an Integer of value 0.

If the type of the result is an Integer variant that overflows, then the result is
a Long variant.

If the type of the result is a Long, Single, or Date variant that overflows, then
the result is a Double variant.

3-10 Docbasic User’s Guide

A-Z Reference - (operator)

Syntax 2

If expression is numeric, then the type of the result is the same type as expression,
with the following exception:

If expression is Boolean, then the result is Integer.

Note: In 2's compliment arithmetic, unary minus may result in an overflow with
Integer and Long variables when the value of expression is the largest negative
number representable for that data type. For example, the following generates an
overflow error:
Sub Main()
Dim a As Integer
a = -32768
a = -a 'Generates overflow here.
End Sub

When negating variants, overflow will never occur because the result will be
automatically promoted: integers to longs and longs to doubles.

Example
This example assigns values to two numeric variables and their difference to a
third variable, then displays the result.
Sub Main()
i% = 100
j# = 22.55
k# = i% - j#
MsgBox "The difference is: " & k#
End Sub

Platform(s)
All.

See Also
Operator Precedence (topic)

Docbasic User’s Guide 3-11

. (keyword) A-Z Reference

. (keyword)

Separates an object from a property or a structure from a structure member.

Syntax 1
object.property

Syntax 2
structure.member

Examples
This example uses the period to separate an object from a property.
Sub Main()
MsgBox Clipboard.GetText()
End Sub

This example uses the period to separate a structure from a member.

Type Rect
left As Integer
top As Integer
right As Integer
bottom As Integer
End Type

Sub Main()
Dim r As Rect
r.left = 10
r.right = 12
End Sub

Platform(s)
All.

See Also
Objects (topic)

3-12 Docbasic User’s Guide

A-Z Reference / (operator)

/ (operator)

Returns the quotient of expression1 and expression2.

Syntax
expression1 / expression2

Description
The type of the result is Double, with the following exceptions:

Table 3-6 Effect of Expression Type on Division

If one expression is and the other then the type of the

expression is result is

Integer Integer Single

Single Single Single

Boolean Boolean Single

A runtime error is generated if the result overflows its legal range.

When either or both expressions is Variant, then the following additional rules
apply:

If expression1 is Null and expression2 is Boolean, then the result is Empty.
Otherwise, if either expression is Null, then the result is Null.

Empty is treated as an Integer of value 0.

If both expressions are either Integer or Single variants and the result
overflows, then the result is automatically promoted to a Double variant.

Example
This example assigns values to two variables and their quotient to a third variable,
then displays the result.
Sub Main()
i% = 100
j# = 22.55
k# = i% / j#
MsgBox "The quotient of i/j is: " & k#
End Sub

Docbasic User’s Guide 3-13

/ (operator) A-Z Reference

Platform(s)
All.

See Also
\ (operator)
Operator Precedence (topic)

3-14 Docbasic User’s Guide

A-Z Reference < (operator)

< (operator)

See Comparison Operators (topic).

<= (operator)

See Comparison Operators (topic).

<> (operator)

See Comparison Operators (topic).

= (operator)

See Comparison Operators (topic).

> (operator)

See Comparison Operators (topic).

>= (operator)

See Comparison Operators (topic).

Docbasic User’s Guide 3-15

= (statement) A-Z Reference

= (statement)

Assigns the result of an expression to a variable.

Syntax
variable = expression

Description
When assigning expressions to variables, internal type conversions are performed
automatically between any two numeric quantities. Thus, you can freely assign
numeric quantities without regard to type conversions. However, it is possible for
an overflow error to occur when converting from larger to smaller types. This
occurs when the larger type contains a numeric quantity that cannot be
represented by the smaller type. For example, the following code will produce a
runtime error:
Dim amount As Long
Dim quantity As Integer

amount = 400123'Assign a value out of range for int.

quantity = amount'Attempt to assign to Integer.

When performing an automatic data conversion, underflow is not an error.

The assignment operator (=) cannot be used to assign objects. Use the Set statement
instead.

Example
Sub Main()
a$ = "This is a string"
b% = 100
c# = 1213.3443
MsgBox a$ & "," & b% & "," & c#
End Sub

Platform(s)
All.

See Also
Let (statement)
Operator Precedence (topic)

3-16 Docbasic User’s Guide

A-Z Reference = (statement)

Set (statement)
Expression Evaluation (topic)

Docbasic User’s Guide 3-17

\ (operator) A-Z Reference

\ (operator)

Returns the integer division of expression1 and expression2.

Syntax
expression1 \ expression2

Description
Before the integer division is performed, each expression is converted to the data
type of the most precise expression. If the type of the expressions is either Single,
Double, Date, or Currency, then each is rounded to Long.

If either expression is a Variant, then the following additional rules apply:

If either expression is Null, then the result is Null.

Empty is treated as an Integer of value 0.

Example
This example assigns the quotient of two literals to a variable and displays the
result.
Sub Main()
s% = 100.99 \ 2.6
MsgBox "Integer division of 100.99\2.6 is: " & s%
End Sub

Platform(s)
All.

See Also
/ (operator)
Operator Precedence (topic)

3-18 Docbasic User’s Guide

A-Z Reference ^ (operator)

^ (operator)

Returns expression1 raised to the power specified in expression2.

Syntax
expression1 ^ expression2

Description
The following are special cases:

Table 3-7 Special Exponents

Special Case Value

n^0 1

0^-n undefined

0^+n 0

1^n 1

The type of the result is always Double, except with Boolean expressions, in which
case the result is Boolean. Fractional and negative exponents are allowed. If either
expression is a Variant containing Null, then the result is Null.

Raising a number to a negative exponent produces a fractional result.

Example
Sub Main()
s# = 2 ^ 5 'Returns 2 to the 5th power.
r# = 16 ^ .5'Returns the square root of 16.
MsgBox "2 to the 5th power is: " & s#
MsgBox "The square root of 16 is: " & r#
End Sub

Platform(s)
All.

See Also
Operator Precedence (topic)

Docbasic User’s Guide 3-19

_ (keyword) A-Z Reference

_ (keyword)

Line-continuation character, which allows you to split a single Docbasic statement

onto more than one line.

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

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

The line-continuation character can be followed by a comment, as shown below:

i = 5 + 6 & _'Continue on the next line.
"Hello"

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

Sub Main()
'The line-continuation operator is useful when concatenating
'long strings.

msg = "This line is a line of text that" + crlf + "extends" _

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

'It is also useful for separating and continuing long calculation lines.

b# = .124
a# = .223
s# = ( (((Sin(b#) ^ 2) + (Cos(a#) ^ 2)) ^ .5) / _
(((Sin(a#) ^ 2) + (Cos(b#) ^ 2)) ^ .5) ) * 2.00
MsgBox msg & crlf & "The value of s# is: " & s#
End Sub

Platform(s)
All.

3-20 Docbasic User’s Guide

A-Z Reference Abs (function)

Abs (function)

Returns the absolute value of expression.

Syntax
Abs(expression)

Description
If expression is Null, then Null is returned. Empty is treated as 0.

The type of the result is the same as that of expression, with the following
exceptions:

If expression is an Integer that overflows its legal range, then the result is
returned as a Long. This only occurs with the largest negative Integer:
Dim a As Variant
Dim i As Integer
i = -32768
a = Abs(i) 'Result is a Long.
i = Abs(i) 'Overflow!

If expression is a Long that overflows its legal range, then the result is
returned as a Double. This only occurs with the largest negative Long:
Dim a As Variant
Dim l As Long
l = -2147483648
a = Abs(l) 'Result is a Double.
l = Abs(l) 'Overflow!

If expression is a Currency value that overflows its legal range, an overflow

error is generated.

Example
This example assigns absolute values to variables of four types and displays the
result.
Sub Main()
s1% = Abs(- 10.55)
s2& = Abs(- 10.55)
s3! = Abs(- 10.55)
s4# = Abs(- 10.55)
MsgBox "The absolute values are: " & s1% & "," & s2& & "," & s3! & "," & s4#
End Sub

Docbasic User’s Guide 3-21

Abs (function) A-Z Reference

Platform(s)
All.

See Also
Sgn (function)

3-22 Docbasic User’s Guide

A-Z Reference And (operator)

And (operator)

Performs a logical or binary conjunction on two expressions.

Syntax
expression1 And expression2

Description
If both expressions are either Boolean, Boolean variants, or Null variants, then a
logical conjunction is performed as follows:

Table 3-8 Effects of Boolean and Null Expressions on the And Operator

If the first expression and the second Then the result is

is expression is

True True True

True False False

True Null Null

False True False

False False False

False Null Null

Null True Null

Null False False

Null Null Null

Binary Conjunction

If the two expressions are Integer, then a binary conjunction is performed,

returning an Integer result. All other numeric types (including Empty variants) are
converted to Long, and a binary conjunction is then performed, returning a Long
result.

Binary conjunction forms a new value based on a bit-by-bit comparison of the

binary representations of the two expressions according to the following table:

Table 3-9 Binary Conjunction

1 And 1 = 1

Docbasic User’s Guide 3-23

And (operator) A-Z Reference

Table 3-9 Binary Conjunction

0 And 1 = 0

1 And 0 = 0

0 And 0 = 0

Example
Sub Main()
n1 = 1001
n2 = 1000
b1 = True
b2 = False
'This example performs a numeric bitwise And operation and stores the
'result in N3.
n3 = n1 And n2

'This example performs a logical And comparing B1 and B2 and displays the
'result.
If b1 And b2 Then
MsgBox "b1 and b2 are True; n3 is: " & n3
Else
MsgBox "b1 and b2 are False; n3 is: " & n3
End If
End Sub

Platform(s)
All.

See Also
Operator Precedence (topic)
Or (operator)
Xor (operator)
Eqv (operator)
Imp (operator)

3-24 Docbasic User’s Guide

A-Z Reference Any (data type)

Any (data type)

Description
Used with the Declare statement to indicate that type checking is not to be
performed with a given argument.

Example
Given the following declaration:
Declare Sub Foo Lib "FOO.DLL" (a As Any)

the following calls are valid:

Foo 10
Foo "Hello, world."

Platform(s)
All.

See Also
Declare (statement)

Docbasic User’s Guide 3-25

ArrayDims (function) A-Z Reference

ArrayDims (function)

Returns an Integer containing the number of dimensions of a given array.

Syntax
ArrayDims(arrayvariable)

Description
This function can be used to determine whether a given array contains any
elements or if the array is initially created with no dimensions and then
redimensioned by another function, such as the FileList function, as shown in the
following example.

Example
This example allocates an empty (null-dimensioned) array; fills the array with a list
of filenames, which resizes the array; then tests the array dimension and displays
an appropriate message.
Sub Main()
Dim f$()
FileList f$,"c:\*.bat"
If ArrayDims(f$) = 0 Then
MsgBox "The array is empty."
Else
MsgBox "The array size is: " & (UBound(f$) - UBound(f$) + 1)
End If
End Sub

Platform(s)
All.

See Also
LBound (function)
UBound (function)
Arrays (topic)

3-26 Docbasic User’s Guide

A-Z Reference Arrays (topic)

Arrays (topic)

Declaring Array Variables

Arrays in Docbasic are declared using any of the following statements:
Dim
Public
Private

For example:
Dim a(10) As Integer
Public LastNames(1 to 5,-2 to 7) As Variant
Private

Arrays of any data type can be created, including Integer, Long, Single, Double,
Boolean, Date, Variant, Object, user-defined structures, and data objects.

The lower and upper bounds of each array dimension must be within the
following range:
-32768 <= bound <= 32767

Arrays can have up to 60 dimensions.

Arrays can be declared as either fixed or dynamic, as described below.

Fixed Arrays
The dimensions of fixed arrays cannot be adjusted at execution time. Once
declared, a fixed array will always require the same amount of storage. Fixed
arrays can be declared with the Dim, Private, or Public statement by supplying
explicit dimensions. The following example declares a fixed array of ten strings:
Dim a(10) As String

Fixed arrays can be used as members of user-defined data types. The following
example shows a structure containing fixed-length arrays:
Type Foo
rect(4) As Integer
colors(10) As Integer
End Type

Only fixed arrays can appear within structures.

Dynamic Arrays
Dynamic arrays are declared without explicit dimensions, as shown below:

Docbasic User’s Guide 3-27

Arrays (topic) A-Z Reference

Public Ages() As Integer

Dynamic arrays can be resized at execution time using the Redim statement:
Redim Ages$(100)

Subsequent to their initial declaration, dynamic arrays can be redimensioned any

number of times. When redimensioning an array, the old array is first erased unless
you use the Preserve keyword, as shown below:
Redim Preserve Ages$(100)

Dynamic arrays cannot be members of user-defined data types.

Passing Arrays
Arrays are always passed by reference.

Querying Arrays
The following table describes the functions used to retrieve information about
arrays.

Table 3-10 Functions Used to Retrieve Information from Arrays

Use this function To

LBound Retrieve the lower bound of an array. A runtime is generated if the

array has no dimensions.

UBound Retrieve the upper bond of an array. A runtime error is generated if

the array has no dimensions.

ArrayDims Retrieve the number of dimensions of an array. This function returns

0 if the array has no dimensions.

Operations on Arrays
The following table describes the function that operate on arrays:

Table 3-11 Functions Used to Operate on Arrays

Use the command To

ArraySort Sort an array of integers, longs, singles, doubles, currency, Booleans,

dates, or variants.

FileList Fill an array with a list of files in a given directory.

DiskDrives Fill an array with a list of valid drive letters.

3-28 Docbasic User’s Guide

A-Z Reference Arrays (topic)

Table 3-11 Functions Used to Operate on Arrays

Use the command To

ReadInSection Fill an array with the item names from a section in an INI file.

FileDirs Fill an array with a list of subdirectories.

Erase Erase all the elements of an array.

ReDim Establish the bounds and dimensions of an array.

Dim Declare an array.

Docbasic User’s Guide 3-29

ArraySort (statement) A-Z Reference

ArraySort (statement)

Sorts a single-dimensioned array in ascending order.

Syntax
ArraySort array()

Description
If a string array is specified, then the routine sorts alphabetically in ascending
order using case-sensitive string comparisons. If a numeric array is specified, the
ArraySort statement sorts smaller numbers to the lowest array index locations.

Docbasic generates a runtime error if you specify an array with more than one
dimension.

When sorting an array of variants, the following rules apply:

A runtime error is generated if any element of the array is an object.

String is greater than any numeric type.

Null is less than String and all numeric types.

Empty is treated as a number with the value 0.

String comparison is case-sensitive (this function is not affected by the
Option Compare setting).

Example
This example dimensions an array and fills it with filenames using FileList, then
sorts the array and displays it in a select box.
Sub Main()
Dim f$()
FileList f$,"c:\*.*"
ArraySort f$
End Sub

Platform(s)
All.

3-30 Docbasic User’s Guide

A-Z Reference ArraySort (statement)

See Also
ArrayDims (function)
LBound (function)
UBound (function)

Docbasic User’s Guide 3-31

Asc (function) A-Z Reference

Asc (function)

Returns an Integer containing the numeric code for the first character of text$.

Syntax
Asc(text$)

Description
The return value is an integer between 0 and 255.

Example
This example fills an array with the ASCII values of the strings components and
displays the result.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
s$ = InputBox("Please enter a string.","Enter String")
If s$ = "" Then End'Exit if no string entered.
For i = 1 To Len(s$)
msg = msg & Asc(Mid$(s$,i,1)) & crlf
Next i
MsgBox "The Asc values of the string are:" & msg
End Sub

Platform(s)
All.

See Also
Chr, Chr$ (functions)

3-32 Docbasic User’s Guide

A-Z Reference Atn (function)

Atn (function)

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

Syntax
Atn(number)

Description
Some helpful conversions:

Pi (3.1415926536) radians = 180 degrees.

1 radian = 57.2957795131 degrees.

1 degree = .0174532925 radians.

Example
This example finds the angle whose tangent is 1 (45 degrees) and displays the
result.
Sub Main()
a# = Atn(1.00)
MsgBox "1.00 is the tangent of " & a# & " radians (45 degrees)."
End Sub

Platform(s)
All.

See Also
Tan (function)
Sin (function)
Cos (function)

Docbasic User’s Guide 3-33

Basic.Capability (method) A-Z Reference

Basic.Capability (method)

Returns True if the specified capability exists on the current platform; returns False
otherwise.

Syntax
Basic.Capability(which)

Description
The which parameter is an Integer specifying the capability for which to test. It can
be any of the following values:

Table 3-12 Values of the Which Parameter

Value Returns True If the Platform Supports

1 Disk drives

2 System file attribute (ebSystem)

3 Hidden file attribute (ebHidden)

4 Volume label file attribute (ebVolume)

5 Archive file attribute (ebArchive)

6 Denormalized floating-point math

7 File locking (i.e., the Lock and Unlock statements)

8 Big endian byte ordering

Example
This example tests to see whether your current platform supports disk drives and
hidden file attributes and displays the result.
Sub Main()
msg = "This operating system "

If Basic.Capability(1) Then
msg = msg & "supports disk drives."
Else
msg = msg & "does not support disk drives."
End If

MsgBox msg
End Sub

3-34 Docbasic User’s Guide

A-Z Reference Basic.Capability (method)

Platform(s)
All.

See Also
Cross-Platform Procedures (topic)
Basic.OS (property)

Docbasic User’s Guide 3-35

Basic.Eoln$ (property) A-Z Reference

Basic.Eoln$ (property)

Returns a String containing the end-of-line character sequence appropriate to the

current platform.

Syntax
Basic.Eoln$

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

Example
This example writes two lines of text in a message box.
Sub Main()
MsgBox "This is the first line of text." & Basic.Eoln$ & "This is the
second line of text."
End Sub

Platform(s)
All.

See Also
Cross-Platform Procedures (topic)
Basic.PathSeparator$ (property)

3-36 Docbasic User’s Guide

A-Z Reference Basic.FreeMemory (property)

Basic.FreeMemory (property)

Returns a Long representing the number of bytes of free memory in Docbasic's data
space.

Syntax
Basic.FreeMemory

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

Docbasic's data space contains strings and dynamic arrays.

Example
This example displays free memory in a dialog box.
Sub Main()
MsgBox "The largest free memory block is: " & Basic.FreeMemory
End Sub

Platform(s)
All.

See Also
Basic.FreeMemory (property)

Docbasic User’s Guide 3-37

Basic.HomeDir$ (property) A-Z Reference

Basic.HomeDir$ (property)

Returns a String specifying the directory containing Docbasic.

Syntax
Basic.HomeDir$

Description
This method is used to find the directory in which the Docbasic files are located.

Example
This example assigns the home directory to HD and displays it.
Sub Main()
hd$ = Basic.HomeDir$
MsgBox "The Docbasic home directory is: " & hd$
End Sub

Platform(s)
All.

3-38 Docbasic User’s Guide

A-Z Reference Basic.OS (property)

Basic.OS (property)

Returns an Integer indicating the current platform.

Syntax
Basic.OS

Description
Table 3-13 Values of the Basic.OS Property

Value Constant Platform

0 ebWin16 Microsoft Windows

1 ebDOS16 MS-DOS (16-bit edition)

2 edWin32 Microsoft Windows 95

Microsoft Windows NT Workstation (Intel, Alpha,
AXP, MIPS,)
Microsoft Windows NT Server (Intel, Alpha, AXP,
MIPS)
Microsoft Win32s running under Windows 3.1

3 ebSolaris Sun Solaris 2.x

4 ebSunOS SunOS

5 ebHPUX HP/UX

8 ebAIX IBM AIX

10 ebMacintosh Apple Macintosh

The value returned is not necessarily the platform under which Docbasic is
running but rather an indicator of the platform for which Docbasic was created.
For example, it is possible to run Docbasic for Windows under Windows NT
Workstation. In this case, Basic.OS will return 0.

Example
This example determines whether the currently-running operating system is
Windows or DOS and displays the appropriate message.
Sub Main()
Select Case Basic.OS
Case ebWin16
s = "Windows"
Case ebDOS16

Docbasic User’s Guide 3-39

Basic.OS (property) A-Z Reference

s = "DOS"
Case Else
s = "not Windows or DOS"
End Select
MsgBox "You are currently running " & s
End Sub

Platform(s)
All.

See Also
Cross-Platform Procedures (topic)

3-40 Docbasic User’s Guide

A-Z Reference Basic.PathSeparator$ (property)

Basic.PathSeparator$ (property)

Returns a String containing the path separator appropriate for the current
platform.

Syntax
Basic.PathSeparator$

Description
The returned string is any one of the following characters: / (slash), \ (back slash),
: (colon)

Example
Sub Main()
MsgBox "The path separator for this platform is: " & Basic.PathSeparator$
End Sub

Platform(s)
All.

See Also
Basic.Eoln$ (property)
Cross-Platform Procedures (topic)

Docbasic User’s Guide 3-41

Basic.Version$ (property) A-Z Reference

Basic.Version$ (property)

Returns a String containing the version of Docbasic.

Syntax
Basic.Version$

Description
This function returns the major and minor version numbers in the format
major.minor.BuildNumber, as in "2.00.30."

Example
This example displays the current version of Docbasic.
Sub Main()
MsgBox "Version " & Basic.Version$ & " of Docbasic is running"
End Sub

Platform(s)
All.

3-42 Docbasic User’s Guide

A-Z Reference Beep (statement)

Beep (statement)

Makes a single system beep.

Syntax
Beep

Example
This example causes the system to beep five times and displays a reminder
message.
Sub Main()
For i = 1 To 5
Beep
Sleep(200)
Next i
MsgBox "You have an upcoming appointment!"
End Sub

Platform(s)
All.

Docbasic User’s Guide 3-43

Boolean (data type) A-Z Reference

Boolean (data type)

A data type capable of representing the logical values True and False.

Syntax
Boolean

Description
Boolean variables are used to hold a binary value--either True or False. Variables
can be declared as Boolean using the Dim, Public, or Private statement.

Variants can hold Boolean values when assigned the results of comparisons or the
constants True or False.

Internally, a Boolean variable is a 2-byte value holding -1 (for True) or 0 (for False).

Any type of data can be assigned to Boolean variables. When assigning, non-0
values are converted to True, and 0 values are converted to False.

When appearing as a structure member, Boolean members require 2 bytes of

storage.

When used within binary or random files, 2 bytes of storage are required.

When passed to external routines, Boolean values are sign-extended to the size of
an integer on that platform (either 16 or 32 bits) before pushing onto the stack.

There is no type-declaration character for Boolean variables.

Boolean variables that have not yet been assigned are given an initial value of False.

Platform(s)
All.

See Also
Currency (data type)
Date (data type)
Double (data type)
Integer (data type)
Long (data type)
Object (data type)

3-44 Docbasic User’s Guide

A-Z Reference Boolean (data type)

Single (data type)

String (data type)
Variant (data type)
DefType (statement)
CBool (function)
True (constant)
False (constant)

Docbasic User’s Guide 3-45

ByRef (keyword) A-Z Reference

ByRef (keyword)

Used within the Sub...End Sub, Function...End Function, or Declare statement to

specify that a given parameter can be modified by the called routine.

Syntax
...,ByRef parameter,...

Description
Passing a parameter by reference means that the caller can modify that variable's
value.

Unlike the ByVal keyword, the ByRef keyword cannot be used when passing a
parameter. The absence of the ByVal keyword is sufficient to force a parameter to
be passed by reference:
MySub ByVal i Pass i by value.
MySub ByRef i Illegal (will not compile).
MySub i Pass i by reference.

Example
Sub Test(ByRef a As Variant)
a = 14
End Sub

Sub Main()
b = 12
Test b
MsgBox "The ByRef value is: " & b'Displays 14.
End Sub

Platform(s)
All.

See Also
() (keyword)
ByVal (keyword)

3-46 Docbasic User’s Guide

A-Z Reference ByVal (keyword)

ByVal (keyword)

Forces a parameter to be passed by value rather than by reference.

Syntax
...ByVal parameter...

Description
The ByVal keyword can appear before any parameter passed to any function,
statement, or method to force that parameter to be passed by value. Passing a
parameter by value means that the caller cannot modify that variable's value.

Enclosing a variable within parentheses has the same effect as the ByVal keyword:
Foo ByVal iForces i to be passed by value.
Foo(i)Forces i to be passed by value.

When calling external statements and functions (i.e., routines defined using the
Declare statement), the ByVal keyword forces the parameter to be passed by value
regardless of the declaration of that parameter in the Declare statement. The
following example shows the effect of the ByVal keyword used to passed an
Integer to an external routine:
Declare Sub Foo Lib "MyLib" (ByRef i As Integer)

i% = 6
Foo ByVal i% 'Pass a 2-byte Integer.
Foo i% 'Pass a 4-byte pointer to an Integer.

Since the Foo routine expects to receive a pointer to an Integer, the first call to Foo
will have unpredictable results.

Example
This example demonstrates the use of the ByVal keyword.
Sub Foo(a As Integer)
a = a + 1
End Sub

Sub Main()
Dim i As Integer
i = 10
Foo i
MsgBox "The ByVal value is: " & i'Displays 11 (Foo changed the value).
Foo ByVal i
MsgBox "The Byval value is still: " & i'Displays 11 (Foo did not change
the value).
End Sub

Docbasic User’s Guide 3-47

ByVal (keyword) A-Z Reference

Platform(s)
All.

See Also
() (keyword)
ByRef (keyword)

3-48 Docbasic User’s Guide

A-Z Reference Call (statement)

Call (statement)

Transfers control to the given subroutine, optionally passing the specified

arguments.

Syntax
Call subroutine_name [(arguments)]

Description
Using this statement is equivalent to:

subroutine_name [arguments]

Use of the Call statement is optional. The Call statement can only be used to
execute subroutines; functions cannot be executed with this statement. The
subroutine to which control is transferred by the Call statement must be declared
outside of the Main procedure, as shown in the following example.

Example
This example demonstrates the use of the Call statement to pass control to another
function.
Sub Example_Call(s$)
'This subroutine is declared externally to Main and displays the text
'passed in the parameter s$.
MsgBox "Call: " & s$
End Sub

Sub Main()
'This example assigns a string variable to display, then calls subroutine
'Example_Call, passing parameter S$ to be displayed in a message box
'within the subroutine.
s$ = "DAVE"
Example_Call s$
Call Example_Call("SUSAN")
End Sub

Platform(s)
All.

Docbasic User’s Guide 3-49

Call (statement) A-Z Reference

See Also
Goto (statement)
GoSub (statement)
Declare (statement)

3-50 Docbasic User’s Guide

A-Z Reference CBool (function)

CBool (function)

Converts expression to True or False, returning a Boolean value.

Syntax
CBool(expression)

Description
The expression parameter is any expression that can be converted to a Boolean. A
runtime error is generated if expression is Null.

All numeric data types are convertible to Boolean. If expression is zero, then the
CBool returns False; otherwise, CBool returns True. Empty is treated as False.

If expression is a String, then CBool first attempts to convert it to a number, then

converts the number to a Boolean. A runtime error is generated if expression cannot
be converted to a number.

A runtime error is generated if expression cannot be converted to a Boolean.

Example
This example uses CBool to determine whether a string is numeric or just plain
text.
Sub Main()
Dim IsNumericOrDate As Boolean
s$ = "34224.54"
IsNumericOrDate = CBool(IsNumeric(s$) Or IsDate(s$))
If IsNumericOrDate = True Then
MsgBox s$ & " is either a valid date or number!"
Else
MsgBox s$ & " is not a valid date or number!"
End If
End Sub

Platform(s)
All.

See Also
CCur (function)
CDate, CVDate (functions)

Docbasic User’s Guide 3-51

CBool (function) A-Z Reference

CDbl (function)
CInt (function)
CLng (function)
CSng (function)
CStr (function)
CVar (function)
CVErr (function)
Boolean (data type)

3-52 Docbasic User’s Guide

A-Z Reference CCur (function)

CCur (function)

Converts any expression to a Currency.

Syntax
CCur(expression)

Description
This function accepts any expression convertible to a Currency, including strings.
A runtime error is generated if expression is Null or a String not convertible to a
number. Empty is treated as 0.

When passed a numeric expression, this function has the same effect as assigning
the numeric expression number to a Currency.

When used with variants, this function guarantees that the variant will be assigned
a Currency (VarType 6).

Example
This example displays the value of a String converted into a Currency value.
Sub Main()
i$ = "100.44"
MsgBox "The currency value is: " & CCur(i$)
End Sub

Platform(s)
All.

See Also
CBool (function)
CDate, CVDate (functions)
CDbl (function)
CInt (function)
CLng (function)
CSng (function)
CStr (function)
CVar (function)
CVErr (function)
Currency (data type)

Docbasic User’s Guide 3-53

CDate, CVDate (functions) A-Z Reference

CDate, CVDate (functions)

Converts expression to a date, returning a Date value.

Syntax
CDate(expression)

CVDate(expression)

Description
The expression parameter is any expression that can be converted to a Date. A
runtime error is generated if expression is Null.

If expression is a String, an attempt is made to convert it to a Date using the current

country settings. If expression does not represent a valid date, then an attempt is
made to convert expression to a number. A runtime error is generated if expression
cannot be represented as a date.

These functions are sensitive to the date and time formats of your computer.

The CDate and CVDate functions are identical.

Example
This example takes two dates and computes the difference between them.
Sub Main()
Dim date1 As Date
Dim date2 As Date
Dim diff As Date

date1 = CDate(#1/1/1994#)
date2 = CDate("February 1, 1994")
diff = DateDiff("d",date1,date2)

MsgBox "The date difference is " & CInt(diff) & " days."
End Sub

Platform(s)
All.

3-54 Docbasic User’s Guide

A-Z Reference CDate, CVDate (functions)

See Also
CCur (function)
CBool (function)
CDbl (function)
CInt (function)
CLng (function)
CSng (function)
CStr (function)
CVar (function)
CVErr (function)
Date (data type)

Docbasic User’s Guide 3-55

CDbl (function) A-Z Reference

CDbl (function)

Converts any expression to a Double.

Syntax
CDbl(expression)

Description
This function accepts any expression convertible to a Double, including strings. A
runtime error is generated if expression is Null. Empty is treated as 0.0.

When passed a numeric expression, this function has the same effect as assigning
the numeric expression number to a Double.

When used with variants, this function guarantees that the variant will be assigned
a Double (VarType 5).

Example
This example displays the result of two numbers as a Double.
Sub Main()
i% = 100
j! = 123.44
MsgBox "The double value is: " & CDbl(i% * j!)
End Sub

Platform(s)
All.

See Also
CCur (function)
CBool (function)
CDate, CVDate (functions)
CInt (function)
CLng (function)
CSng (function)
CStr (function)
CVar (function)
CVErr (function)
Double (data type)

3-56 Docbasic User’s Guide

A-Z Reference ChDir (statement)

ChDir (statement)

Changes the current directory of the specified drive to newdir$. This routine will
not change the current drive. (See ChDrive (statement).)

Syntax
ChDir newdir$

Example
This example saves the current directory, then changes to the root directory,
displays the old and new directories, restores the old directory, and displays it.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
save$ = CurDir$
ChDir (Basic.PathSeparator$)
MsgBox "Old: " & save$ & crlf & "New: " & CurDir$
ChDir (save$)
MsgBox "Directory restored to: " & CurDir$
End Sub

Platform(s)
All.

Platform Notes: UNIX

UNIX platforms do not support drive letters.

Platform Notes: Macintosh

The Macintosh does not support drive letters.

The Macintosh uses the colon (":") as the path separator. A double colon ("::")
specifies the parent directory.

See Also
ChDrive (statement)
CurDir, CurDir$ (functions)
Dir, Dir$ (functions)

Docbasic User’s Guide 3-57

ChDir (statement) A-Z Reference

MkDir (statement)
RmDir (statement)

3-58 Docbasic User’s Guide

A-Z Reference ChDrive (statement)

ChDrive (statement)

Changes the default drive to the specified drive.

Syntax
ChDrive DriveLetter$

Description
Only the first character of DriveLetter$ is used.

DriveLetter$ is not case-sensitive.

If DriveLetter$ is empty, then the current drive is not changed.

Example
This example saves the current directory in CD, then extracts the current drive
letter and saves it in Save$. If the current drive is D, then it is changed to C;
otherwise, it is changed to D. Then the saved drive is restored and displayed.
Const crlf$ = Chr$(13) + Chr$(10)

Sub Main()
cd$ = CurDir$
save$ = Mid$(CurDir$,1,1)
If save$ = "D" Then
ChDrive("C")
Else
ChDrive("D")
End If
MsgBox "Old: " & save$ & crlf & "New: " & CurDir$
ChDrive (save$)
MsgBox "Directory restored to: " & CurDir$
End Sub

Platform(s)
Windows, Win32.

Platform Notes: UNIX, Macintosh

UNIX platforms and the Macintosh do not support drive letters.

Docbasic User’s Guide 3-59

ChDrive (statement) A-Z Reference

See Also
ChDir (statement)
CurDir, CurDir$ (functions)
Dir, Dir$ (functions)
MkDir (statement)
RmDir (statement)
DiskDrives (statement)

3-60 Docbasic User’s Guide

A-Z Reference Choose (function)

Choose (function)

Returns the expression at the specified index position.

Syntax
Choose(index,expression1,expression2,...,expression13)

Description
The index parameter specifies which expression is to be returned. If index is 1, then
expression1 is returned; if index is 2, then expression2 is returned, and so on. If index
is less than 1 or greater than the number of supplied expressions, then Null is
returned.

The Choose function returns the expression without converting its type. Each
expression is evaluated before returning the selected one.

Example
This example assigns a variable of indeterminate type to a.
Sub Main()
Dim a As Variant
Dim c As Integer
c% = 2
a = Choose(c%,"Hello, world",#1/1/94#,5.5,False)
MsgBox "Item " & c% & " is '" & a & "'"'Displays the date passed as
parameter 2.
End Sub

Platform(s)
All.

See Also
Switch (function)
IIf (function)
If...Then...Else (statement)
Select...Case (statement)

Docbasic User’s Guide 3-61

Chr, Chr$ (functions) A-Z Reference

Chr, Chr$ (functions)

Returns the character whose value is Code.

Syntax
Chr[$](Code)

Description
Code must be an Integer between 0 and 255.

Chr$ returns a string, whereas Chr returns a String variant.

The Chr$ function can be used within constant declarations, as in the following
example:
Const crlf = Chr$(13) + Chr$(10)

Some common uses of this function are:

Chr$(9) Tab
Chr$(13) + Chr$(10)End-of-line (carriage return, linefeed)
Chr$(26)End-of-file
Chr$(0)Null

Example
Sub Main()
'Concatenates carriage return (13) and line feed (10) to CRLF$,
'then displays a multiple-line message using CRLF$ to separate lines.
crlf$ = Chr$(13) + Chr$(10)
MsgBox "First line." & crlf$ & "Second line."

'Fills an array with the ASCII characters for ABC and displays their
'corresponding characters.
Dim a%(2)
For i = 0 To 2
a%(i) = (65 + i)
Next i
MsgBox "The first three elements of the array are: " & Chr$(a%(0)) &
Chr$(a%(1)) & Chr$(a%(2))
End Sub

Platform(s)
All.

3-62 Docbasic User’s Guide

A-Z Reference Chr, Chr$ (functions)

See Also
Asc (function)
Str, Str$ (functions)

Docbasic User’s Guide 3-63

CInt (function) A-Z Reference

CInt (function)

Converts expression to an Integer.

Syntax
CInt(expression)

Description
This function accepts any expression convertible to an Integer, including strings. A
runtime error is generated if expression is Null. Empty is treated as 0.

The passed numeric expression must be within the valid range for integers:
-32768 <= expression <= 32767

A runtime error results if the passed expression is not within the above range.

When passed a numeric expression, this function has the same effect as assigning
a numeric expression to an Integer. Note that integer variables are rounded before
conversion.

When used with variants, this function guarantees that the expression is converted
to an Integer variant (VarType 2).

Example
This example demonstrates the various results of integer manipulation with CInt.
Sub Main()

'(1) Assigns i# to 100.55 and displays its integer representation (101).

i# = 100.55
MsgBox "The value of CInt(i) = " & CInt(i#)

'(2) Sets j# to 100.22 and displays the CInt representation (100).

j# = 100.22
MsgBox "The value of CInt(j) = " & CInt(j#)

'(3) Assigns k% (integer) to the CInt sum of j# and k% and displays k%

(201).
k% = CInt(i# + j#)
MsgBox "The integer sum of 100.55 and 100.22 is: " & k%

'(4) Reassigns i# to 50.35 and recalculates k%, then displays the result
'(note rounding).
i# = 50.35
k% = CInt(i# + j#)
MsgBox "The integer sum of 50.35 and 100.22 is: " & k%

End Sub

3-64 Docbasic User’s Guide

A-Z Reference CInt (function)

Platform(s)
All.

See Also
CCur (function)
CBool (function)
CDate, CVDate (functions)
CDbl (function)
CLng (function)
CSng (function)
CStr (function)
CVar (function)
CVErr (function)
Integer (data type)

Docbasic User’s Guide 3-65

Clipboard$ (function) A-Z Reference

Clipboard$ (function)

Returns a String containing the contents of the Clipboard.

Syntax
Clipboard$[()]

Description
If the Clipboard doesn't contain text or the Clipboard is empty, then a zero-length
string is returned.

Example
This example puts text on the Clipboard, displays it, clears the Clipboard, and
displays the Clipboard again.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
Clipboard$ "Hello out there!"
MsgBox "The text in the Clipboard is:" & crlf & Clipboard$
Clipboard.Clear
MsgBox "The text in the Clipboard is:" & crlf & Clipboard$
End Sub

Platform(s)
Windows, Win32, Macintosh.

See Also
Clipboard$ (statement)
Clipboard.GetText (method)
Clipboard.SetText (method)

3-66 Docbasic User’s Guide

A-Z Reference Clipboard$ (statement)

Clipboard$ (statement)

Copies NewContent$ into the Clipboard.

Syntax
Clipboard$ NewContent$

Description
This example puts text on the Clipboard, displays it, clears the Clipboard, and
displays the Clipboard again.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
Clipboard$ "Hello out there!"
MsgBox "The text in the Clipboard is:" & crlf & Clipboard$
Clipboard.Clear
MsgBox "The text in the Clipboard is:" & crlf & Clipboard$
End Sub

Platform(s)
Windows, Win32, Macintosh.

See Also
Clipboard$ (function)
Clipboard.GetText (method)
Clipboard.SetText (method)

Docbasic User’s Guide 3-67

Clipboard.Clear (method) A-Z Reference

Clipboard.Clear (method)

This method clears the Clipboard by removing any content.

Syntax
Clipboard.Clear

Example
This example puts text on the Clipboard, displays it, clears the Clipboard, and
displays the Clipboard again.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
Clipboard$ "Hello out there!"
MsgBox "The text in the Clipboard is:" & crlf & Clipboard$
Clipboard.Clear
MsgBox "The text in the Clipboard is:" & crlf & Clipboard$
End Sub

Platform(s)
Windows, Win32, Macintosh.

3-68 Docbasic User’s Guide

A-Z Reference Clipboard.GetFormat (method)

Clipboard.GetFormat (method)

Returns True if data of the specified format is available in the Clipboard; returns
False otherwise.

Syntax
WhichFormat = Clipboard.GetFormat(format)

Description
This method is used to determine whether the data in the Clipboard is of a
particular format. The format parameter is an Integer representing the format to be
queried:

Table 3-14 Values of Format Parameter

Format Description

1 Text

2 Bitmap

3 Metafile

8 Device-independent bitmap (DIB)

9 Color palette

Example
This example puts text on the Clipboard, checks whether there is text on the
Clipboard, and if there is, displays it.
Sub Main()
Clipboard$ "Hello out there!"
If Clipboard.GetFormat(1) Then
MsgBox Clipboard$
Else
MsgBox "There is no text in the Clipboard."
End If
End Sub

Platform(s)
Windows, Win32, Macintosh.

Docbasic User’s Guide 3-69

Clipboard.GetFormat (method) A-Z Reference

See Also
Clipboard$ (function)
Clipboard$ (statement)

3-70 Docbasic User’s Guide

A-Z Reference Clipboard.GetText (method)

Clipboard.GetText (method)

Returns the text contained in the Clipboard.

Syntax
text$ = Clipboard.GetText([format])

Description
The format parameter, if specified, must be 1.

Example
This example retrieves the text from the Clipboard and checks to make sure that it
contains the word "dog."
Option Compare Text

Sub Main()
If Clipboard.GetFormat(1) Then
If Instr(Clipboard.GetText(1),"dog",1) = 0 Then
MsgBox "The Clipboard doesn't contain the word ""dog."""
Else
MsgBox "The Clipboard contains the word ""dog""."
End If
Else
MsgBox "The Clipboard does not contain text."
End If
End Sub

Platform(s)
Windows, Win32, Macintosh.

See Also
Clipboard$ (statement)
Clipboard$ (function)
Clipboard.SetText (method)

Docbasic User’s Guide 3-71

Clipboard.SetText (method) A-Z Reference

Clipboard.SetText (method)

Copies the specified text string to the Clipboard.

Syntax
Clipboard.SetText data$ [,format]

Description
The data$ parameter specifies the text to be copied to the Clipboard. The format
parameter, if specified, must be 1.

Example
This example gets the contents of the Clipboard and uppercases it.
Sub Main()
If Not Clipboard.GetFormat(1) Then Exit Sub
Clipboard.SetText UCase$(Clipboard.GetText(1)),1
End Sub

Platform(s)
Windows, Win32, Macintosh.

See Also
Clipboard$ (statement)
Clipboard.GetText (method)
Clipboard$ (function)

3-72 Docbasic User’s Guide

A-Z Reference CLng (function)

CLng (function)

Converts expression to a Long.

Syntax
CLng(expression)

Description
This function accepts any expression convertible to a Long, including strings. A
runtime error is generated if expression is Null. Empty is treated as 0.

The passed expression must be within the following range:

-2147483648 <= expression <= 2147483647

A runtime error results if the passed expression is not within the above range.

When passed a numeric expression, this function has the same effect as assigning
the numeric expression to a Long. Note that long variables are rounded before
conversion.

When used with variants, this function guarantees that the expression is converted
to a Long variant (VarType 3).

Example
This example displays the results for various conversions of i and j (note
rounding).
Sub Main()
i% = 100
j& = 123.666
MsgBox "The result is: " & CLng(i% * j&)'Displays 12367.
MsgBox "The variant type is: " & Vartype(CLng(i%))
End Sub

Platform(s)
All.

See Also
CCur (function)
CBool (function)

Docbasic User’s Guide 3-73

CLng (function) A-Z Reference

CDate, CVDate (functions)

CDbl (function)
CInt (function)
CSng (function)
CStr (function)
CVar (function)
CVErr (function)
Long (data type)

3-74 Docbasic User’s Guide

A-Z Reference Close (statement)

Close (statement)

Closes the specified files.

Syntax
Close [[#] filenumber [,[#] filenumber]...]

Description
If no arguments are specified, then all files are closed.

Example
This example opens four files and closes them in various combinations.
Sub Main()
Open "test1" For Output As #1
Open "test2" For Output As #2
Open "test3" For Random As #3
Open "test4" For Binary As #4
MsgBox "The next available file number is :" & FreeFile()
Close #1 'Closes file 1 only.
Close #2, #3'Closes files 2 and 3.
Close 'Closes all remaining files(4).
MsgBox "The next available file number is :" & FreeFile()
End Sub

Platform(s)
All.

See Also
Open (statement)
Reset (statement)
End (statement)

Docbasic User’s Guide 3-75

Command, Command$ (functions) A-Z Reference

Command, Command$ (functions)

Returns the argument from the command line used to start the application.

Syntax
Command[$][()]

Description
Command$ returns a string, whereas Command returns a String variant.

Example
This example gets the command line and parameters, checks to see whether the
string "/s" is present, and displays the result.
Sub Main()
cmd$ = Command$
If (InStr(cmd$,"/s")) <> 0 Then
MsgBox "Application was started with the /s switch."
Else
MsgBox "Application was started without the /s switch."
End If

If cmd$ <> "" Then

MsgBox "The command line startup options were: " & cmd$
Else
MsgBox "No command line startup options were used!"
End If
End Sub

Platform(s)
All.

See Also
Environ, Environ$ (functions)

3-76 Docbasic User’s Guide

A-Z Reference Comments (topic)

Comments (topic)

Comments can be added to Docbasic code in the following manner:

All text between a single quotation mark and the end of the line is ignored:
MsgBox "Hello"'Displays a message box.

The REM statement causes the compiler to ignore the entire line:
REM This is a comment.

Docbasic supports C-style multiline comment blocks /*...*/, as shown in the

following example:
MsgBox "Before comment"
/* This stuff is all commented out.
This line, too, will be ignored.
This is the last line of the comment. */
MsgBox "After comment"

Note: C-style comments can be nested.

Docbasic User’s Guide 3-77

Comparison Operators (topic) A-Z Reference

Comparison Operators (topic)

Comparison operators return True or False depending on the operator.

Syntax
expression1 [< | > | <= | >= | <> | =] expression2

Description
The comparison operators are listed in the following table :

Table 3-15 Comparison Operators

Operator Returns True If

> expression1 is greater than expression2

< expression1 is less than expression2

<= expression1 is less than or equal to expression2

>= expression1 is greater than or equal to expression2

<> expression1 is not equal to expression2

= expression1 is equal to expression2

This operator behaves differently depending on the types of the expressions, as

shown in the following table:

Table 3-16 Effect of Expression Type on Comparison Operators

If one expression is and the other then

expression is

Numeric Numeric A numeric comparison is performed (see below).

String String A string comparison is performed (see below).

Numeric String A compile error is generated.

Variant String A string comparison is performed (see below).

Variant Numeric A variant comparison is performed (see below).

Null variant Any data type Return Null.

Variant Variant A variant comparison is performed (see below).

3-78 Docbasic User’s Guide

A-Z Reference Comparison Operators (topic)

String Comparisons

If the two expressions are strings, then the operator performs a text comparison
between the two string expressions, returning True if expression1 is less than
expression2. The text comparison is case-sensitive if Option Compare is Binary;
otherwise, the comparison is case-insensitive.

When comparing letters with regard to case, lowercase characters in a string sort
greater than uppercase characters, so a comparison of "a" and "A" would indicate
that "a" is greater than "A".

Numeric Comparisons

When comparing two numeric expressions, the less precise expression is

converted to be the same type as the more precise expression.

Dates are compared as doubles. This may produce unexpected results as it is

possible to have two dates that, when viewed as text, display as the same date
when, in fact, they are different. This can be seen in the following example:
Sub Main()
Dim date1 As Date
Dim date2 As Date

date1 = Now
date2 = date1 + 0.000001'Adds a fraction of a second.

MsgBox date2 = date1'Prints False (the dates are different).

MsgBox date1 & "," & date2'Prints two dates that are the same.
End Sub

Variant Comparisons

When comparing variants, the actual operation performed is determined at

execution time according to the following table:

Table 3-17 Effect of Variant Data Type on Comparison Operators

If one variant is and the other then

variant is

Numeric Numeric Compare the variants as numbers.

String String Compare the variants as text.

Numeric String The number is less than the string.

Null Any other data type Null

Numeric Empty Compare the number with 0.

String Empty Compare the string with a zero-length string.

Docbasic User’s Guide 3-79

Comparison Operators (topic) A-Z Reference

Example
Sub Main()
'Tests two literals and displays the result.
If 5 < 2 Then
MsgBox "5 is less than 2."
Else
MsgBox "5 is not less than 2."
End If

'Tests two strings and displays the result.

If "This" < "That" Then
MsgBox "'This' is less than 'That'."
Else
MsgBox "'That' is less than 'This'."
End If
End Sub

Platform(s)
All.

See Also
Operator Precedence (topic)
Is (operator)
Like (operator)
Option Compare (statement)

3-80 Docbasic User’s Guide

A-Z Reference Const (statement)

Const (statement)

Declares a constant for use within the current procedure.

Syntax
Const name [As type] = expression [,name [As type] = expression]...

Description
The name is only valid within the current Docbasic procedure. Constant names
must follow these rules:

Must begin with a letter.

May contain only letters, digits, and the underscore character.

Must not exceed 80 characters in length.

Cannot be a reserved word.

Constant names are not case-sensitive.

The expression must be assembled from literals or other constants. Calls to

functions are not allowed except calls to the Chr$ function, as shown below:
Const s$ = "Hello, there" + Chr(44)

Constants can be given an explicit type by declaring the name with a type-
declaration character, as shown below:
Const a% = 5'Constant Integer whose value is 5
Const b# = 5'Constant Double whose value is 5.0
Const c$ = "5"'Constant String whose value is "5"
Const d! = 5'Constant Single whose value is 5.0
Const e& = 5'Constant Long whose value is 5

The type can also be given by specifying the As type clause:

Const a As Integer = 5'Constant Integer whose value is 5
Const b As Double = 5'Constant Double whose value is 5.0
Const c As String = "5"'Constant String whose value is "5"
Const d As Single = 5'Constant Single whose value is 5.0
Const e As Long = 5'Constant Long whose value is 5

You cannot specify both a type-declaration character and the type:

Const a% As Integer = 5'THIS IS ILLEGAL.

If an explicit type is not given, then Docbasic will choose the most imprecise type
that completely represents the data, as shown below:
Const a = 5 'Integer constant

Docbasic User’s Guide 3-81

Const (statement) A-Z Reference

Const b = 5.5'Single constant

Const c = 5.5E200'Double constant

Constants defined within a Sub or Function are local to that subroutine or function.
Constants defined outside of all subroutines and function can be used anywhere
within that procedure. The following example demonstrates the scoping of
constants:
Const DefFile = "default.txt"

Sub Test1
Const DefFile = "foobar.txt"
MsgBox DefFile 'Displays "foobar.txt".
End Sub

Sub Test2
MsgBox DefFile 'Displays "default.txt".
End Sub

Example
This example displays the declared constants in a dialog box (crlf produces a new
line in the dialog box).
Const crlf = Chr$(13) + Chr$(10)
Const s As String = "This is a constant."

Sub Main()
MsgBox s$ & crlf & "The constants are shown above."
End Sub

Platform(s)
All.

See Also
DefType (statement)
Let (statement)
= (statement)
Constants (topic)

3-82 Docbasic User’s Guide

A-Z Reference Constants (topic)

Constants (topic)

Constants are variables that cannot change value during procedure execution. The
following constants are predefined by Docbasic:

Table 3-18 Predefined Constants

True False Empty

PI ebRightButton ebLeftButton

ebPortrait ebLandscape ebMinimized

ebWindows ebMaximized ebReadOnly

ebRestored ebNormal ebVolume

ebHidden ebSystem ebNone

ebDirectory ebArchive ebAbortRetryIgnore

ebOKOnly ebOKCancel ebRetryCancel

ebYesNoCancel ebYesNo ebExclamation

ebCritical ebQuestion ebDefaultButton1

ebInformation ebApplicationModal ebSystemModal

ebDefaultButton2 ebDefaultButton3 ebAbort

ebOK ebCancel ebYes

ebRetry ebIgnor ebWin32

ebNo ebWin16 ebSolaris

ebAIX ebSunOs ebMacintosh

ebHPUX ebDOS16 ebNull

ebInteger ebLong ebSingle

ebVariant ebEmpty ebBoolean

ebDouble ebDate ebCurrency

ebObject ebDataObject

You can define your own constants using the Const statement.

Docbasic User’s Guide 3-83

Cos (function) A-Z Reference

Cos (function)

Returns a Double representing the cosine of angle.

Syntax
Cos(angle)

Description
The angle parameter is a Double specifying an angle in radians.

Example
This example assigns the cosine of pi/4 radians (45 degrees) to C# and displays its
value.
Sub Main()
c# = Cos(3.14159 / 4)
MsgBox "The cosine of 45 degrees is: " & c#
End Sub

Platform(s)
All.

See Also
Tan (function)
Sin (function)
Atn (function)

3-84 Docbasic User’s Guide

A-Z Reference CreateObject (function)

CreateObject (function)

Creates an OLE automation object and returns a reference to that object.

Syntax
CreateObject(class$)

Description
The class$ parameter specifies the application used to create the object and the type
of object being created. It uses the following syntax:

"application.class",

where application is the application used to create the object and class is the type of
the object to create.

At runtime, CreateObject looks for the given application and runs that application
if found. Once the object is created, its properties and methods can be accessed
using the dot syntax (e.g., object.property = value).

There may be a slight delay when an automation server is loaded (this depends on
the speed with which a server can be loaded from disk). This delay is reduced if an
instance of the automation server is already loaded.

Examples
This first example instantiates Microsoft Excel. It then uses the resulting object to
make Excel visible and then close Excel.
Sub Main()
Dim Excel As Object

On Error GoTo Trap1 'Set error trap.

Set Excel = CreateObject("excel.application")'Instantiate object.
Excel.Visible = True 'Make Excel visible.
Sleep 5000 'Wait 5 seconds.
Excel.Quit 'Close Excel.

Exit Sub 'Exit before error trap.

Trap1:
MsgBox "Can't create Excel object."'Display error message.
Exit Sub 'Reset error handler.
End Sub

This second example uses CreateObject to instantiate a Visio object. It then uses the
resulting object to create a new document.

Docbasic User’s Guide 3-85

CreateObject (function) A-Z Reference

Sub Main()
Dim Visio As Object
Dim doc As Object
Dim page As Object
Dim shape As Object

Set Visio = CreateObject("visio.application")'Create Visio object.

Set doc = Visio.Documents.Add("")'Create a new document.
Set page = doc.Pages(1) 'Get first page.
Set shape = page.DrawRectangle(1,1,4,4)'Create a new shape.
shape.text = "Hello, world."'Set text within shape.
End Sub

Platform(s)
Windows, Win32, Macintosh

See Also
GetObject (function)
Object (data type)

3-86 Docbasic User’s Guide

A-Z Reference Cross-Platform Procedures (topic)

Cross-Platform Procedures (topic)

This section discusses different techniques that can be used to ensure that a given
procedure runs on all platforms that support Docbasic.

Querying the Platform

A procedure can query the platform in order to take appropriate actions for that
platform. This is done using the Basic.OS property. The following example uses
this method to display a message to the user:
Sub Main()
If Basic.OS = ebWindows Then
MsgBox "This is a message."
Else
Print "This is a message."
End If
End Sub

Querying the Capabilities of a Platform

Some capabilities of the current platform can be determined using the
Basic.Capability method. This method takes a number indicating which capability
is being queried and returns either True or False depending on whether that
capability is or is not supported on the current platform. The following example
uses this technique to read hidden files:
Sub Main()
If Basic.Capability(3) Then
f$ = Dir$("*",ebHidden)'This platform supports hiddenfiles.
Else
f$ = Dir$("*") 'This platform doesn't support hidden files.
End If

'Print all the files.

While f$ <> ""
x = x + 1
Msgbox "Matching file " & x & " is: " & f$
f$ = Dir$
WEnd
End Sub

Byte Ordering with Files

One of the main differences between platforms is byte ordering. On some
platforms, the processor requires that the bytes that make up a given data item be
reversed from their expected ordering.

Byte ordering becomes problematic if binary data is transferred from one platform
to another. This can only occur when writing data to files. For this reason, it is

Docbasic User’s Guide 3-87

Cross-Platform Procedures (topic) A-Z Reference

strongly recommended that files that are to be transported to a different platform

with different byte ordering be sequential (i.e., do not use Binary and Random
files).

If a Binary or Random file needs to be transported to another platform, you will

have to take into consideration the following:

You must either decide on a byte ordering for your file or write information
to the file indicating its byte ordering so that it can be queried by the
procedure that is to read the file.

When reading a file on a platform in which the byte ordering matches,
nothing further needs to be done. If the byte ordering is different, then the
bytes of each data item read from a file need to be reversed. This is a difficult
proposition.

Byte Ordering with Structures

Due to byte ordering differences between platforms, structure copying using the
LSet statement produces different results. Consider the following example:
Type TwoInts
first As Integer
second As Integer
End Type

Type OneLong
first As Long
End Type

Sub Main()
Dim l As OneLong
Dim i As TwoInts
l.First = 4
LSet i = l
MsgBox "First integer: " & i.first
MsgBox "Second integer: " & i.second
End Sub

On Intel-based platforms, bytes are stored in memory with the most significant
byte first (known as little-endian format). Thus, the above example displays two
dialog boxes, the first one displaying the number 4 and the second displaying the
number 0.

On UNIX and Macintosh platforms, bytes are stored in memory with the least
significant byte first (known as big-endian format). Thus, the above example
displays two dialog boxes, the first one displaying the number 0 and the second
displaying the number 4.

Procedures that rely on binary images of data must take the byte ordering of the
current platform into account.

3-88 Docbasic User’s Guide

A-Z Reference Cross-Platform Procedures (topic)

Reading Text Files and Writing to Them

Different platforms use different characters to represent end-of-line in a file. For
example, under Windows, a carriage-return/line-feed pair is used. Under UNIX, a
line feed by itself is used. On the Macintosh, a carriage return is used.

Docbasic takes this into account when reading text files. The following
combinations are recognized and interpreted as end-of-line:

Carriage return Chr(13)

Carriage return/line feed Chr(13) + Chr(10)

Line feed Chr(10)

When writing to text files, Docbasic uses the end-of-line appropriate to that
platform. You can retrieve the same end-of-line used by Docbasic using the
Basic.Eoln$ property:
crlf = Basic.Eoln$

Print #1,"Line 1." & crlf & "Line 2."

Alignment
A major difference between platforms supported by Docbasic is the forced
alignment of data. Docbasic handles most alignment issues itself.

Portability of Compiled Code

Procedures compiled under Docbasic can be executed without recompilation on
any platform supported by Docbasic.

Unsupported Language Elements

A compiled Docbasic procedure is portable to any platform on which Docbasic
runs. Because of this, it is possible to execute a procedure that was compiled on
another platform and contains calls to language elements not supported by the
current platform.

Docbasic generates a runtime error when unsupported language elements are

encountered during execution. For example, the following procedure will execute
without errors under Windows but generate a runtime error when run under
UNIX:
Sub Main()
MsgBox "Hello, world."
End Sub

Docbasic User’s Guide 3-89

Cross-Platform Procedures (topic) A-Z Reference

If you trap a call to an unsupported function, the function will return one of the
following values:

Table 3-19 Effect of Unsupported Function Calls in Cross-Platform Procedures

Data Type Skipped Function Returns

Integer 0

Double 0.0

Single 0.0

Long 0

Date December 31, 1899

Boolean False

Variant Empty

Object Nothing

Path Separators
Different file systems use different characters to separate parts of a pathname. For
example, under Windows and Win32, the backslash character is used:
s$ = "c:\sheets\bob.xls"

Under UNIX, the forward slash is used:

s$ = "/sheets/bob.xls"

When creating procedures that operate on any of these platforms, Docbasic

recognizes the forward slash universally as a valid path separator. Thus, the
following file specification is valid on all these platforms:
s$ = "/sheets/bob.xls"

On the Macintosh, the slashes are valid filename characters. Instead, Docbasic
recognizes the colon as the valid file separator character:
s$ = "sheets:bob.xls"

You can find out the path separator character for your platform using the
Basic.PathSeparator$ property:
s$ = "sheets" & Basic.PathSeparator$ & "bob.xls"

3-90 Docbasic User’s Guide

A-Z Reference Cross-Platform Procedures (topic)

Relative Paths
Specifying relative paths is different across platforms. Under UNIX, Windows, and
Win32, a period (.) is used to specify the current directory, and two periods (..) are
used to indicate the parent directory, as shown below:
s$ = ".\bob.xls"'File in the current directory
s$ = "..\bob.xls"'File in the parent directory

On the Macintosh, double colons are used to specify the parent folder:
s$ = "::bob.xls"'File in the parent folder

Drive Letters
Not all platforms support drive letters. For example, considering the following file
specification:
c:\test.txt

Under UNIX, this specifies a single file called c:\test.txt. Under Windows, this
specifies a file called test.txt in the root directory of drive c. On the Macintosh, this
specifies a file called \test.txt in a folder called c. You can use the Basic.Capability
method to determine whether your platform supports drive letters:
Sub Main()
If Basic.Capability(1) Then s$ = "c:/" Else s$ = ""
s$ = s$ & "test.xls"
MsgBox "The platform-specific filename is: " & s$
End Sub

Docbasic User’s Guide 3-91

CSng (function) A-Z Reference

CSng (function)

Converts expression to a Single.

Syntax
CSng(expression)

Description
This function accepts any expression convertible to a Single, including strings. A
runtime error is generated if expression is Null. Empty is treated as 0.0.

A runtime error results if the passed expression is not within the valid range for
Single.

When passed a numeric expression, this function has the same effect as assigning
the numeric expression to a Single.

When used with variants, this function guarantees that the expression is converted
to a Single variant (VarType 4).

Example
This example displays the value of a String converted to a Single.
Sub Main()
s$ = "100"
MsgBox "The single value is: " & CSng(s$)
End Sub

Platform(s)
All.

See Also
CCur (function)
CBool (function)
CDate, CVDate (functions)
CDbl (function)
CInt (function)
CLng (function)
CStr (function)
CVar (function)

3-92 Docbasic User’s Guide

A-Z Reference CSng (function)

CVErr (function)
Single (data type)

Docbasic User’s Guide 3-93

CStr (function) A-Z Reference

CStr (function)

Converts expression to a String.

Syntax
CStr(expression)

Description
Unlike Str$ or Str, the string returned by CStr will not contain a leading space if the
expression is positive. Further, the CStr function correctly recognizes thousands
and decimal separators for your locale.

Different data types are converted to String in accordance with the following rules:

Table 3-20 Effect of Data Types on String Conversion

Data type CStr returns

Any numeric type A string containing the number without the leading space for
positive values.

Date A string converted to a date using the short date format.

Boolean A string containing either "True" or "False.

Null variant A runtime error.

Empty variant A zero-length string.

Example
This example displays the value of a Double converted to a String.
Sub Main()
s# = 123.456
MsgBox "The string value is: " & CStr(s#)
End Sub

Platform(s)
All.

3-94 Docbasic User’s Guide

A-Z Reference CStr (function)

See Also
CCur (function)
CBool (function)
CDate, CVDate (functions)
CDbl (function)
CInt (function)
CLng (function)
CSng (function)
CVar (function)
CVErr (function)
String (data type)
Str, Str$ (functions)

Docbasic User’s Guide 3-95

CurDir, CurDir$ (functions) A-Z Reference

CurDir, CurDir$ (functions)

Returns the current directory on the specified drive. If no drive$ is specified or

drive$ is zero-length, then the current directory on the current drive is returned.

Syntax
CurDir[$][(drive$)]

Description
CurDir$ returns a String, whereas CurDir returns a String variant.

Docbasic generates a runtime error if drive$ is invalid.

Example
This example saves the current directory, changes to the next higher directory, and
displays the change; then restores the original directory and displays the change.

Note: The dot designators will not work with all platforms.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
save$ = CurDir$
ChDir ("..")
MsgBox "Old directory: " & save$ & crlf & "New directory: " & CurDir$
ChDir (save$)
MsgBox "Directory restored to: " & CurDir$
End Sub

Platform(s)
All.

Platform Notes: UNIX

On UNIX platforms, the drive$ parameter is ignored. Since UNIX platforms do not
support drive letters, the current directory is always returned.

See Also
ChDir (statement)
ChDrive (statement)

3-96 Docbasic User’s Guide

A-Z Reference CurDir, CurDir$ (functions)

Dir, Dir$ (functions)

MkDir (statement)
RmDir (statement)

Docbasic User’s Guide 3-97

Currency (data type) A-Z Reference

Currency (data type)

A data type used to declare variables capable of holding fixed-point numbers with
15 digits to the left of the decimal point and 4 digits to the right.

Syntax
Currency

Description
Currency variables are used to hold numbers within the following range:
-922,337,203,685,477.5808 <= currency <= 922,337,203,685,477.5807

Due to their accuracy, Currency variables are useful within calculations involving
money.

The type-declaration character for Currency is @.

Storage

Internally, currency values are 8-byte integers scaled by 10000. Thus, when
appearing within a structure, currency values require 8 bytes of storage. When
used with binary or random files, 8 bytes of storage are required.

Platform(s)
All.

See Also
Date (data type)
Double (data type)
Integer (data type)
Long (data type)
Object (data type)
Single (data type)
String (data type)
Variant (data type)
Boolean (data type)
DefType (statement)
CCur (function)

3-98 Docbasic User’s Guide

A-Z Reference CVar (function)

CVar (function)

Converts expression to a Variant.

Syntax
CVar(expression)

Description
This function is used to convert an expression into a variant. Use of this function is
not necessary (except for code documentation purposes) because assignment to
variant variables automatically performs the necessary conversion:
Sub Main()
Dim v As Variant
v = 4 & "th"'Assigns "4th" to v.
MsgBox "You came in: " & v
v = CVar(4 & "th")'Assigns "4th" to v.
MsgBox "You came in: " & v
End Sub

Example
This example converts an expression into a Variant.
Sub Main()
Dim s As String
Dim a As Variant
s = CStr("The quick brown fox ")
msg = CVar(s & "jumped over the lazy dog.")
MsgBox msg
End Sub

Platform(s)
All.

See Also
CCur (function)
CBool (function)
CDate, CVDate (functions)
CDbl (function)
CInt (function)
CLng (function)
CSng (function)

Docbasic User’s Guide 3-99

CVar (function) A-Z Reference

CStr (function)
CVErr (function)
Variant (data type)

3-100 Docbasic User’s Guide

A-Z Reference CVErr (function)

CVErr (function)

Converts expression to an error.

Syntax
CVErr(expression)

Description
This function is used to convert an expression into a user-defined error number.

A runtime error is generated under the following conditions:

If expression is Null.

If expression is a number outside the legal range for errors, which is as follows:
0 <= expression <= 65535

If expression is Boolean.

If expression is a String that can't be converted to a number within the legal range.

Empty is treated as 0.

Example
This example simulates a user-defined error and displays the error number.
Sub Main()
MsgBox "The error is: " & CStr(CVErr(2046))
End Sub

Platform(s)
All.

See Also
CCur (function)
CBool (function)
CDate, CVDate (functions)
CDbl (function)
CInt (function)
CLng (function)

Docbasic User’s Guide 3-101

CVErr (function) A-Z Reference

CSng (function)
CStr (function)
CVar (function)
IsError (function)

3-102 Docbasic User’s Guide

A-Z Reference Date (data type)

Date (data type)

A data type capable of holding date and time values.

Syntax
Date

Description
Date variables are used to hold dates within the following range:
January 1, 100 00:00:00 <= date <= December 31, 9999 23:59:59

-6574340 <= date <= 2958465.99998843

Internally, dates are stored as 8-byte IEEE double values. The integer part holds the
number of days since December 31, 1899, and the fractional part holds the number
of seconds as a fraction of the day. For example, the number 32874.5 represents
January 1, 1990 at 12:00:00.

When appearing within a structure, dates require 8 bytes of storage. Similarly,

when used with binary or random files, 8 bytes of storage are required.

There is no type-declaration character for Date.

Date variables that haven't been assigned are given an initial value of 0 (i.e.,
December 31, 1899).

Literal dates are specified using number signs, as shown below:

Dim d As Date
d = #January 1, 1990#

The interpretation of the date string (i.e., January 1, 1990 in the above example)
occurs at runtime, using the current country settings. This is a problem when
interpreting dates such as 1/2/1990. If the date format is M/D/Y, then this date is
January 2, 1990. If the date format is D/M/Y, then this date is February 1, 1990. To
remove any ambiguity when interpreting dates, use the universal date format:
date_variable = #YY/MM/DD HH:MM:SS#

The following example specifies the date June 3, 1965 using the universal date
format:
Dim d As Date
d = #1965/6/3 10:23:45#

Docbasic User’s Guide 3-103

Date (data type) A-Z Reference

Platform(s)
All.

See Also
Currency (data type)
Double (data type)
Integer (data type)
Long (data type)
Object (data type)
Single (data type)
String (data type)
Variant (data type)
Boolean (data type)
Deftype (statement)
CDate, CVDate (functions)

3-104 Docbasic User’s Guide

A-Z Reference Date, Date$ (functions)

Date, Date$ (functions)

Returns the current system date.

Syntax
Date[$][()]

Description
The Date$ function returns the date using the short date format. The Date function
returns the date as a Date variant.

Use the Date/Date$ statements to set the system date.

Example
This example saves the current date to Cdate$, then changes the date and displays
the result. It then changes the date back to the saved date and displays the result.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
TheDate$ = Date$()
Date$ = "01/01/95"
MsgBox "Saved date is: " & TheDate$ & crlf & "Changed date is: " & Date$()
Date$ = TheDate$
MsgBox "Restored date to: " & TheDate$
End Sub

Platform(s)
All.

See Also
CDate, CVDate (functions)
Time, Time$ (functions)
Date, Date$ (statements)
Now (function)
Format, Format$ (functions)
DateSerial (function)
DateValue (function)

Docbasic User’s Guide 3-105

Date, Date$ (statements) A-Z Reference

Date, Date$ (statements)

Sets the system date to the specified date.

Syntax
Date[$] = newdate

Description
The Date$ statement requires a string variable using one of the following formats:
MM-DD-YYYY
MM-DD-YY
MM/DD/YYYY
MM/DD/YY,

where MM is a two-digit month between 1 and 31, DD is a two-digit day between

1 and 31, and YYYY is a four-digit year between 1/1/100 and 12/31/9999.

The Date statement converts any expression to a date, including string and
numeric values. Unlike the Date$ statement, Date recognizes many different date
formats, including abbreviated and full month names and a variety of ordering
options. If newdate contains a time component, it is accepted, but the time is not
changed. An error occurs if newdate cannot be interpreted as a valid date.

Example
This example saves the current date to Cdate$, then changes the date and displays
the result. It then changes the date back to the saved date and displays the result.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
TheDate$ = Date$()
Date$ = "01/01/95"
MsgBox "Saved date is: " & TheDate$ & crlf & "Changed date is: " & Date$()
Date$ = TheDate$
MsgBox "Restored date to: " & TheDate$
End Sub

Platform(s)
All.

3-106 Docbasic User’s Guide

A-Z Reference Date, Date$ (statements)

Platform Notes
On some platforms, you may not have permission to change the date, causing
runtime error 70 to be generated. This can occur on all UNIX platforms and Win32.

The range of valid dates varies from platform to platform. The following table
describes the minimum and maximum dates accepted by various platforms:

Table 3-21 Valid Dates for Docbasic Platforms

Platform Minimum Date Maximum Date

Macintosh January 1, 1904 February 6, 2040

Windows January 1, 1980 December 31, 2099

Win32

Windows 95 January 1, 1980 December 31, 2099

UNIX

See Also
Date, Date$ (functions)
Time, Time$ (statements)

Docbasic User’s Guide 3-107

DateAdd (function) A-Z Reference

DateAdd (function)

Returns a Date variant representing the sum of date and a specified number
(increment) of time intervals (interval$).

Syntax
DateAdd(interval$, increment&, date)

Argument Descriptions

interval$ String expression indicating the time interval used in the

addition.

increment Integer indicating the number of time intervals you wish to

add. Positive values result in dates in the future; negative
values result in dates in the past.

date Any expression convertible to a Date.

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

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

Table 3-22 Values of the Interval$ Parameter

Time Interval

"y" Day of the year

"yyyy" Year

"d" Day

"m" Month

"q" Quarter

"ww" Week

"h" Hour

3-108 Docbasic User’s Guide

A-Z Reference DateAdd (function)

Table 3-22 Values of the Interval$ Parameter

Time Interval

"n" Minute

"s" Second

"w" Weekday

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

The DateAdd function will never return an invalid date/time expression. The
following example adds two months to December 31, 1992:
s# = DateAdd("m", 2, "December 31, 1992")

In this example, s is returned as the double-precision number equal to "February

28, 1993", not "February 31, 1993".

Docbasic generates a runtime error if you try subtracting a time interval that is
larger than the time value of the date.

Example
This example gets today's date using the Date$ function; adds three years, two
months, one week, and two days to it; and then displays the result in a dialog box.
Sub Main()
Dim sdate$
sdate$ = Date$
NewDate# = DateAdd("yyyy", 4, sdate$)
NewDate# = DateAdd("m", 3, NewDate#)
NewDate# = DateAdd("ww", 2, NewDate#)
NewDate# = DateAdd("d", 1, NewDate#)
s$ = "Four years, three months, two weeks, and one day from now will be: "
s$ = s$ & Format(NewDate#, "long date")
MsgBox s$
End Sub

Platform(s)
All.

See Also
DateDiff (function)

Docbasic User’s Guide 3-109

DateDiff (function) A-Z Reference

DateDiff (function)

Returns a Date variant representing the number of given time intervals between
date1 and date2.

Syntax
DateDiff(interval$,date1,date2)

Argument Descriptions

interval$ String expression indicating the specific time interval you

wish to find the difference between.

date1 Any expression convertible to a Date. An example of a

valid date/time string would be "January 1, 1994".

date2 Any expression convertible to a Date. An example of a

valid date/time string would be "January 1, 1994".

Description
The following lists the valid time interval strings and the meanings of each. The
Format$ function uses the same expressions.

Table 3-23 Values of the Interval$ Parameter

Time Interval

"y" Day of the year

"yyyy" Year

"d" Day

"m" Month

"q" Quarter

"ww" Week

"h" Hour

"n" Minute

"s" Second

"w" Weekday

3-110 Docbasic User’s Guide

A-Z Reference DateDiff (function)

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

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

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

Example
This example gets today's date and adds ten days to it. It then calculates the
difference between the two dates in days and weeks and displays the result.
Sub Main()
today$ = Format(Date$,"Short Date")
NextWeek = Format(DateAdd("d", 14, today$),"Short Date")
DifDays# = DateDiff("d", today$, NextWeek)
DifWeek# = DateDiff("w", today$, NextWeek)
s$ = "The difference between " & today$ & " and " & NextWeek
s$ = s$ & " is: " & DifDays# & " days or " & DifWeek# & " weeks"
MsgBox s$
End Sub

Platform(s)
All.

See Also
DateAdd (function)

Docbasic User’s Guide 3-111

DatePart (function) A-Z Reference

DatePart (function)

Returns an Integer representing a specific part of a date/time expression.

Syntax
DatePart(interval$,date)

Argument Descriptions

interval$ String expression that indicates the specific time interval

you wish to identify within the given date.

date Any expression convertible to a Date. An example of a

valid date/time string would be "January 1, 1995".

Description
The DatePart function decomposes the specified date and returns a given date/
time element.

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

Table 3-24 Values of the Interval$ Parameter

Time Interval

"y" Day of the year

"yyyy" Year

"d" Day

"m" Month

"q" Quarter

"ww" Week

"h" Hour

"n" Minute

"s" Second

"w" Weekday

3-112 Docbasic User’s Guide

A-Z Reference DatePart (function)

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

Example
This example displays the parts of the current date.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
today$ = Date$
qtr = DatePart("q",today$)
yr = DatePart("yyyy",today$)
mo = DatePart("m",today$)
wk = DatePart("ww",today$)
da = DatePart("d",today$)
s$ = "Quarter: " & qtr & crlf
s$ = s$ & "Year: " & yr & crlf
s$ = s$ & "Month: " & mo & crlf
s$ = s$ & "Week: " & wk & crlf
s$ = s$ & "Day: " & da & crlf
MsgBox s$
End Sub

Platform(s)
All.

See Also
Day (function)
Minute (function)
Second (function)
Month (function)
Year (function)
Hour (function)
Weekday (function)
Format (function)

Docbasic User’s Guide 3-113

DateSerial (function) A-Z Reference

DateSerial (function)

Returns a Date variant representing the specified date.

Syntax
DateSerial(year,month,day)

Argument Descriptions

year Integer between 100 and 9999

month Integer between 1 and 12

day Integer between 1 and 31

Example
This example converts a date to a real number representing the serial date in days
since December 30, 1899 (which is day 0).
Sub Main()
tdate# = DateSerial(1993,08,22)
MsgBox "The DateSerial value for August 22, 1993, is: " & tdate#
End Sub

Platform(s)
All.

See Also
DateValue (function)
TimeSerial (function)
TimeValue (function)
CDate, CVDate (functions)

3-114 Docbasic User’s Guide

A-Z Reference DateValue (function)

DateValue (function)

Returns a Date variant representing the date contained in the specified string
argument.

Syntax
DateValue(date_string$)

Example
This example returns the day of the month for today's date.
Sub Main()
tdate$ = Date$
tday = DateValue(tdate$)
MsgBox tdate & " date value is: " & tday$
End Sub

Platform(s)
All.

Platform Notes: Windows

Under Windows, date specifications vary depending on the international settings
contained in the "intl" section of the win.ini file. The date items must follow the
ordering determined by the current date format settings in use by Windows.

See Also
TimeSerial (function)
TimeValue (function)
DateSerial (function)

Docbasic User’s Guide 3-115

Day (function) A-Z Reference

Day (function)

Returns the day of the month specified by date.

Syntax
Day(date)

Description
The value returned is an Integer between 0 and 31 inclusive.

The date parameter is any expression that converts to a Date.

Example
This example gets the current date and then displays it.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
CurDate = Now()
MsgBox "Today is day " & Day(CurDate) & " of the month." & crlf &
"Tomorrow is day " & Day(CurDate + 1)
End Sub

Platform(s)
All.

See Also
Minute (function)
Second (function)
Month (function)
Year (function)
Hour (function)
Weekday (function)
DatePart (function)

3-116 Docbasic User’s Guide

A-Z Reference DDB (function)

DDB (function)

Calculates the depreciation of an asset for a specified Period of time using the
double-declining balance method.

Syntax
DDB(Cost, Salvage, Life, Period)

Argument Descriptions

Cost Double representing the initial cost of the asset

Salvage Double representing the estimated value of the asset at the

end of its predicted useful life

Life Double representing the predicted length of the asset's

useful life

Period Double representing the period for which you wish to

calculate the depreciation

Description
The double-declining balance method calculates the depreciation of an asset at an
accelerated rate. The depreciation is at its highest in the first period and becomes
progressively lower in each additional period. DDB uses the following formula to
calculate the depreciation:
DDB =((Cost-Total_depreciation_from_all_other_periods) * 2)/Life

Life and Period must be expressed using the same units. For example, if Life is
expressed in months, then Period must also be expressed in months.

Example
This example calculates the depreciation for capital equipment that cost $10,000,
has a service life of ten years, and is worth 2,000 as scrap. The dialog box displays
the depreciation for each of the first four years.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
s$ = "Depreciation Table" & crlf & crlf
For yy = 1 To 4
CurDep# = DDB(10000.0,2000.0,10,yy)

Docbasic User’s Guide 3-117

DDB (function) A-Z Reference

s$ = s$ & "Year " & yy & " : " & CurDep# & crlf
Next yy
MsgBox s$
End Sub

Platform(s)
All.

See Also
Sln (function)
SYD (function)

3-118 Docbasic User’s Guide

A-Z Reference DDEExecute (statement)

DDEExecute (statement)

Executes a command in another application.

Syntax
DDEExecute channel, command$

Argument Descriptions

channel Integer containing the DDE channel number returned from

DDEInitiate. An error will result if channel is invalid.

command$ String containing the command to be executed. The format

of command$ depends on the receiving application.

Description
If the receiving application does not execute the instructions, Docbasic generates a
runtime error.

Example
This example selects a cell in an Excel spreadsheet.
Sub Main()
q$ = Chr(34)
ch% = DDEInitiate("Excel","c:\sheets\test.xls")
cmd$ = "Select(" & q$ & "R1C1:R8C1" & q$ & ")"
DDEExecute ch%,cmd$
DDETerminate ch%
End Sub

Platform(s)
Windows, Win32.

Platform Notes: Windows

Under Windows, the DDEML library is required for DDE support. This library is
loaded when the first DDEInitiate statement is encountered and remains loaded
until the Docbasic system is terminated. Thus, the DDEML library is required only
if DDE statements are used within a procedure.

Docbasic User’s Guide 3-119

DDEExecute (statement) A-Z Reference

See Also
DDEInitiate (function)
DDEPoke (statement)
DDERequest, DDERequest$ (functions)
DDESend (function)
DDETerminate (statement)
DDETerminateAll (statement)
DDETimeout (statement)

3-120 Docbasic User’s Guide

A-Z Reference DDEInitiate (function)

DDEInitiate (function)

Initializes a DDE link to another application and returns a unique number

subsequently used to refer to the open DDE channel.

Syntax
DDEInitiate(application$, topic$)

Argument Descriptions

application$ String containing the name of the application (the server)

with which a DDE conversation will be established.

topic$ String containing the name of the topic for the

conversation. The possible values for this parameter are
described in the documentation for the server application.

Description
This function returns 0 if Docbasic cannot establish the link. This will occur under
any of the following circumstances:

The specified application is not running.

The topic was invalid for that application.

Memory or system resources are insufficient to establish the DDE link.

Example
This example selects a range of cells in an Excel spreadsheet.
Sub Main()
q$ = Chr(34)
ch% = DDEInitiate("Excel","c:\sheets\test.xls")
cmd$ = "Select(" & q$ & "R1C1:R8C1" & q$ & ")"
DDEExecute ch%,cmd$
DDETerminate ch%
End Sub

Platform(s)
Windows, Win32.

Docbasic User’s Guide 3-121

DDEInitiate (function) A-Z Reference

Platform Notes: Windows

Under Windows, the DDEML library is required for DDE support. This library is
loaded when the first DDEInitiate statement is encountered and remains loaded
until the Docbasic system is terminated. Thus, the DDEML library is required only
if DDE statements are used within a procedure.

See Also
DDEExecute (statement)
DDEPoke (statement)
DDERequest, DDERequest$ (functions)
DDESend (function)
DDETerminate (statement)
DDETerminateAll (statement)
DDETimeout (statement)

3-122 Docbasic User’s Guide

A-Z Reference DDEPoke (statement)

DDEPoke (statement)

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

Syntax
DDEPoke channel, DataItem, value

Argument Descriptions

channel Integer containing the DDE channel number returned from

DDEInitiate. An error will result if channel is invalid.

DataItem Data item to be set. This parameter can be any expression

convertible to a String. The format depends on the server.

value The new value for the data item. This parameter can be any
expression convertible to a String. The format depends on
the server. A runtime error is generated if value is Null.

Example
This example pokes a value into an Excel spreadsheet.
Sub Main()
ch% = DDEInitiate("Excel","c:\sheets\test.xls")
DDEPoke ch%,"R1C1","980"
DDETerminate ch%
End Sub

Platform(s)
Windows, Win32.

Platform Notes: Windows

Under Windows, the DDEML library is required for DDE support. This library is
loaded when the first DDEInitiate statement is encountered and remains loaded
until the Docbasic system is terminated. Thus, the DDEML library is required only
if DDE statements are used within a procedure.

Docbasic User’s Guide 3-123

DDEPoke (statement) A-Z Reference

See Also
DDEExecute (statement)
DDEInitiate (function)
DDERequest, DDERequest$ (functions)
DDESend (function)
DDETerminate (statement)
DDETerminateAll (statement)
DDETimeout (statement)

3-124 Docbasic User’s Guide

A-Z Reference DDERequest, DDERequest$ (functions)

DDERequest, DDERequest$ (functions)

Returns the value of the given data item in the receiving application associated
with the open DDE channel.

Syntax
DDERequest[$](channel,DataItem$)

Argument Descriptions

channel Integer containing the DDE channel number returned from

DDEInitiate. An error will result if channel is invalid.

DataItem$ String containing the name of the data item to request. The
format for this parameter depends on the server.

Description
DDERequest$ returns a String, whereas DDERequest returns a String variant.

The format for the returned value depends on the server.

Example
This example gets a value from an Excel spreadsheet.
Sub Main()
ch% = DDEInitiate("Excel","c:\excel\test.xls")
s$ = DDERequest$(ch%,"R1C1")
DDETerminate ch%
MsgBox s$
End Sub

Platform(s)
Windows, Win32.

Platform Notes: Windows

Under Windows, the DDEML library is required for DDE support. This library is
loaded when the first DDEInitiate statement is encountered and remains loaded

Docbasic User’s Guide 3-125

DDERequest, DDERequest$ (functions) A-Z Reference

until the Docbasic system is terminated. Thus, the DDEML library is required only
if DDE statements are used within a procedure.

See Also
DDEExecute (statement)
DDEInitiate (function)
DDEPoke (statement)
DDESend (function)
DDETerminate (statement)
DDETerminateAll (statement)
DDETimeout (statement)

3-126 Docbasic User’s Guide

A-Z Reference DDESend (statement)

DDESend (statement)

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

Syntax
DDESend application$, topic$, DataItem, value

Argument Descriptions

application$ String containing the name of the application (the server)

with which a DDE conversation will be established.

topic$ String containing the name of the topic for the

conversation. The possible values for this parameter are
described in the documentation for the server application.

DataItem Data item to be set. This parameter can be any expression

convertible to a String. The format depends on the server.

value New value for the data item. This parameter can be any
expression convertible to a String. The format depends on
the server. A runtime error is generated if value is Null.

Description
The DDESend statement performs the equivalent of the following statements:
ch% = DDEInitiate(application$, topic$)
DDEPoke ch%, item, data
DDETerminate ch%

Example
This code fragment sets the content of the first cell in an Excel spreadsheet.
Sub Main()
On Error Goto Trap1
DDESend "Excel","c:\excel\test.xls","R1C1","Hello, world."
On Error Goto 0
'Add more lines here.

Trap1:
MsgBox "Error sending data to Excel."
Exit Sub'Reset error handler.
End Sub

Docbasic User’s Guide 3-127

DDESend (statement) A-Z Reference

Platform(s)
Windows, Win32.

Platform Notes: Windows

Under Windows, the DDEML library is required for DDE support. This library is
loaded when the first DDEInitiate statement is encountered and remains loaded
until the Docbasic system is terminated. Thus, the DDEML library is required only
if DDE statements are used within a procedure.

See Also
DDEExecute (statement)
DDEInitiate (function)
DDEPoke (statement)
DDERequest, DDERequest$ (functions)
DDETerminate (statement)
DDETerminateAll (statement)
DDETimeout (statement)

3-128 Docbasic User’s Guide

A-Z Reference DDETerminate (statement)

DDETerminate (statement)

Closes the specified DDE channel.

Syntax
DDETerminate channel

Description
The channel parameter is an Integer containing the DDE channel number returned
from DDEInitiate. An error will result if channel is invalid.

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

Example
This code fragment sets the content of the first cell in an Excel spreadsheet.
Sub Main()
q$ = Chr(34)
ch% = DDEInitiate("Excel","c:\sheets\test.xls")
cmd$ = "Select(" & q$ & "R1C1:R8C1" & q$ & ")"
DDEExecute ch%,cmd$
DDETerminate ch%
End Sub

Platform(s)
Windows, Win32.

Platform Notes: Windows

Under Windows, the DDEML library is required for DDE support. This library is
loaded when the first DDEInitiate statement is encountered and remains loaded
until the Docbasic system is terminated. Thus, the DDEML library is required only
if DDE statements are used within a procedure.

See Also
DDEExecute (statement)
DDEInitiate (function)
DDEPoke (statement)
DDERequest, DDERequest$ (functions)

Docbasic User’s Guide 3-129

DDETerminate (statement) A-Z Reference

DDESend (function)
DDETerminateAll (statement)
DDETimeout (statement)

3-130 Docbasic User’s Guide

A-Z Reference DDETerminateAll (statement)

DDETerminateAll (statement)

Closes all open DDE channels.

Syntax
DDETerminateAll

Description
All open DDE channels are automatically terminated when the procedure ends.

Example
This code fragment selects the contents of the first cell in an Excel spreadsheet.
Sub Main()
q$ = Chr(34)
ch% = DDEInitiate("Excel","c:\sheets\test.xls")
cmd$ = "Select(" & q$ & "R1C1:R8C1" & q$ & ")"
DDEExecute ch%,cmd$
DDETerminateAll
End Sub

Platform(s)
Windows, Win32.

Platform Notes: Windows

Under Windows, the DDEML library is required for DDE support. This library is
loaded when the first DDEInitiate statement is encountered and remains loaded
until the Docbasic system is terminated. Thus, the DDEML library is required only
if DDE statements are used within a procedure.

See Also
DDEExecute (statement)
DDEInitiate (function)
DDEPoke (statement)
DDERequest, DDERequest$ (functions)
DDESend (function)
DDETerminate (statement)
DDETimeout (statement)

Docbasic User’s Guide 3-131

DDETimeout (statement) A-Z Reference

DDETimeout (statement)

Sets the number of milliseconds that must elapse before any DDE command times
out.

Syntax
DDETimeout milliseconds

Description
The milliseconds parameter is a Long and must be within the following range:
0 <= milliseconds <= 2,147,483,647

The default is 10,000 (10 seconds).

Example
Sub Main()
q$ = Chr(34)
ch% = DDEInitiate("Excel","c:\sheets\test.xls")
DDETimeout(20000)
cmd$ = "Select(" & q$ & "R1C1:R8C1" & q$ & ")"
DDEExecute ch%,cmd$
DDETerminate ch%
End Sub

Platform(s)
Windows, Win32.

Platform Notes: Windows

Under Windows, the DDEML library is required for DDE support. This library is
loaded when the first DDEInitiate statement is encountered and remains loaded
until the Docbasic system is terminated. Thus, the DDEML library is required only
if DDE statements are used within a procedure.

See Also
DDEExecute (statement)
DDEInitiate (function)
DDEPoke (statement)
DDERequest, DDERequest$ (functions)

3-132 Docbasic User’s Guide

A-Z Reference DDETimeout (statement)

DDESend (function)
DDETerminate (statement)
DDETerminateAll (statement)

Docbasic User’s Guide 3-133

Declare (statement) A-Z Reference

Declare (statement)

Creates a prototype for either an external routine or a Docbasic routine that occurs
later in the source module or in another source module.

Syntax
Declare {Sub | Function} name[TypeChar] [CDecl | Pascal | System |
StdCall] _ [Lib "LibName$" [Alias "AliasName$"]] [([ParameterList])] [As
type]

Where ParameterList is a comma-separated list of the following (up to 30

parameters are allowed):
[Optional] [ByVal | ByRef] ParameterName[()] [As ParameterType]

Argument Descriptions

Description
Declare statements must appear outside of any Sub or Function declaration.

Declare statements are only valid during the life of the procedure in which they
appear.

In addition to the default Docbasic data types, ParameterType can specify any user-
defined structure, data object, or OLE automation object. If the data type of the
parameter is not known in advance, then the Any keyword can be used. This forces
the Docbasic compiler to relax type checking, allowing any data type to be passed
in place of the given argument.

Declare Sub Convert Lib "mylib" (a As Any)

The Any data type can only be used when passing parameters to external routines.

Passing Parameters

By default, Docbasic passes arguments by reference. Many external routines

require a value rather than a reference to a value. The ByVal keyword does this. For
example, this C routine

void MessageBeep(int);

would be declared as follows:

Declare Sub MessageBeep Lib "user" (ByVal n As Integer)

3-134 Docbasic User’s Guide

A-Z Reference Declare (statement)

name Any valid Docbasic name. When you declare functions,

you can include a type-declaration character to indicate the
return type.

This name is specified as a normal Docbasic keyword—i.e.,

it does not appear within quotes.

TypeChar An optional type-declaration character used when defining

the type of data returned from functions. It can be any of
the following characters: #, !, $, @, %, or &. For external
functions, the @ character is not allowed.

Type-declaration characters can only appear with function

declarations, and take the place of the As type clause.

Note: Currency data cannot be returned from external

functions. Thus, the @ type-declaration character cannot be
used when declaring external functions.

Decl Optional keyword indicating that the external subroutine

or function uses the C calling convention. With C routines,
arguments are pushed right to left on the stack and the
caller performs stack cleanup.

Pascal Optional keyword indicating that this external subroutine

or function uses the Pascal calling convention. With Pascal
routines, arguments are pushed left to right on the stack
and the called function performs stack cleanup.

System Optional keyword indicating that the external subroutine

or function uses the System calling convention. With
System routines, arguments are pushed right to left on the
stack, the caller performs stack cleanup, and the number of
arguments is specified in the AL register.

StdCall Optional keyword indicating that the external subroutine

or function uses the StdCall calling convention. With
StdCall routines, arguments are pushed right to left on the
stack and the called function performs stack cleanup.

LibName$ Must be specified if the routine is external. This parameter

specifies the name of the library or code resource
containing the external routine and must appear within
quotes.

The LibName$ parameter can include an optional path

specifying the exact location of the library or code resource.

Docbasic User’s Guide 3-135

Declare (statement) A-Z Reference

AliasName$ Alias name that must be given to provide the name of the
routine if the name parameter is not the routine's real name.
For example, the following two statements declare the
same routine:

Declare Function GetCurrentTime Lib "user" () As Integer

Declare Function GetTime Lib "user" Alias

"GetCurrentTime" _

As Integer

Use an alias when the name of an external routine conflicts

with the name of a Docbasic internal routine or when the
external routine name contains invalid characters.

The AliasName$ parameter must appear within quotes.

type Indicates the return type for functions.

For external functions, the valid return types are: Integer,

Long, String, Single, Double, Date, Boolean, and data objects.

Note: Currency, Variant, fixed-length strings, arrays, user-

defined types, and OLE automation objects cannot be
returned by external functions.

Optional Keyword indicating that the parameter is optional. All

optional parameters must be of type Variant. Furthermore,
all parameters that follow the first optional parameter must
also be optional.

If this keyword is omitted, then the parameter being

defined is required when calling this subroutine or
function.

ByVal Optional keyword indicating that the caller will pass the
parameter by value. Parameters passed by value cannot be
changed by the called routine.

ByRef Optional keyword indicating that the caller will pass the
parameter by reference. Parameters passed by reference
can be changed by the called routine. If neither ByVal or
ByRef are specified, then ByRef is assumed.

ParameterName Name of the parameter, which must follow Docbasic

naming conventions:

1. Must start with a letter.

3-136 Docbasic User’s Guide

A-Z Reference Declare (statement)

2. May contain letters, digits, and the underscore character

(_). Punctuation and type-declaration characters are not
allowed. The exclamation point (!) can appear within the
name as long as it is not the last character, in which case it
is interpreted as a type-declaration character.

3. Must not exceed 80 characters in length.

Additionally, ParameterName can end with an optional type-

declaration character specifying the type of that parameter
(i.e., any of the following characters: %, &, !, #, @).

()Indicates that the parameter is an array.

ParameterType Specifies the type of the parameter (e.g., Integer, String,

Variant, and so on). The As ParameterType clause should
only be included if ParameterName does not contain a type-
declaraction character.

As an example of passing parameters by reference, consider the following C

routine which requires a pointer to an integer as the third parameter:

int SystemParametersInfo(int,int,int *,int);

This routine would be declared as follows (notice the ByRef keyword in the third
parameter):

Declare Function SystemParametersInfo Lib "user" (ByVal action As Integer, _

ByVal uParam As Integer,ByRef pInfo As Integer, _
ByVal updateINI As Integer) As Integer

Strings can be passed by reference or by value. When they are passed by reference,
a pointer to the internal handle to the Docbasic string is passed. When they are
passed by value, Docbasic passes a 32-bit pointer to a null-terminated string (i.e.,
a C string). If an external routine modifies a passed string variable, then there must
be sufficient space within the string to hold the returned characters. This can be
accomplished using the Space function, as shown in the following example:
Declare Sub GetWindowsDirectory Lib "kernel" (ByVal dirname$, ByVal
length%)
:
Dim s As String
s = Space(128)
GetWindowsDirectory s,128

Another alternative to ensure that a string has sufficient space is to declare the
string with a fixed length:
Declare Sub GetWindowsDirectory Lib "kernel" (ByVal dirname$, ByVal
length%)
:
Dim s As String * 128'Declare a fixed-length string.

Docbasic User’s Guide 3-137

Declare (statement) A-Z Reference

GetWindowsDirectory s,len(s)'Pass it to an external subroutine.

Calling Conventions with External Routines

For external routines, the argument list must exactly match that of the referenced
routine. When calling an external subroutine or function, Docbasic needs to be told
how that routine expects to receive its parameters and who is responsible for
cleanup of the stack.

The following table describes which calling conventions are supported on which
platform, and indicates what the default calling convention is when no explicit
calling convention is specified in the Declare statement.

Table 3-25 Calling Conventions with External Routines

Platform Convention Characteristics

Win32 _stdcall Arguments are pushed right to left.

The called function performs stack cleanup.

Windows pascal Arguments are pushed left to right.

The called function performs stack cleanup

Macintosh pascal Arguments are pushed left to right.

The called function performs stack cleanup.

Passing Null Pointers

To pass a null pointer to an external procedure, declare the parameter that is to

receive the null pointer as type Any, then pass a long value 0 by value:
Declare Sub Foo Lib "sample" (ByVal lpName As Any)

Sub Main()
Sub Foo "Hello"'Pass a 32-bit pointer to a null-terminated string
Sub Foo ByVal 0&'Pass a null pointer
End Sub

Passing Data to External Routines

Table Table 3-26 shows how the different data types are passed to external routines:

Table 3-26 How Data Types are Passed to External Routines

Data Type Is passed as

ByRef Boolean A 32-bit pointer to a 2-byte value containing -1 or 0.

ByVal Boolean A 2-byte value containing -1 or 0.

ByVal Integer A 32 -bit pointer to a 2-byte short integer.

ByRef Integer A 2-byte short integer.

3-138 Docbasic User’s Guide

A-Z Reference Declare (statement)

Table 3-26 How Data Types are Passed to External Routines

Data Type Is passed as

ByVal Long A 32-bit pointer to a 4-byte long integer.

ByRef Long A 4-byte long integer.

ByRef Single A 32-bit pointer to a 4-byte IEEE floating point value (a float).

ByVal Single A 4-byte IEEE floating point value (a float).

ByRef Double A 32-bit-pointer to an 8-byte IEEE floating point value (adouble).

ByVal Double An 8-byte IEEE floating point value (a double).

ByRef String A 32-bit pointer to a null-terminated string. With strings containing

embedded nulls (Chr$(0)), it is not possible to determine which null
represents the end of the string - therefore, the first null is considered
the string terminator.
An external routine can freely change the content of a string. It
cannot, however, write beyond the end of the null-terminator.

ByVal String A 2-byte internal value representing the string. This value can only
be used by external routines written specifically for Docbasic.

ByRef Variant A 32-bit pointer to a 16-byte internal variant structure. This structure
contains a 2-byte type (the same as that returne by the VarType
function), followed by 6-bytes of slop (for alignment), followed by 8-
bytes containing the value.

ByVal Variant A 16-byte variant structure. This structure contains a 2-byte type (the
same as that returned by the VarType function), followed by 6-bytes
of slop (for alignment), followed by 8-bytes containing the value.

ByVal Object For data objects, a 32-bit pointer to a 4-byte unsigned long integer.
This value can only be used by external routines written specifically
for Docbasic.
For OLE Automation objects, a 32-bit pointer to an LPDISPATCH
handle is passed.

ByRef Object For data objects, a 32-bit pointer to a 4-byte unsigned long integer
that references the object. This value can only be used by external
routines written specifically for Docbasic.
For OLE Automation objects, a 32-bit pointer to a 4-byte internal ID is
passed. This value can only be used by external routines written
specifically for Docbasic.

User-defined type A 32-bit pointer to the structure. User-defined types can only be
passed by reference.
It is important to remember that structures in Docbasic are packed on
2-byte boundaries, meaning that the individual structure members
may not be aligned consistently with similar structures declared in C.

Arrays A 32-bit pointer to a packed array of elements of the given type.

Arrays can only be passed by reference.

Dialogs Dialogs cannot be passed to external routines.

Docbasic User’s Guide 3-139

Declare (statement) A-Z Reference

Only variable-length strings can be passed to external routines; fixed-length

strings are automatically converted to variable-length strings.

Docbasic passes data to external functions consistent with that routine's prototype
as defined by the Declare statement. There is one exception to this rule: you can
override ByRef parameters using the ByVal keyword when passing individual
parameters. The following example shows a number of different ways to pass an
Integer to an external routine called Foo:
Declare Sub Foo Lib "MyLib" (ByRef i As Integer)

Sub Main
Dim i As Integer
i = 6
Foo 6 'Passes a temporary integer (value 6) by reference
Foo i 'Passes variable "i" by reference
Foo (i) 'Passes a temporary integer (value 6) by reference
Foo i + 1'Passes temporary integer (value 7) by reference
Foo ByVal i'Passes i by value
End Sub

The above example shows that the only way to override passing a value by
reference is to use the ByVal keyword.

Note: Use caution when using the ByVal keyword in this way. The external routine
Foo expects to receive a pointer to an Integer—a 32-bit value; using ByVal causes
Docbasic to pass the Integer by value—a 16-bit value. Passing data of the wrong
size to any external routine will have unpredictable results.

Example
Declare Function IsLoaded% Lib "Kernel" Alias "GetModuleHandle" (ByVal
name$)

Declare Function GetProfileString Lib "Kernel" (ByVal SName$,ByVal

KName$,_
ByVal Def$,ByVal Ret$,ByVal Size%) As Integer

Sub Main()
SName$ = "Intl"'Win.ini section name.
KName$ = "sCountry"'Win.ini country setting.
ret$ = String$(255, 0)'Initialize return string.

If GetProfileString(SName$,KName$,"",ret$,Len(ret$)) Then
MsgBox "Your country setting is: " & ret$
Else
MsgBox "There is no country setting in your win.ini file."
End If

If IsLoaded("Progman") Then
MsgBox "Progman is loaded."
Else
MsgBox "Progman is not loaded."
End If
End Sub

3-140 Docbasic User’s Guide

A-Z Reference Declare (statement)

Platform(s)
All platforms support Declare for forward referencing.

The following platforms currently support the use of Declare for referencing
external routines: Windows, Win32, Macintosh. See below for details.

Platform Notes: Windows

Under Windows, external routines are contained in DLLs. The libraries containing
the routines are loaded when the routine is called for the first time (i.e., not when
the procedure is loaded). This allows a procedure to reference external DLLs that
potentially do not exist.

All the Windows API routines are contained in DLLs, such as "user", "kernel", and
"gdi". The file extension ".exe" is implied if another extension is not given.

If the libname$ parameter does not contain an explicit path to the DLL, the
following search will be performed for the DLL (in this order):

1. The current directory

2. The Windows directory

3. The Windows system directory

4. The directory containing Docbasic

5. All directories listed in the path environment variable

If the first character of aliasname$ is #, then the remainder of the characters specify
the ordinal number of the routine to be called. For example, the following two
statements are equivalent (under Windows, GetCurrentTime is defined as ordinal
15 in the user.exe module):

Declare Function GetTime Lib "user" Alias "GetCurrentTime" () As Integer

Declare Function GetTime Lib "user" Alias "#15" () As Integer

Under Windows, the names of external routines declared using the CDecl keyword
are usually preceeded with an underscore character. When Docbasic searches for
your external routine by name, it first attempts to load the routine exactly as
specified. If unsuccessful, Docbasic makes a second attempt by prepending an
underscore character to the specified name. If both attempts fail, then Docbasic
generates a runtime error.

Windows has a limitation that prevents Double, Single, and Date values from
being returned from routines declared with the CDecl keyword. Routines that
return data of these types should be declared Pascal.

Docbasic User’s Guide 3-141

Declare (statement) A-Z Reference

Platform Notes: Win32

Under Win32, eternal routines are contained in DLLs. The libraries containing the
routines are loaded when the routine is called for the first time (i.e., not when the
procedure is loaded). This allows a procedure to reference external DLLs that
potentially do not exist.

All the Win32 API routines are contained in DLLs, such as "user32", "kernel32", and
"gdi32". The file extension ".exe" is implied if another extension is not given.

The Pascal and StdCall calling conventions are identical on Win32 platforms.
Furthermore, on this platform, the arguments are passed using C ordering
regardless of the calling convention -- right to left on the stack.

If the libname$ parameter does not contain an explicit path to the DLL, the
following search will be performed for the DLL (in this order):

1. The directory containing Docbasic

2. The current directory

3. The Windows system directory

4. The Windows directory

5. All directories listed in the path environment variable

If the first character of aliasname$ is #, then the remainder of the characters specify
the ordinal number of the routine to be called. For example, the following two
statements are equivalent (under Win32, GetCurrentTime is defined as
GetTickCount, ordinal 300, in kernel32.dll):

Declare Function GetTime Lib "kernel32.dll" Alias "GetTickCount" () As Long

Declare Function GetTime Lib "kernel32.dll" Alias "#300" () As Long

Platform Notes: Macintosh

On the Macintosh, external routines are implemented in code resources. If a code
resource does not contain an explicit folder name, then Docbasic looks in the
following areas:

1. The current folder

2. The folder containing the application

3. The Extension folder within the System folder

3-142 Docbasic User’s Guide

A-Z Reference Declare (statement)

When using the C calling convention (with the CDecl keyword), Docbasic assumes
4-byte integers (the int data type in C). This may be problematic, as some compilers
on the Macintosh assume 2-byte integers.

On the Macintosh, the code resource type is specified in aliasname$ as follows:

ResourceType Any valid four-character name containing the type of the

resource. If this parameter is omitted, then CODE is
assumed.

ResourceName Name of the procedure in the code resource. If this

parameter is omitted, then ResourceName is assumed to be
the same as name.

If the libname$ parameter does not contain an explicit path to the DLL, the
following search will be performed for the DLL (in this order):

1. The current directory.

2. All directories listed in the path environment variable.

Note: Docbasic does not support passing of Single and Double values to external
16-bit subroutines or functions. These data types are also not supported as return
values from external 16-bit functions.

If the first character of aliasname$ is #, then the remainder of the characters specify
the ordinal number of the routine to be called.

See Also
Call (statement)
Sub...End Sub (statement)
Function...End Function (statement)

Docbasic User’s Guide 3-143

DefType (statement) A-Z Reference

DefType (statement)

Establishes the default type assigned to undeclared or untyped variables.

Syntax
DefInt letterrange
DefLng letterrange
DefStr letterrange
DefSng letterrange
DefDbl letterrange
DefCur letterrange
DefObj letterrange
DefVar letterrange
DefBool letterrange
DefDate letterrange

Description
The DefType statement controls automatic type declaration of variables. Normally,
if a variable is encountered that hasn't yet been declared with the Dim, Public, or
Private statement or does not appear with an explicit type-declaration character,
then that variable is declared implicitly as a variant (DefVar A-Z). This can be
changed using the DefType statement to specify starting letter ranges for types
other than integer. The letterrange parameter is used to specify starting letters.
Thus, any variable that begins with a specified character will be declared using the
specified type.

The syntax for letterrange is:

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

DefType variable types are superseded by an explicit type declarationusing

either a type-declaration character or the Dim, Public, or Private statement.

The DefType statement only affects how Docbasic compiles procedures and has no
effect at runtime.

The DefType statement can only appear outside all Sub and Function declarations.

The following table describes the data types referenced by the different variations
of the DefType statement:

Table 3-27 DefType Variations and Corresponding Data Types

Statement Data Type

DefInt Integer

3-144 Docbasic User’s Guide

A-Z Reference DefType (statement)

Table 3-27 DefType Variations and Corresponding Data Types

Statement Data Type

DefLng Long

DefStr String

DefSng Single

DefDbl Double

DefCur Currency

DefObj Object

DefVar Variant

DefBool Boolean

DefDate Date

Example
DefStr a-l
DefLng m-r
DefSng s-u
DefDbl v-w
DefInt x-z

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

Sub Main()
a = 100.52
m = 100.52
s = 100.52
v = 100.52
x = 100.52
msg = "The values are:"
msg = msg & "(String) a: " & a
msg = msg & "(Long) m: " & m
msg = msg & "(Single) s: " & s
msg = msg & "(Double) v: " & v
msg = msg & "(Integer) x: " & x
MsgBox msg
End Sub

Platform(s)
All.

Docbasic User’s Guide 3-145

DefType (statement) A-Z Reference

See Also
Boolean (data type)
Currency (data type)
Date (data type)
Double (data type)
Integer (data type)
Long (data type)
Object (data type)
Single (data type)
String (data type)
Variant (data type)

3-146 Docbasic User’s Guide

A-Z Reference Dim (statement)

Dim (statement)

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

Syntax
Dim name [(<subscripts>)] [As [New] type] [,name [(<subscripts>)] [As
[New] type]]...

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

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

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

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

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

Dynamic arrays are declared by not specifying any bounds:

Dim a()

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

A Dim statement within a subroutine or function declares variables local to that

subroutine or function. If the Dim statement appears outside of any subroutine or
function declaration, then that variable has the same scope as variables declared
with the Private statement.

Fixed-Length Strings

Fixed-length strings are declared by adding a length to the String type-declaration

character:

Docbasic User’s Guide 3-147

Dim (statement) A-Z Reference

Dim name As String * length

where length is a literal number specifying the string's length.

Implicit Variable Declaration

If Docbasic encounters a variable that has not been explicitly declared with Dim,
then the variable will be implicitly declared using the specified type-declaration
character (#, %, @, $, or &). If the variable appears without a type-declaration
character, then the first letter is matched against any pending DefType statements,
using the specified type if found. If no DefType statement has been encountered
corresponding to the first letter of the variable name, then Variant is used.

Creating New Objects

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

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

When that variable goes out of scope (i.e., the Sub or Function procedure in which
the variable is declared ends), the application is notified. The application then
performs some appropriate action, such as destroying the physical object.

Initial Values

All declared variables are given initial values, as described in the following table:

Table 3-28 Effect of Data Type on Initial Value of Declared Variables

Data Type Initial Value

Integer 0

Long 0

Double 0.0

Single 0.0

Date December 31, 1899 00:00:00

Currency 0.0

Boolean False

Object Nothing

3-148 Docbasic User’s Guide

A-Z Reference Dim (statement)

Table 3-28 Effect of Data Type on Initial Value of Declared Variables

Data Type Initial Value

Variant Empty

String "" (zero-length string)

User-defined type Each element of the structure is given an initial value, as described above.

Arrays Each element of the array is given an initial value, as described above.

Naming Conventions

Variable names must follow these naming rules:

Must start with a letter.

May contain letters, digits, and the underscore character (_); punctuation is
not allowed. The exclamation point (!) can appear within the name as long
as it is not the last character, in which case it is interpreted as a type-
declaration character.

The last character of the name can be any of the following type-declaration
characters: #, @, %, !, &, and $.

Must not exceed 80 characters in length.

Cannot be a reserved word.

Examples
The following examples use the Dim statement to declare various variable types.
Sub Main()
Dim i As Integer
Dim l& 'long
Dim s As Single
Dim d# 'double
Dim c$ 'string
Dim MyArray(10) As Integer'10 element integer array
Dim MyStrings$(2,10)'2-10 element string arrays
Dim Filenames$(5 to 10)'6 element string array
Dim Values(1 to 10, 100 to 200)'111 element variant array
End Sub

Platform(s)
All.

Docbasic User’s Guide 3-149

Dim (statement) A-Z Reference

See Also
Redim (statement)
Public (statement)
Private (statement)
Option Base (statement)

3-150 Docbasic User’s Guide

A-Z Reference Dir, Dir$ (functions)

Dir, Dir$ (functions)

Returns a String containing the first or next file matching filespec$.

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

Argument Descriptions

filespec$ String containing a file specification.

If this parameter is specified, then Dir$ returns the first file

matching this file specification. If this parameter is omitted,
then the next file matching the initial file specification is
returned.

If no path is specified in filespec$, then the current directory

is used.

attributes Integer specifying attributes of files you want included in

the list, as described below. If omitted, then only the
normal, read-only, and archive files are returned.

Description
If filespec$ is specified, then the first file matching that filespec$ is returned. If
filespec$ is not specified, then the next file matching the initial filespec$ is returned.

Dir$ returns a String, whereas Dir returns a String variant.

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

If there is no matching filespec$, then a zero-length string is returned.

Wildcards

The filespec$ argument can include wildcards, such as * and ?. The * character
matches any sequence of zero or more characters, whereas the ? character matches
any single character. Multiple *'s and ?'s can appear within the expression to form
complete searching patterns. The following table shows some examples:

Docbasic User’s Guide 3-151

Dir, Dir$ (functions) A-Z Reference

Table 3-29 Wildcard Examples for Filespec$ Parameter

This Pattern Matches these files Doesn’t match these files

*S*.TXT SAMPLE.TXT SAMPLE

GOOSE.TXT SAMPLE.DAT
SAMS.TXT

C*T.TXT CAT.TXT CAP.TXT

ACATS.TXT

C*T CAT CAT.DOC

CAP.TXT

C?T CAT CAT.TXT

CUT CAPIT
CT

* (All files)

Attributes

You can control which files are included in the search by specifying the optional
attributes parameter. The Dir, Dir$ functions always return all normal, read-only,
and archive files (ebNormal Or ebReadOnly Or ebArchive). To include additional
files, you can specify any combination of the following attributes (combined with
the Or operator):

Table 3-30 Constants for Use With Attribute Parameter

Constant Value Includes

ebNormal 0 Read-only, archive, subdir, and none

ebHidden 2 Hidden files

ebSystem 4 System files

ebVolume 8 Volume label

Example
This example dimensions a null array and fills it with directory entries. The result
is displayed in a dialog box.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
Dim a$(10)
a(1) = Dir$("*.*")
i% = 1
While (a(i%) <> "") And (i% < 10)
i% = i% + 1
a(i%) = Dir$
Wend

3-152 Docbasic User’s Guide

A-Z Reference Dir, Dir$ (functions)

MsgBox a(1) & crlf & a(2) & crlf & a(3) & crlf & a(4)
End Sub

Platform(s)
All.

Platform Notes: Macintosh

The Macintosh does not support wildcard characters such as * and ?. These are
valid filename characters. Instead of wildcards, the Macintosh uses the MacID
function to specify a collection of files of the same type. The syntax for this function
is:
Dir$(filespec$,MacID(text$))

The text$ parameter is a four-character string containing a file type, a resource type,
an application signature, or an Apple event. A runtime error occurs if the MacID
function is used on platforms other than the Macintosh.

When the MacID function is used, the filespec$ parameter specifies the directory in
which to search for files of the indicated type.

Platform Notes: UNIX

On UNIX platforms, the hidden file attribute corresponds to files without the read
or write attributes.

See Also
ChDir (statement)
ChDrive (statement)
CurDir, CurDir$ (functions)
MkDir (statement)
RmDir (statement)
FileList (statement)

Docbasic User’s Guide 3-153

DiskDrives (statement) A-Z Reference

DiskDrives (statement)

Fills the specified String or Variant array with a list of valid drive letters.

Syntax
DiskDrives array()

Description
The array() parameter specifies either a zero- or a one-dimensioned array of strings
or variants. The array can be either dynamic or fixed.

If array() is dynamic, then it will be redimensioned to exactly hold the new number
of elements. If there are no elements, then the array will be redimensioned to
contain no dimensions. You can use the LBound, UBound, and ArrayDims
functions to determine the number and size of the new array's dimensions.

If the array is fixed, each array element is first erased, then the new elements are
placed into the array. If there are fewer elements than will fit in the array, then the
remaining elements are initialized to zero-length strings (for String arrays) or
Empty (for Variant arrays). A runtime error results if the array is too small to hold
the new elements.

Example
This example builds and displays an array containing the first three available disk
drives.
Sub Main()
Dim drive$()
DiskDrives drive$
MsgBox "Available Disk Drives " + drive$
End Sub

Platform(s)
Windows, Win32.

See Also
ChDrive (statement)
DiskFree (function)

3-154 Docbasic User’s Guide

A-Z Reference DiskFree (function)

DiskFree (function)

Returns a Long containing the free space (in bytes) available on the specified drive.

Syntax
DiskFree&([drive$])

Description
If drive$ is zero-length or not specified, then the current drive is assumed.

Only the first character of the drive$ string is used.

Example
This example uses DiskFree to set the value of i and then displays the result in a
message box.
Sub Main()
s$ = "c"
i# = DiskFree(s$)
MsgBox "Free disk space on drive '" & s$ & "' is: " & i#
End Sub

Platform(s)
All.

Platform Notes:
On systems that do not support drive letters, the drive$ parameter specifies the
name of the path from which to retrieve the free disk space.

See Also
ChDrive (statement)
DiskDrives (statement)

Docbasic User’s Guide 3-155

dmAPIExec (function) A-Z Reference

dmAPIExec (function)

Invokes a method. Use with methods that perform operations but do not set or
retrieve values, such as the Disconnect method. Returns a Boolean, True if the
method executed successfully, False otherwise.

Syntax
dmAPIExec (method$)

Argument Descriptions

method$ String containing a method call, including arguments to the

method.

Example
This example displays an alert message in a dialog box.
Sub Main()
ret% = dmAPIExec("alert,c,dcapp,A message using the API")
End Sub

Platform(s)
All.

See Also
dmAPIGet (function)
dmAPISet (function)

3-156 Docbasic User’s Guide

A-Z Reference dmAPIGet (function)

dmAPIGet (function)

Invokes a method. Use with methods that return data or objects to the user or
application, such as the Connect method. Returns a pointer to a data storage area.

Syntax
dmAPIGet (method$)

Argument Descriptions

method$ String containing a method call, including arguments to the

method.

Description
When you execute a method that returns data, the system places the data in the
client memory cache associated with the running application. At this point, the
application can utilize the data. If the method was a Getfile method, the server
copies the requested file to the location specified in the method call.

Each time you issue a dmAPIGet function, the data returned by the invoked
method overwrites any existing data in the storage area. Consequently, do not
execute consecutive dmAPIGet functions without retrieving the data from the first
call before you issue the second.

The return value can be NULL ("").

Example
This example returns the object ID of the currently active window in Workspace.
Sub Main()
id$ = dmAPIGet("getdata,c,dcapp,active_window")
MsgBox "The active window ID is: " + id$
End Sub

Platform(s)
All.

Docbasic User’s Guide 3-157

dmAPIGet (function) A-Z Reference

See Also
dmAPIExec (function)
dmAPISet (function)

3-158 Docbasic User’s Guide

A-Z Reference dmAPISet (function)

dmAPISet (function)

Invokes a method. Use with methods that write data to the docbase or assign
values to attributes, such as the Set method. Returns a Boolean, True if the method
executed successfully, False otherwise.

Syntax
dmAPISet (method$, newvalue$)

Argument Descriptions

method$ String containing a method call, including arguments to the

method.

newvalue$ String specifying the value you want to asign to the

attribute specified in the method.

Example
This example changes the title of the Workspace application window to New Title.
Sub Main()
ret% = dmAPISet("setdata,c,dcapp,title","New Title")
End Sub

Platform(s)
All.

See Also
dmAPIExec (function)
dmAPIGet (function)

Docbasic User’s Guide 3-159

dmExit (function) A-Z Reference

dmExit (function)

Terminates a procedure and returns a status indicator to the operating system.

Syntax
dmExit (return_status)

Argument Descriptions

return_status A numeric value returned to the operating system

indicating the exit status of the procedure. Typically a
value of 0 indicates a normal exit, and a nonzero value
indicates an error.
On UNIX platforms, the return_status can range from 0 to
255. On Windows NT, it can be any long number.

Description
The dmExit function applies to procedures stored in dm_method objects on the
server. dmExit is non-operational if executed in a procedure for customizing
Workspace.

The dmExit function closes all files before terminating the procedure.

Example
This example checks to see whether a user belongs to a certain group. If so, dmExit
passes 0 to the operating system; otherwise dmExit returns -1. For simplicity error
handling is ignored.
Function check_group(ByVal usr As String, ByVal grp As String) As Integer

Dim buff As String

Dim value As Integer
Dim status As Integer
Dim col_id As String

buff = "query,c,select count(*) as exist from dm_group " &_

"where group_name = '" & grp & "' and " &_
"any users_names = '" & usr & "'"

col_id = dmAPIGet(buff)
buff = "next,c," & col_id
status = dmAPIExec(buff)
buff = "get,c," & col_id & ",exist"
value = Val(dmAPIGet(buff))

3-160 Docbasic User’s Guide

A-Z Reference dmExit (function)

buff = "close,c," & col_id

status = dmAPIExec(buff)
If value = 0 Then
status = -1
Else
status = 0
End If
dmExit(status)
End Function

Platform(s)
All.

See Also
dmAPIExec (function)
dmAPIGet (function)
dmAPISet (function)

Docbasic User’s Guide 3-161

Do...Loop (statement) A-Z Reference

Do...Loop (statement)

Repeats a block of Docbasic statements while a condition is True or until a

condition is True.

Syntax 1
Do {While | Until} condition statements Loop

Syntax 2
Do
statements
Loop {While | Until} condition

Syntax 3
Do
statements
Loop

Description
If the {While | Until} conditional clause is not specified, then the loop repeats the
statements forever (or until Docbasic encounters an Exit Do statement).

The condition parameter specifies any Boolean expression.

Examples
This first example uses the Do...While statement, which performs the iteration,
then checks the condition, and repeats if the condition is True.
Sub Main()
Dim a$(100)
i% = -1
Do
i% = i% + 1
If i% = 0 Then
a(i%) = Dir$("*")
Else
a(i%) = Dir$
End If
Loop While (a(i%) <> "" And i% <= 99)
r% = SelectBox(i% & " files found",,a)

3-162 Docbasic User’s Guide

A-Z Reference Do...Loop (statement)

This second example uses the Do While...Loop, which checks the condition and
then repeats if the condition is True.
Dim a$(100)
i% = 0
a(i%) = Dir$("*")
Do While a(i%) <> "" And i% <= 99
i% = i% + 1
a(i%) = Dir$
Loop
r% = SelectBox(i% & " files found",,a)

This third example uses the Do Until...Loop, which does the iteration and then
checks the condition and repeats if the condition is True.
Dim a$(100)
i% = 0
a(i%) = Dir$("*")
Do Until a(i%) = "" Or i% = 100
i% = i% + 1
a(i%) = Dir$
Loop
r% = SelectBox(i% & " files found",,a)

This last example uses the Do...Until Loop, which performs the iteration first,
checks the condition, and repeats if the condition is True.
Dim a$(100)
i% = -1
Do
i% = i% + 1
If i% = 0 Then
a(i%) = Dir$("*")
Else
a(i%) = Dir$
End If
Loop Until (a(i%) = "" Or i% = 100)
r% = SelectBox(i% & " files found",,a)
End Sub

Platform(s)
All.

Platform Notes: Windows, Win32

Due to errors in program logic, you can inadvertently create infinite loops in your
code. Under Windows and Win 32, you can break out of infinite loops using
Ctrl+Break.

Docbasic User’s Guide 3-163

Do...Loop (statement) A-Z Reference

Platform Notes: UNIX

Due to errors in program logic, you can inadvertently create infinite loops in your
code. Under UNIX, you can break out of infinite loops using Ctrl+C.

Platform Notes: Macintosh

Due to errors in program logic, you can inadvertently create infinite loops in your
code. On the Macintosh, you can break out of infinite loops using
Command+Period.

See Also
For...Next (statement)
While ...WEnd (statement)

3-164 Docbasic User’s Guide

A-Z Reference Double (data type)

Double (data type)

A data type used to declare variables capable of holding real numbers with 15-16
digits of precision.

Syntax
Double

Description
Double variables are used to hold numbers within the following ranges:

Table 3-31 Range of Values for the Double Data Type

Sign Range

Negative -1.797693134862315E308 <= double <= -4.94066E-324

Positive 4.94066E-324 <= double <= 1.797693134862315E308

The type-declaration character for Double is #.

Storage

Internally, doubles are 8-byte (64-bit) IEEE values. Thus, when appearing within a
structure, doubles require 8 bytes of storage. When used with binary or random
files, 8 bytes of storage are required.

Each Double consists of the following

A 1-bit sign

An 11-bit exponent

A 53-bit significand (mantissa)

Platform(s)
All.

See Also
Boolean (data type)
Currency (data type)
Date (data type)
Integer (data type)

Docbasic User’s Guide 3-165

Double (data type) A-Z Reference

Long (data type)

Object (data type)
Single (data type)
String (data type)
Variant (data type)
DefType (statement)
CDbl (function)

3-166 Docbasic User’s Guide

A-Z Reference ebBoolean (constant)

ebBoolean (constant)

Number representing the type of a Boolean variant.

Description
This constant is equal to 11.

Example
Sub Main()
Dim MyVariant as variant
MyVariant = True
If VarType(MyVariant) = ebBoolean Then
MyVariant = 5.5
End If
End Sub

Platform(s)
All.

See Also
VarType (function)
Variant (data type)

Docbasic User’s Guide 3-167

ebCancel (constant) A-Z Reference

ebCancel (constant)

Returned by the MsgBox function when the Cancel button is chosen.

Description
This constant is equal to 2.

Example
Sub Main()
'Invoke MsgBox and check whether the Cancel button was pressed.
rc% = MsgBox("Are you sure you want to quit?",ebOKCancel)
If rc% = ebCancel Then
MsgBox "The user clicked Cancel."
End If
End Sub

Platform(s)
Windows, Win32, Macintosh.

See Also
MsgBox (function)
MsgBox (statement)

3-168 Docbasic User’s Guide

A-Z Reference ebCritical (constant)

ebCritical (constant)

Used with the MsgBox statement and function.

Description
This constant is equal to 16.

Example
Sub Main()
'Invoke MsgBox with Abort, Retry, and Ignore buttons and a Stop icon.
rc% = MsgBox("Disk drive door is open.",ebAbortRetryIgnore Or
ebCritical)
If rc% = 3 Then
'The user selected Abort from the dialog box.
MsgBox "The user clicked Abort."
End If
End Sub

Platform(s)
Windows, Win32, Macintosh.

See Also
MsgBox (function)
MsgBox (statement)

Docbasic User’s Guide 3-169

ebCurrency (constant) A-Z Reference

ebCurrency (constant)

Number representing the type of a Currency variant.

Description
This constant is equal to 6.

Example
This example checks to see whether a variant is of type Currency.
Sub Main()
Dim MyVariant
If VarType(MyVariant) = ebCurrency Then
MsgBox "Variant is Currency."
End If
End Sub

Platform(s)
All.

See Also
VarType (function)
Variant (data type)

3-170 Docbasic User’s Guide

A-Z Reference ebDataObject (constant)

ebDataObject (constant)

Number representing the type of a data object variant.

Description
This constant is equal to 13.

Example
This example checks to see whether a variable is a data object.
Sub Main()
Dim MyVariant as Variant
If VarType(MyVariant) = ebDataObject Then
MsgBox "Variant contains a data object."
End If
End Sub

Platform(s)
All.

See Also
VarType (function)
Variant (data type)

Docbasic User’s Guide 3-171

ebDate (constant) A-Z Reference

ebDate (constant)

Number representing the type of a Date variant.

Description
This constant is equal to 7.

Example
Sub Main()
Dim MyVariant as Variant
If VarType(MyVariant) = ebDate Then
MsgBox "This variable is a Date type!"
Else
MsgBox "This variable is not a Date type!"
End If
End Sub

Platform(s)
All.

See Also
VarType (function)
Variant (data type)

3-172 Docbasic User’s Guide

A-Z Reference ebEmpty (constant)

ebEmpty (constant)

Number representing the type of an Empty variant.

Description
This constant is equal to 0.

Example
Sub Main()
Dim MyVariant as Variant
If VarType(MyVariant) = ebEmpty Then
MsgBox "No data has been input yet!"
End If
End Sub

Platform(s)
All.

See Also
VarType (function)
Variant (data type)

Docbasic User’s Guide 3-173

ebError (constant) A-Z Reference

ebError (constant)

Number representing the type of an error variant.

Description
This constant is equal to 10.

Example
This example checks to see whether a variable is an error.
Function Div(ByVal a As Variant,ByVal b As Variant) As Variant
If b = 0 Then
Div = CVErr(20000)
Else
Div = a / b
End If
End Function

Sub Main()
Dim Result as Variant
Randomize
Result = Div(10,Random(0,2))
If VarType(Result) = ebError Then
MsgBox "An error occurred"
Else
MsgBox "The result of the division is: " & Result
End If
End Sub

Platform(s)
All.

See Also
VarType (function)
Variant (data type)

3-174 Docbasic User’s Guide

A-Z Reference ebHidden (constant)

ebHidden (constant)

Bit position of a file attribute indicating that a file is hidden.

Description
This constant is equal to 2.

Example
This example dimensions an array and fills it with filenames using the ebHidden
attribute.
Sub Main()
Dim s$()
FileList s$,"*",ebHidden
If ArrayDims(s$) = 0 Then
MsgBox "No hidden files found!"
End
End If
MsgBox("Hidden Files " + s$)
End Sub

Platform(s)
Windows, Win32, Macintosh.

See Also
Dir, Dir$ (functions)
FileList (statement)
SetAttr (statement)
FileAttr (function)

Docbasic User’s Guide 3-175

ebInteger (constant) A-Z Reference

ebInteger (constant)

Number representing the type of an Integer variant.

Description
This constant is equal to 2.

Example
This example defines a function that returns True if a variant contains an Integer
value (either a 16-bit or 32-bit Integer).
Function IsInteger(v As Variant) As Boolean
If VarType(v) = ebInteger Or VarType(v) = ebLong Then
IsInteger = True
Else
IsInteger = False
End If
End Function

Sub Main()
Dim i as Integer
i = 123
If IsInteger(i) then
Msgbox "i is an Integer."
End If
End Sub

Platform(s)
All.

See Also
VarType (function)
Variant (data type)

3-176 Docbasic User’s Guide

A-Z Reference ebLong (constant)

ebLong (constant)

Number representing the type of a Long variant.

Description
This constant is equal to 3.

Example
See ebInteger (constant).

Platform(s)
All.

See Also
VarType (function)
Variant (data type)

Docbasic User’s Guide 3-177

ebNone (constant) A-Z Reference

ebNone (constant)

Bit value used to select files with no other attributes.

Description
This value can be used with the Dir$ and FileList commands. These functions will
return only files with no attributes set when used with this constant. This constant
is equal to 64.

Example
This example dimensions an array and fills it with filenames with no attributes set.
Sub Main()
Dim s$()
FileList s$,"*",ebNone
If ArrayDims(s$) = 0 Then
MsgBox "No files found without attributes!"
End
End If
MsgBox "Files with attributes " + s$
End Sub

Platform(s)
All.

See Also
Dir, Dir$ (functions)
FileList (statement)
SetAttr (statement)
FileAttr (function)

3-178 Docbasic User’s Guide

A-Z Reference ebNormal (constant)

ebNormal (constant)

Used to search for "normal" files.

Description
This value can be used with the Dir$ and FileList commands and will return files
with the Archive, Volume, ReadOnly, or no attributes set. It will not match files
with Hidden, System, or Directory attributes. This constant is equal to 0.

Example
This example dimensions an array and fills it with filenames with Normal
attributes.
Sub Main()
Dim s$()
FileList s$,"*", ebNormal
If ArrayDims(s$) = 0 Then
MsgBox "No filesfound!"
End
End If
MsgBox "Normal files " + s$
End Sub

Platform(s)
All.

See Also
Dir, Dir$ (functions)
FileList (statement)
SetAttr (statement)
FileAttr (function)

Docbasic User’s Guide 3-179

ebNull (constant) A-Z Reference

ebNull (constant)

Number representing the type of a Null variant.

Description
This constant is equal to 1.

Example
Sub Main()
Dim MyVariant
MyVariant = Null
If VarType(MyVariant) = ebNull Then
MsgBox "This variant is Null"
End If
End Sub

Platform(s)
All.

See Also
VarType (function)
Variant (data type)

3-180 Docbasic User’s Guide

A-Z Reference ebObject (constant)

ebObject (constant)

Number representing the type of an Object variant (an OLE automation object).

Description
This constant is equal to 9.

Example
Sub Main()
If VarType(MyVariant) = ebObject Then
MsgBox MyVariant.Value
End If
End Sub

Platform(s)
All.

See Also
VarType (function)
Variant (data type)

Docbasic User’s Guide 3-181

ebReadOnly (constant) A-Z Reference

ebReadOnly (constant)

Bit position of a file attribute indicating that a file is read-only.

Description
This constant is equal to 1.

Example
This example dimensions an array and fills it with filenames with ReadOnly
attributes.
Sub Main()
Dim s$()
FileList s$, "*", ebReadOnly
If ArrayDims(s$) = 0 Then
MsgBox "No read only files found!"
End
End If
MsgBox "ReadOnly Files " + s$
End Sub

Platform(s)
All.

See Also
Dir, Dir$ (functions)
FileList (statement)
SetAttr (statement)
FileAttr (function)

3-182 Docbasic User’s Guide

A-Z Reference ebSingle (constant)

ebSingle (constant)

Number representing the type of a Single variant.

Description
This constant is equal to 4.

Example
This example defines a function that returns True if the passed variant is a Real
number.
Function IsReal(v As Variant) As Boolean
If VarType(v) = ebSingle Or VarType(v) = ebDouble Then
IsReal = True
Else
IsReal = False
End If
End Function

Sub Main()
Dim i as Integer
i = 123
If IsReal(i) then
Msgbox "i is Real."
End If
End Sub

Platform(s)
All.

See Also
VarType (function)
Variant (data type)

Docbasic User’s Guide 3-183

ebString (constant) A-Z Reference

ebString (constant)

Number representing the type of a String variant.

Description
This constant is equal to 8.

Example
Sub Main()
Dim MyVariant as variant
MyVariant = "This is a test."
If VarType(MyVariant) = ebString Then
MsgBox "Variant is a string."
End If
End Sub

Platform(s)
All.

See Also
VarType (function)
Variant (data type)

3-184 Docbasic User’s Guide

A-Z Reference ebSystem (constant)

ebSystem (constant)

Bit position of a file attribute indicating that a file is a system file.

Description
This constant is equal to 4.

Example
This example dimensions an array and fills it with filenames with System
attributes.
Sub Main()
Dim s$()
FileList s$,"*",ebSystem
MsgBox "System files " + s$
End Sub

Platform(s)
Windows, Win32.

See Also
Dir, Dir$ (functions)
FileList (statement)
SetAttr (statement)
FileAttr (function)

Docbasic User’s Guide 3-185

ebSystemModal (constant) A-Z Reference

ebSystemModal (constant)

Used with the MsgBox statement and function.

Description
This constant is equal to 4096.

Example
Sub Main()
MsgBox "All applications are halted!",ebSystemModal
End Sub

Platform(s)
Windows, Win32, Macintosh.

See Also
Constants (topic)
MsgBox (function)
MsgBox (statement)

3-186 Docbasic User’s Guide

A-Z Reference ebVariant (constant)

ebVariant (constant)

Number representing the type of a Variant.

Description
Currently, it is not possible for variants to use this subtype. This constant is equal
to 12.

Platform(s)
All.

See Also
VarType (function)
Variant (data type)

Docbasic User’s Guide 3-187

ebVolume (constant) A-Z Reference

ebVolume (constant)

Bit position of a file attribute indicating that a file is the volume label.

Description
This constant is equal to 8.

Example
This example dimensions an array and fills it with filenames with Volume
attributes.
Sub Main()
Dim s$()
FileList s$, "*", ebVolume
If ArrayDims(s$) > 0 Then
MsgBox "The volume name is: " & s(1)
Else
MsgBox "No volumes found."
End If
End Sub

Platform(s)
Windows, Win32.

See Also
Dir, Dir$ (functions)
FileList (statement)
SetAttr (statement)
FileAttr (function)

3-188 Docbasic User’s Guide

A-Z Reference Empty (constant)

Empty (constant)

Constant representing a variant of type 0.

Description
The Empty value has special meaning indicating that a Variant is uninitialized.

When Empty is assigned to numbers, the value 0 is assigned. When Empty is

assigned to a String, the string is assigned a zero-length string.

Example
Sub Main()
Dim a As Variant
a = Empty
End Sub

Platform(s)
All.

See Also
Null (constant)
Variant (data type)
VarType (function)

Docbasic User’s Guide 3-189

End (statement) A-Z Reference

End (statement)

Terminates execution of the current procedure, closing all open files.

Syntax
End

Example
This example uses the End statement to stop execution.
Sub Main()
MsgBox "The next line will terminate the procedure."
End
End Sub

Platform(s)
All.

See Also
Close (statement)
Stop (statement)
Exit For (statement)
Exit Do (statement)
Exit Function (statement)
Exit Sub (function)

3-190 Docbasic User’s Guide

A-Z Reference Environ, Environ$ (functions)

Environ, Environ$ (functions)

Returns the value of the specified environment variable.

Syntax
Environ[$](variable$ | VariableNumber)

Description
Environ$ returns a String, whereas Environ returns a String variant.

If variable$ is specified, then this function looks for that variable in the
environment. If the variable name cannot be found, then a zero-length string is
returned.

If VariableNumber is specified, then this function looks for the Nth variable within
the environment (the first variable being number 1). If there is no such
environment variable, then a zero-length string is returned. Otherwise, the entire
entry from the environment is returned in the following format:
variable = value

Example
This example looks for the DOS Comspec variable and displays the value in a
dialog box.
Sub Main()
Dim a$(1)
a$(1) = Environ$("COMSPEC")
MsgBox "The DOS Comspec variable is set to: " & a$(1)
End Sub

Platform(s)
All.

See Also
Command, Command$ (functions)

Docbasic User’s Guide 3-191

EOF (function) A-Z Reference

EOF (function)

Returns True if the end-of-file has been reached for the given file; returns False
otherwise.

Syntax
EOF(filenumber)

Description
The filenumber parameter is an Integer used by Docbasic to refer to the open file—
the number passed to the Open statement.

With sequential files, EOF returns True when the end of the file has been reached
(i.e., the next file read command will result in a runtime error).

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

Example
This example opens the autoexec.bat file and reads lines from the file until the end-
of-file is reached.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
Dim s$
Open "c:\autoexec.bat" For Input As #1
Do While Not EOF(1)
Input #1,s$
Loop
Close
MsgBox "The last line was:" & crlf & s$
End Sub

Platform(s)
All.

See Also
Open (statement)
LOF (function)

3-192 Docbasic User’s Guide

A-Z Reference Eqv (operator)

Eqv (operator)

Performs a logical or binary equivalence on two expressions.

Syntax
expression1 Eqv expression2

Description
If both expressions are either Boolean, Boolean variants, or Null variants, then a
logical equivalence is performed as follows:

Table 3-32 Effect of Expression Type on Eqv Operator

If the first expression is and the second expression is Then the result is

True True True

True False False

False True False

False False True

If either expression is Null, then Null is returned.

Binary Equivalence

If the two expressions are Integer, then a binary equivalence is performed,

returning an Integer result. All other numeric types (including Empty variants) are
converted to Long and a binary equivalence is then performed, returning a Long
result.

Binary equivalence forms a new value based on a bit-by-bit comparison of the

binary representations of the two expressions, according to the following table:

1 Eqv 1 = 1

0 Eqv 1 = 0

1 Eqv 0 = 0

0 Eqv 0 = 1

Docbasic User’s Guide 3-193

Eqv (operator) A-Z Reference

Example
This example assigns False to A, performs some equivalent operations, and
displays a dialog box with the result. Since A is equivalent to False, and False is
equivalent to 0, and by definition, A = 0, then the dialog box will display "A is
False."
Sub Main()
a = False
If ((a Eqv False) And (False Eqv 0) And (a = 0)) Then
MsgBox "a is False."
Else
MsgBox "a is True."
End If
End Sub

Platform(s)
All.

See Also
Operator Precedence (topic)
Or (operator)
Xor (operator)
Imp (operator)
And (operator)

3-194 Docbasic User’s Guide

A-Z Reference Erase (statement)

Erase (statement)

Erases the elements of the specified arrays.

Syntax
Erase array1 [, array2]...

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

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

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

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

Table 3-33 How Data Type Affects the Erase Statement

Element type What Erase does to that element

Integer Sets the element to 0.

Boolean Sets the element to False.

Long Sets the element to 0.

Double Sets the element to 0.0.

Date Sets the element to December 30, 1899.

Single Sets the element to 0.0.

String (variable-length) Frees the string, then sets the element to a zero-length string.

String (fixed-length) Sets every character of each element to zero (Char$(0)).

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

Variant Sets the element to Empty.

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

Docbasic User’s Guide 3-195

Erase (statement) A-Z Reference

Example
This example puts a value into an array and displays it. Then it erases the value
and displays it again.
Sub Main()
Dim a$(10) 'Declare an array.
a$(1) = Dir$("*")'Fill element 1 with a filename.
MsgBox "Array before Erase: " & a$(1)'Display element 1.
Erase a$ 'Erase all elements in the array.
MsgBox "Array after Erase: " & a$(1)'Display element 1 again (should be
erased).
End Sub

Platform(s)
All.

See Also
Redim (statement)
Arrays (topic)

3-196 Docbasic User’s Guide

A-Z Reference Erl (function)

Erl (function)

Returns the line number of the most recent error.

Syntax
Erl[()]

Description
The first line of the procedure is 1, the second line is 2, and so on.

The internal value of Erl is reset to 0 with any of the following statements: Resume,
Exit Sub, Exit Function. Thus, if you want to use this value outside an error
handler, you must assign it to a variable.

Example
This example generates an error and then determines the line on which the error
occurred.
Sub Main()
Dim i As Integer
On Error Goto Trap1
i = 32767 'Generate an error--overflow.
i = i + 1
Exit Sub
Trap1:
MsgBox "Error on line: " & Erl
Exit Sub 'Reset the error handler.
End Sub

Platform(s)
All.

See Also
Err (function)
Error, Error$ (functions)
Error Handling (topic)

Docbasic User’s Guide 3-197

Err (function) A-Z Reference

Err (function)

Returns an Integer representing the error that caused the current error trap.

Syntax
Err[()]

Description
The Err function can only be used while within an error trap.

The internal value of Err is reset to 0 with any of the following statements: Resume,
Exit Sub, Exit Function. Thus, if you want to use this value outside an error
handler, you must assign it to a variable.

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

TestError:
If Err = 55 Then 'File already open.
MsgBox "Cannot copy an open file. Close it and try again."
Else
MsgBox "Error '" & Err & "' has occurred!"
Err = 999
End If
Resume Next
End Sub

Platform(s)
All.

See Also
Erl (function)
Error, Error$ (functions)
Error Handling (topic)

3-198 Docbasic User’s Guide

A-Z Reference Err (statement)

Err (statement)

Sets the value returned by the Err function to a specific Integer value.

Syntax
Err = value

Description
Only positive values less than or equal to 32767 can be used.

Setting value to -1 has the side effect of resetting the error state. This allows you to
perform error trapping within an error handler. The ability to reset the error
handler while within an error trap is not standard Basic. Normally, the error
handler is reset only with the Resume, Exit Sub, or Exit Function statement.

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

TestError:
If Err = 55 Then 'File already open.
MsgBox "Cannot copy an open file. Close it and try again."
Else
MsgBox "Error '" & Err & "' has occurred."
Err = 999
End If
Resume Next
End Sub

Platform(s)
All.

See Also
Error (statement)
Error Handling (topic)

Docbasic User’s Guide 3-199

Error (statement) A-Z Reference

Error (statement)

Simulates the occurrence of the given runtime error.

Syntax
Error errornumber

Description
The errornumber parameter is any Integer containing either a built-in error number
or a user-defined error number. The Err function can be used within the error trap
handler to determine the value of the error.

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

TestError:
If Err = 55 Then 'File already open.
MsgBox "Cannot copy an open file. Close it and try again."
Else
MsgBox "Error '" & Err & "' has occurred."
Err = 999
End If
Resume Next
End Sub

Platform(s)
All.

See Also
Err (statement)
Error Handling (topic)

3-200 Docbasic User’s Guide

A-Z Reference Error Handling (topic)

Error Handling (topic)

Error Handlers
Docbasic supports nested error handlers. When an error occurs within a
subroutine, Docbasic checks for an On Error handler within the currently
executing subroutine or function. An error handler is defined as follows:
Sub foo()
On Error Goto catch
'Do something here.
Exit Sub

catch:
'Handle error here.
End Sub

Error handlers have a life local to the procedure in which they are defined. The
error is reset when (1) another On Error statement is encountered, (2) an error
occurs, or (3) the procedure returns.

Cascading Errors
If a runtime error occurs and no On Error handler is defined within the currently
executing procedure, then Docbasic returns to the calling procedure and executes
the error handler there. This process repeats until a procedure is found that
contains an error handler or until there are no more procedures. If an error is not
trapped or if an error occurs within the error handler, then Docbasic displays an
error message, halting execution of the procedure.

Once an error handler has control, it must address the condition that caused the
error and resume execution with the Resume statement. This statement resets the
error handler, transferring execution to an appropriate place within the current
procedure. An error is displayed if a procedure exits without first executing
Resume or Exit.

Visual Basic Compatibility

Where possible, Docbasic has the same error numbers and error messages as
Visual Basic. This is useful for porting procedures between environments.

Handling errors in Docbasic involves querying the error number or error text
using the Error$ or Err function. Since this is the only way to handle errors in
Docbasic, compatibility with Visual Basic's error numbers and messages is
essential.

Docbasic errors fall into three categories:

Docbasic User’s Guide 3-201

Error Handling (topic) A-Z Reference

Visual Basic-compatible errors: These errors, numbered between 0 and 799,

are numbered and named according to the errors supported by Visual Basic.

Docbasic errors: These errors, numbered from 800 to 999, are unique to
Docbasic.

User-defined errors: These errors, equal to or greater than 1,000, are
available for use by extensions or by the procedure itself.

You can intercept trappable errors using Docbasic's On Error construct. Almost all
errors in Docbasic are trappable except for various system errors.

3-202 Docbasic User’s Guide

A-Z Reference Error, Error$ (functions)

Error, Error$ (functions)

Returns a String containing the text corresponding to the given error number or the
most recent error.

Syntax
Error[$][(errornumber)]

Description
Error$ returns a String, whereas Error returns a String variant.

The errornumber parameter is an Integer containing the number of the error

message to retrieve. If this parameter is omitted, then the function returns the text
corresponding to the most recent runtime error. If no runtime error has occurred,
then a zero-length string is returned.

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

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

TestError:
If Err = 55 Then 'File already open.
MsgBox "Cannot copy an open file. Close it and try again."
Else
MsgBox "Error '" & Err & "' has occurred."
Err = 999
End If
Resume Next
End Sub

Platform(s)
All.

Docbasic User’s Guide 3-203

Error, Error$ (functions) A-Z Reference

See Also
Erl (function)
Err (function)
Error Handling (topic)

3-204 Docbasic User’s Guide

A-Z Reference Exit Do (statement)

Exit Do (statement)

Causes execution to continue on the statement following the Loop clause.

Syntax
Exit Do

Description
This statement can only appear within a Do...Loop statement.

Example
This example will load an array with directory entries unless there are more than
ten entries--in which case, the Exit Do terminates the loop.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
Dim a$(5)
Do
i% = i% + 1
If i% = 1 Then
a(i%) = Dir$("*")
Else
a(i%) = Dir$
End If
If i% >= 10 Then Exit Do
Loop While (a(i%) <> "")

If i% = 10 Then
MsgBox i% & " entries processed!"
Else
MsgBox "Less than " & i% & " entries processed!"
End If
End Sub

Platform(s)
All.

See Also
Stop (statement)
Exit For (statement)
Exit Function (statement)

Docbasic User’s Guide 3-205

Exit Do (statement) A-Z Reference

Exit Sub (statement)

End (function)
Do...Loop (statement)

3-206 Docbasic User’s Guide

A-Z Reference Exit For (statement)

Exit For (statement)

Causes execution to exit the innermost For loop, continuing execution on the line
following the Next statement.

Syntax
Exit For

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

Example
This example will fill an array with directory entries until a null entry is
encountered or 100 entries have been processed--at which time, the loop is
terminated by an Exit For statement. The dialog box displays a count of files found
and then some entries from the array.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
Dim a$(100)
For i = 1 To 100
If i = 1 Then
a$(i) = Dir$("*")
Else
a$(i) = Dir$
End If
If (a$(i) = "") Or (i >= 100) Then Exit For
Next i
msg = "There are " & i & " files found." & crlf
MsgBox msg & a$(1) & crlf & a$(2) & crlf & a$(3) & crlf & a$(10)
End Sub

Platform(s)
All.

See Also
Stop (statement)
Exit Do (statement)
Exit Function (statement)
Exit Sub (statement)

Docbasic User’s Guide 3-207

Exit For (statement) A-Z Reference

End (statement)
For...Next (statement)

3-208 Docbasic User’s Guide

A-Z Reference Exit Function (statement)

Exit Function (statement)

Causes execution to exit the current function, continuing execution on the

statement following the call to this function.

Syntax
Exit Function

Description
This statement can only appear within a function.

Example
This function displays a message and then terminates with Exit Function.
Function Test_Exit() As Integer
MsgBox "Testing function exit, returning to Main()."
Test_Exit = 0
Exit Function
MsgBox "This line should never execute."
End Function

Sub Main()
a% = Test_Exit()
MsgBox "This is the last line of Main()."
End Sub

Platform(s)
All.

See Also
Stop (statement)
Exit For (statement)
Exit Do (statement)
Exit Sub (statement)
End (statement)
Function...End Function (statement)

Docbasic User’s Guide 3-209

Exit Sub (statement) A-Z Reference

Exit Sub (statement)

Causes execution to exit the current subroutine, continuing execution on the

statement following the call to this subroutine.

Syntax
Exit Sub

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

Example
This example displays a dialog box and then exits. The last line should never
execute because of the Exit Sub statement.
Sub Main()
MsgBox "Terminating Main()."
Exit Sub
MsgBox "Still here in Main()."
End Sub

Platform(s)
All.

See Also
Stop (statement)
Exit For (statement)
Exit Do (statement)
Exit Function (statement)
End (function)
Sub...End Sub (statement)

3-210 Docbasic User’s Guide

A-Z Reference Exp (function)

Exp (function)

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

Syntax
Exp(value)

Description
The value parameter is a Double within the following range:

0 <= value <= 709.782712893.

A runtime error is generated if value is out of the range specified above.

The value of e is 2.71828.

Example
This example assigns a to e raised to the 12.4 power and displays it in a dialog box.
Sub Main()
a# = Exp(12.40)
MsgBox "e to the 12.4 power is: " & a#
End Sub

Platform(s)
All.

See Also
Log (function)

Docbasic User’s Guide 3-211

Expression Evaluation (topic) A-Z Reference

Expression Evaluation (topic)

Docbasic allows expressions to involve data of different types. When this occurs,
the two arguments are converted to be of the same type by promoting the less
precise operand to the same type as the more precise operand. For example,
Docbasic will promote the value of i% to a Double in the following expression:
result# = i% * d#

In some cases, the data type to which each operand is promoted is different than
that of the most precise operand. This is dependent on the operator and the data
types of the two operands and is noted in the description of each operator.

If an operation is performed between a numeric expression and a String

expression, then the String expression is usually converted to be of the same type
as the numeric expression. For example, the following expression converts the
String expression to an Integer before performing the multiplication:
result = 10 * "2"'Result is equal to 20.

There are exceptions to this rule as noted in the description of the indicidual
operators.

Type Coercion
Docbasic performs numeric type conversion automatically. Automatic conversions
sometimes result in overflow errors, as shown in the following example:
d# = 45354
i% = d#

In this example, an overflow error is generated because the value contained in d#

is larger than the maximum size of an Integer.

Rounding
When floating-point values (Single or Double) are converted to integer values
(Integer or Long), the fractional part of the floating-point number is lost, rounding
to the nearest integer value. Docbasic uses Baker's rounding:

If the fractional part is larger than .5, the number is rounded up.

If the fractional part is smaller than .5, the number is rounded down.

If the fractional part is equal to .5, then the number is rounded up if it is odd
and down if it is even.

The following table shows sample values before and after rounding:

3-212 Docbasic User’s Guide

A-Z Reference Expression Evaluation (topic)

Table 3-34 Rounding Examples

Before rounding After rounding to whole number

2.1 2

4.6 5

2.5 2

3.5 4

Default Properties
When an OLE object variable or an Object variant is used with numerical operators
such as addition or subtraction, then the default property of that obect is
automatically retrieved. For example, consider the following:

Dim Excel As Object

Set Excel = GetObject(,"Excel.Application")
MsgBox "This application is " & Excel

The above example displays This application is Microsoft Excel in a dialog box.
When the variable Excel is used within the expression, the default property is
automatically retrieved, which, in this case, is the string Microsoft Excel.
Considering that the default property of the Excel object is .Value, then the
following two statements are equivalent:

MsgBox "This application is " & Excel

MsgBox "This application is " & Excel.Value

Docbasic User’s Guide 3-213

External (function) A-Z Reference

External (function)

Loads a dm_procedure object into memory, making it available to be called by the

current procedure.

Syntax
External(object$)

Description
Before one procedure can call another procedure stored in a different
dm_procedure object, you must load the dm_procedure object into memory. The
External function does this for you. After loading a dm_procedure object, you can
call any of its procedures.

The object$ argument can be the object ID or the full path and object name of the
dm_procedure object to load.

To specify the object name, use the following format:

/cabinet{/folder}/object_name

External returns a boolean True if successful; otherwise External returns False.

Example
This example loads a dm_procedure object called "My Procedure" stored in the
System cabinet.
Sub Main()
ret% = External("/System/My Procedure")
End Sub

This example identifies the procedure by object ID instead of object name.

Sub Main()
ret% = External("0900000987893e31")
End Sub

Platform(s)
All.

3-214 Docbasic User’s Guide

A-Z Reference False (Constant)

False (Constant)

Boolean constant whose value is False.

Description
Used in conditionals and Boolean expressions.

Example
This example assigns False to A, performs some equivalent operations, and
displays a dialog box with the result. Since A is equivalent to False, and False is
equivalent to 0, and by definition, A = 0, then the dialog box will display "A is
False."
Sub Main()
a = False
If ((a = False) And (False Eqv 0) And (a = 0)) Then
MsgBox "a is False."
Else
MsgBox "a is True."
End If
End Sub

Platform(s)
All.

See Also
True (constant)
Constants (topic)
Boolean (data type)

Docbasic User’s Guide 3-215

FileAttr (function) A-Z Reference

FileAttr (function)

Returns an Integer specifying the file mode (if attribute is 1) or the operating system
file handle (if attribute is 2).

Syntax
FileAttr(filenumber, attribute)

Description
The FileAttr function takes the following parameters:

filenumber Integer value used by Docbasic to refer to the open file—

the number passed to the Open statement.

attribute Integer specifying the type of value to be returned. If

attribute is 1, then one of the following values is returned:
1 Input
2 Output
4 Random
8 Append
32 Binary
If attribute is 2, then the operating system file handle is
returned. On most systems, this is a special Integer value
identifying the file.

Example
This example opens a file for input, reads the file attributes, and determines the file
mode for which it was opened. The result is displayed in a dialog box.
Sub Main()
Open "c:\autoexec.bat" For Input As #1
a% = FileAttr(1,1)
Select Case a%
Case 1
MsgBox "Opened for input."
Case 2
MsgBox "Opened for output."
Case 4
MsgBox "Opened for random."
Case 8
MsgBox "Opened for append."
Case 32
MsgBox "Opened for binary."

3-216 Docbasic User’s Guide

A-Z Reference FileAttr (function)

Case Else
MsgBox "Unknown file mode."
End Select
a% = FileAttr(1,2)
MsgBox "File handle is: " & a%
Close
End Sub

Platform(s)
All.

See Also
FileLen (function)
FileType (function)
FileExists (function)
Open (statement)
SetAttr (statement)

Docbasic User’s Guide 3-217

FileCopy (statement) A-Z Reference

FileCopy (statement)

Copies a source$ file to a destination$ file.

Syntax
FileCopy source$, destination$

Description
The FileCopy function takes the following parameters:

source$ String containing the name of a single file to copy.

The source$ parameter cannot contain wildcards (? or *) but

may contain path information.

destination$ String containing a single, unique destination file, which

may contain a drive and path specification.

The file will be copied and renamed if the source$ and destination$ filenames are not
the same.

Some platforms do not support drive letters and may not support dots to indicate
current and parent directories.

Example
This example copies the autoexec.bat file to "autoexec.sav", then opens the copied
file and tries to copy it again--which generates an error.
Sub Main()
On Error Goto ErrHandler
FileCopy "c:\autoexec.bat", "c:\autoexec.sav"
Open "c:\autoexec.sav" For Input As # 1
FileCopy "c:\autoexec.sav", "c:\autoexec.sv2"
Close
Exit Sub

ErrHandler:
If Err = 55 Then 'File already open.
MsgBox "Cannot copy an open file. Close it and try again."
Else
MsgBox "An unspecified file copy error has occurred."
End If
Resume Next
End Sub

3-218 Docbasic User’s Guide

A-Z Reference FileCopy (statement)

Platform(s)
All.

See Also
Kill (statement)
Name (statement)

Docbasic User’s Guide 3-219

FileDateTime (function) A-Z Reference

FileDateTime (function)

Returns a Date variant representing the date and time of the last modification of a
file.

Syntax
FileDateTime(filename$)

Description
This function retrieves the date and time of the last modification of the file
specified by filename$ (wildcards are not allowed). A runtime error results if the file
does not exist. The value returned can be used with the date/time functions (i.e.,
Year, Month, Day, Weekday, Minute, Second, Hour) to extract the individual
elements.

Example
This example gets the file date/time of the autoexec.bat file and displays it in a
dialog box.
Sub Main()
If FileExists("c:\autoexec.bat") Then
a# = FileDateTime("c:\autoexec.bat")
MsgBox "The date/time information for the file is: " & Year(a#) & "-
" & Month(a#) & "-" & Day(a#)
Else
MsgBox "The file does not exist."
End If
End Sub

Platform(s)
All.

Platform Notes:
Some operating systems (such as Win32) store the file creation date, last
modification date, and the date the file was last written to. The FileDateTeime
function only returns the last modification date.

3-220 Docbasic User’s Guide

A-Z Reference FileDateTime (function)

See Also
FileLen (function)
FileType (function)
FileAttr (function)
FileExists (function)

Docbasic User’s Guide 3-221

FileDirs (statement) A-Z Reference

FileDirs (statement)

Fills a String or Variant array with directory names from disk.

Syntax
FileDirs array() [,dirspec$]

Description
The FileDirs statement takes the following parameters:

array() Either a zero- or a one-dimensioned array of strings or

variants. The array can be either dynamic or fixed.

If array() is dynamic, then it will be redimensioned to

exactly hold the new number of elements. If there are no
elements, then the array will be redimensioned to contain
no dimensions. You can use the LBound, UBound, and
ArrayDims functions to determine the number and size of
the new array's dimensions.

If the array is fixed, each array element is first erased, then

the new elements are placed into the array. If there are
fewer elements than will fit in the array, then the
remaining elements are initialized to zero-length strings
(for String arrays) or Empty (for Variant arrays). A runtime
error results if the array is too small to hold the new
elements.

dirspec$ String containing the file search mask, such as:

t*.
c:\*.*

If this parameter is omitted, then * is used, which fills the

array with all the subdirectory names within the current
directory.

Example
This example fills an array with directory entries and displays the first one.
Sub Main()
Dim a$()
FileDirs a$,"c:\*.*"

3-222 Docbasic User’s Guide

A-Z Reference FileDirs (statement)

MsgBox "The first directory is: " & a$(0)

End Sub

Platform(s)
All.

See Also
FileList (statement)
Dir, Dir$ (functions)
CurDir, CurDir$ (functions)
ChDir (statement)

Docbasic User’s Guide 3-223

FileExists (function) A-Z Reference

FileExists (function)

Returns True if filename$ exists; returns False otherwise.

Syntax
FileExists(filename$)

Description
This function determines whether a given filename$ is valid.

This function will return False if filename$ specifies a subdirectory.

Example
This example checks to see whether there is an autoexec.bat file in the root
directory of the C drive, then displays either its date and time of creation or the fact
that it does not exist.
Sub Main()
If FileExists("c:\autoexec.bat") Then
Msgbox "This file exists!"
Else
MsgBox "File does not exist."
End If
End Sub

Platform(s)
All.

See Also
FileLen (function)
FileType (function)
FileAttr (function)
FileParse$ (function)

3-224 Docbasic User’s Guide

A-Z Reference FileLen (function)

FileLen (function)

Returns a Long representing the length of filename$ in bytes.

Syntax
FileLen(filename$)

Description
This function is used in place of the LOF function to retrieve the length of a file
without first opening the file. A runtime error results if the file does not exist.

Example
This example checks to see whether there is a c:\autoexec.bat file and, if there is,
displays the length of the file.
Sub Main()
If (FileExists("c:\autoexec.bat") And (FileLen("c:\autoexec.bat") <> 0))
Then
b% = FileLen("c:\autoexec.bat")
MsgBox "The length of autoexec.bat is: " & b%
Else
MsgBox "File does not exist."
End If
End Sub

Platform(s)
All.

See Also
FileType (function)
FileAttr (function)
FileParse$ (function)
FileExists (function)
Loc (function)

Docbasic User’s Guide 3-225

FileList (statement) A-Z Reference

FileList (statement)

Fills a String or Variant array with filenames from disk.

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

Description
The FileList function takes the following parameters:

array() Either a zero- or a one-dimensioned array of strings or

variants. The array can be either dynamic or fixed.

If array() is dynamic, then it will be redimensioned to

exactly hold the new number of elements. If there are no
elements, then the array will be redimensioned to contain
no dimensions. You can use the LBound, UBound, and
ArrayDims functions to determine the number and size of
the new array's dimensions.

If the array is fixed, each array element is first erased, then

the new elements are placed into the array. If there are
fewer elements than will fit in the array, then the
remaining elements are initialized to zero-length strings
(for String arrays) or Empty (for Variant arrays). A runtime
error results if the array is too small to hold the new
elements.

filespec$ String specifying which filenames are to be included in the

list.

The filespec$ parameter can include wildcards, such as *

and ?. If this parameter is omitted, then * is used.

include_attr Integer specifying attributes of files you want included in

the list. It can be any combination of the attributes listed
below.

If this parameter is omitted, then the value 97 is used

(ebReadOnly Or ebArchive Or ebNone).

exclude_attr Integer specifying attributes of files you want excluded

from the list. It can be any combination of the attributes
listed below.

3-226 Docbasic User’s Guide

A-Z Reference FileList (statement)

If this parameter is omitted, then the value 18 is used

(ebHidden Or ebDirectory). In other words, hidden files
and subdirectories are excluded from the list.

Wildcards

The * character matches any sequence of zero or more characters, whereas the ?
character matches any single character. Multiple *'s and ?'s can appear within the
expression to form complete searching patterns. The following table shows some
examples:

Table 3-35 Examples Using * and ? Wildcards

This pattern Matches these files Doesn’t match these files

*S.*TXT SAMPLE. TXT SAMPLE

GOOSE.TXT SAMPLE.DAT
SAMS.TXT

C*T.TXT CAT.TXT CAP.TXT

ACATS.TXT

C*T CAT CAT.DOC

CAP.TXT

C?T CAT CAT.TXT

CUT CAPIT
CT

* (All files)

File Attributes

These numbers can be any combination of the following:

Table 3-36 Constants for Use with Include_attr and Exclude_attr Parameters

Constant Value Includes

ebNormal 0 Read-only, archive, subdir, none

ebReadOnly 1 Read-only files

ebHidden 2 Hidden files

ebSystem 4 System files

ebVolume 8 Volume label

ebArchive 32 Files that have changed since the last backup

ebNone 64 Files with no attributes

Docbasic User’s Guide 3-227

FileList (statement) A-Z Reference

Example
This example fills an array a with the directory of the current drive for all files that
have normal or no attributes and excludes those with system attributes. The dialog
box displays four filenames from the array.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
Dim a$()
FileList a$,"*.*", (ebNormal + ebNone), ebSystem
If ArrayDims(a$) > 0 Then
MsgBox a$(1) & crlf & a$(2) & crlf & a$(3) & crlf & a$(4)
Else
MsgBox "No files found."
End If
End Sub

Platform(s)
All.

Platform Notes: UNIX

On UNIX platforms, the hidden file attribute corresponds to files without the read
or write attributes.

See Also
FileDirs (statement)
Dir, Dir$ (functions)

3-228 Docbasic User’s Guide

A-Z Reference FileParse$ (function)

FileParse$ (function)

Returns a String containing a portion of filename$ such as the path, drive, or file
extension.

Syntax
FileParse$(filename$[, operation])

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

..\test.dat
c:\sheets\test.dat
test.dat

A runtime error is generated if filename$ is a zero-length string.

The optional operation parameter is an Integer specifying which portion of the

filename$ to extract. It can be any of the following values.

Table 3-37 Values for Operation Parameter

Value Meaning Example

0 Full name c:\sheets\test.dat

1 Drive c

2 Path c:\sheets

3 Name test.dat

4 Root test

5 Extension dat

If operation is not specified, then the full name is returned. A runtime error will
result if operation is not one of the above values.

Example
This example parses the file string "c:\testsub\autoexec.bat" into its component
parts and displays them in a dialog box.
Const crlf = Chr$(13) + Chr$(10)

Docbasic User’s Guide 3-229

FileParse$ (function) A-Z Reference

Sub Main()
Dim a$(6)
For i = 1 To 5
a$(i) = FileParse$("c:\testsub\autoexec.bat",i - 1)
Next i
MsgBox a$(1) & crlf & a$(2) & crlf & a$(3) & crlf & a$(4) & crlf & a$(5)
End Sub

Platform(s)
All.

Platform Notes:
On systems that do not support drive letters, operation 1 will return a zero-length
string.

The path separator is different on different platforms. Under Windows and Win32,
the backslash and forward slash can be used interchangeably. For example,
"c:\test.dat" is the same as "c:/test.dat".

Platform Notes: UNIX

Under UNIX systems, the backslash and colon are valid filename characters.

Platform Notes: Macintosh

On the Macintosh, all characters are valid within filenames except colons, which
are seen as path separators.

See Also
FileLen (function)
FileType (function)
FileAttr (function)
FileExists (function)

3-230 Docbasic User’s Guide

A-Z Reference FileType (function)

FileType (function)

Returns the type of the specified file.

Syntax
FileType(filename$)

Description
One of the following Integer constants is returned:

Table 3-38 Return Value of FileType Function

Constant Value Description

ebDOS 1 A DOS executable file (exe files only; com files are not
recognized)

ebWindows 2 Windows executable file

If one of the above values is not returned, then the file type is unknown.

Example
This example looks at c:\windows\winfile.exe and determines whether it is a DOS
or a Windows file. The result is displayed in a dialog box.
Sub Main()
a = FileType("c:\windows\winfile.exe")
If a = ebDos Then
MsgBox "This is a DOS file."
Else
MsgBox "This is a Windows file of type '" & a & "'"
End If
End Sub

Platform(s)
Windows.

Platform Notes: Windows

Currently, only files with a ".exe" extension can be used with this function. Files
with a ".com" or ".bat" extension will return 3 (unknown).

Docbasic User’s Guide 3-231

FileType (function) A-Z Reference

See Also
FileLen (function)
FileAttr (function)
FileExists (function)

3-232 Docbasic User’s Guide

A-Z Reference Fix (function)

Fix (function)

Returns the integer part of number.

Syntax
Fix(number)

Description
This function returns the integer part of the given value by removing the fractional
part. The sign is preserved.

The Fix function returns the same type as number, with the following exceptions:

If number is Empty, then an Integer variant of value 0 is returned.

If number is a String, then a Double variant is returned.

If number contains no valid data, then a Null variant is returned.

Example
This example returns the fixed part of a number and assigns it to b, then displays
the result in a dialog box.
Sub Main()
a# = -19923.45
b% = Fix(a#)
MsgBox "The fixed portion of -19923.45 is: " & b%
End Sub

Platform(s)
All.

See Also
Int (function)
CInt (function)

Docbasic User’s Guide 3-233

For...Next (statement) A-Z Reference

For...Next (statement)

Repeats a block of statements a specified number of times, incrementing a loop

counter by a given increment each time through the loop.

Syntax
For counter = start To end [Step increment]
[statements]
[Exit For]
[statements]
Next [counter [,nextcounter]... ]

Description
The For statement takes the following parameters:

counter Name of a numeric variable. Variables of the following

types can be used: Integer, Long, Single, Double, Variant.

start Initial value for counter. The first time through the loop,
counter is assigned this value.

end Final value for counter. The statements will continue

executing until counter is equal to end.

increment Amount added to counter each time through the loop. If end
is greater than start, then increment must be positive. If end
is less than start, then increment must be negative.

If increment is not specified, then 1 is assumed. The

expression given as increment is evaluated only once.
Changing the increment during execution of the loop will
have no effect.

statements Any number of Docbasic statements.

The For...Next statement continues executing until an Exit For statement is

encountered when counter is greater than end.

For...Next statements can be nested. In such a case, the Next [counter] statement
applies to the innermost For...Next.

The Next clause can be optimized for nested next loops by separating each counter
with a comma. The ordering of the counters must be consistent with the nesting
order (innermost counter appearing before outermost counter). The following
example shows two equivalent For statements:

3-234 Docbasic User’s Guide

A-Z Reference For...Next (statement)

For i = 1 To 10 For i = 1 To 10
For j = 1 To 10 For j = 1 To 10
Next j Next j,i
Next i

A Next clause appearing by itself (with no counter variable) matches the innermost
For loop.

The counter variable can be changed within the loop but will have no effect on the number
of times the loop will execute.

Example
Sub Main()
'This example constructs a truth table for the OR statement 'using
nested For...Next loops.
For x = -1 To 0
For y = -1 To 0
Z = x Or y
msg = msg & Format(Abs(x%),"0") & " Or "
msg = msg & Format(Abs(y%),"0") & " = "
msg = msg & Format(Z,"True/False") & Basic.Eoln$
Next y
Next x
MsgBox msg
End Sub

Platform(s)
All.

Platform Notes: Windows, Win32

Due to errors in program logic, you can inadvertently create infinite loops in your
code. Under Windows and Win32, you can break out of infinite loops using
Ctrl+Break.

Platform Notes: UNIX

Due to errors in program logic, you can inadvertently create infinite loops in your
code. Under UNIX, you can break out of infinite loops using Ctrl+C.

Platform Notes: Macintosh

Due to errors in program logic, you can inadvertently create infinite loops in your
code. On the Macintosh, you can break out of infinite loops using
Command+Period.

Docbasic User’s Guide 3-235

For...Next (statement) A-Z Reference

See Also
Do...Loop (statement)
While...WEnd (statement)

3-236 Docbasic User’s Guide

A-Z Reference Format, Format$ (functions)

Format, Format$ (functions)

Returns a String formatted to user specification.

Syntax
Format[$](expression [,Userformat$])

Description
Format$ returns a String, whereas Format returns a String variant.

The Format$/Format functions take the following parameters:

expression String or numeric expression to be formatted.

Userformat$ Format expression that can be either one of the built-in

Docbasic formats or a user-defined format consisting of
characters that specify how the expression should be
displayed.

String, numeric, and date/time formats cannot be mixed in

a single Userformat$ expression.

If Userformat$ is omitted and the expression is numeric, then these functions

perform the same function as the Str$ or Str statements, except that they do not
preserve a leading space for positive values.

If expression is Null, then a zero-length string is returned.

Built-In Formats

To format numeric expressions, you can specify one of the built-in formats. There
are two categories of built-in formats: one deals with numeric expressions and the
other with date/time values.The following tables list the built-in numeric and
date/time format strings, followed by an explanation of what each does.

Table 3-39 Built-In Numeric Formats

Format Description

General Number Displays the numeric expression as is, with no additonal

formatting.

Currency Displays the numeric expression as currency, with

thousands separator if necessary.

Docbasic User’s Guide 3-237

Format, Format$ (functions) A-Z Reference

Table 3-39 Built-In Numeric Formats

Format Description

Fixed Displays at least one digit to the left of the decimal

separator and two digits to the right.

Standard Displays the numeric expression with thousands separator

if necessary. Displays at least one digit to the left of the
decimal separator and two digits to the right.

Percent Displays the numeric expression multiplied by 100. A

percent sign (%) will appear at the right of the formatted
output. Two digits are displayed to the right of the
decimal separator.

Scientific Displays the number using scientific notation. One digit

appears before the decimal separator and two after.

Yes/No Displays No if the numeric expression is 0. Displays Yes

for all other values.

True/False Displays False if the numeric expression is 0. Displays

True for all other values.

On/Off Displays Off if the numeric expression is 0. Displays On

for all other values.

Table 3-40 Built-In Date/Time Formats

Format Description

General date Displays the date and time. If there is no fractional part in
the numeric expression, then only the date is displayed. If
there is no integral part in the numeric expression, then
only the time is displayed. Output is in the following
form: 1/1/95 01:00:00 AM.

Medium date Displays a medium date. N prints out only the

abbreviated name of the month.

Short date Displays a short date.

Lone time Displays the long time. The default is: h:mm:ss.

Medium time Displays the time using a 12-hour clock. Hours and
minutes are displayed, and the AM/PM designator is at
the end.

Short time Displays the time using a 24-hour clock. Hours and
minutes are displayed.

User-Defined Formats

In addition to the built-in formats, you can specify a user-defined format by using
characters that have special meaning when used in a format expression. The

3-238 Docbasic User’s Guide

A-Z Reference Format, Format$ (functions)

following tables list the characters you can use for numeric, string, and date/time
formats and explain their functions.

Table 3-41 User-Defined Numeric Formats

Character Meaning

Empty string Displays the numeric expression as is, with no additional formatting.

0 This is a digit placeholder.

Displays a number or a 0. If a number exists in the numeric expression in

the position where the 0 appears, the number will be displayed.
Otherwise, a 0 will be displayed. If there are more 0s in the format string
than there are digits, the leading and trailing 0s are displayed without
modification.

# This is a digit placeholder.

Displays a number or nothing. If a number exists in the numeric

expression in the position where the number sign appears, the number
will be displayed. Otherwise, nothing will be displayed. Leading and
trailing 0s are not displayed.

. This is the decimal placeholder.

Designates the number of digits to the left of the decimal and the number
of digits to the right. The character used in the formatted string depends
on the decimal placeholder, as specified by your locale.

% This is the percentage operator.

The numeric expression is multiplied by 100, and the percent character is

inserted in the same position as it appears in the user-defined format
string.

, This is the thousand separator.

The common use for the thousands separator is to separate thousands

from hundreds. To specify this use, the thousands separator must be
surrounded by digit placeholders. Commas appearing before any digit
placeholders are specified are just displayed. Adjacent commas with no
digit placeholders specified between them and the decimal mean that the
number should be divided by 1,000 for each adjacent comma in the format
string. A comma immediately to the left of the decimal has the same
function. The actual thousands separator character used depends on the
character specified by your locale.

E-E+e-e+ These are the scientific notation operators, which display the number in
scientific notation. At least one digit placeholder must exist to the left of E-
, E+, e-, or e+. Any digit placeholders displayed to the left of E-, E+, e-, or
e+ determine the number of digits displayed in the exponent. Using E+ or
e+ places a + in front of positive exponents and a - in front of negative
exponents. Using E- or e- places a - in front of negative exponents and
nothing in front of positive exponents.

: This is the time separator.

Docbasic User’s Guide 3-239

Format, Format$ (functions) A-Z Reference

Table 3-41 User-Defined Numeric Formats

Character Meaning

Separates hours, minutes, and seconds when time values are being
formatted. The actual character used depends on the character specified
by your locale.

/ This is the date separator.

Separates months, days, and years when date values are being formatted.
The actual character used depends on the character specified by your
locale.

-+$()space These are the literal characters you can display.

To display any other character, you should precede it with a backslash or

enclose it in quotes.

\ This designates the next character as a displayed character.

To display characters, precede them with a backslash. To display a

backslash, use two backslashes. Double quotation marks can also be used
to display characters. Numeric formatting characters, date/time
formatting characters, and string formatting characters cannot be
displayed without a preceding backslash.

"ABC" Displays the text between the quotation marks, but not the quotation
marks. To designate a double quotation mark within a format string, use
two adjacent double quotation marks.

* This will display the next character as the fill character.

Any empty space in a field will be filled with the specified fill character.

Numeric formats can contain one to three parts. Each part is separated by a
semicolon. If you specify one format, it applies to all values. If you specify two
formats, the first applies to positive values and the second to negative values. If
you specify three formats, the first applies to positive values, the second to
negative values, and the third to 0s. If you include semicolons with no format
between them, the format for positive values is used.

Table 3-42 User-Defined String Formats

Character Meaning

@ This is a character placeholder.

Displays a character if one exists in the expression in the same position;

otherwise, displays a space. Placeholders are filled from right to left unless
the format string specifies left to right.

& This is a character placeholder.

Displays a character if one exists in the expression in the same position;

otherwise, displays nothing. Placeholders are filled from right to left
unless the format string specifies left to right.

3-240 Docbasic User’s Guide

A-Z Reference Format, Format$ (functions)

Table 3-42 User-Defined String Formats

Character Meaning

< This character forces lowercase.

Displays all characters in the expression in lowercase.

> This character forces uppercase.

Displays all characters in the expression in uppercase.

! This character forces placeholders to be filled from left to right. The

default is right to left.

Table 3-43 User-Defined Date/Time Formats

Character Meaning

c Displays the date as ddddd and the time as ttttt. Only the date is
displayed if no fractional part exists in the numeric expression. Only the
time is displayed if no integral portion exists in the numeric expression.

d Displays the day without a leading 0 (1-31).

dd Displays the day with a leading 0 (01-31).

ddd Displays the day of the week abbreviated (Sun-Sat).

dddd Displays the day of the week (Sunday-Saturday).

ddddd Displays the date as a short date.

dddddd Displays the date as a long date.

w Displays the number of the day of the week (1-7). Sunday is 1; Saturday is
7.

ww Displays the week of the year (1-53).

m Displays the month without a leading 0 (1-12). If m immediately follows h

or hh, m is treated as minutes (0-59).

mm Displays the month with a leading 0 (01-12). If mm immediately follows h

or hh, mm is treated as minutes with a leading 0 (00-59).

mmm Displays the month abbreviated (Jan-Dec).

mmmm Displays the month (January-December).

q Displays the quarter of the year (1-4).

yy Displays the year, not the century (00-99).

yyyy Displays the year (1000-9999).

h Displays the hour without a leading 0 (0-24).

Docbasic User’s Guide 3-241

Format, Format$ (functions) A-Z Reference

Table 3-43 User-Defined Date/Time Formats

Character Meaning

hh Displays the hour with a leading 0 (00-24).

n Displays the minute without a leading 0 (0-59).

nn Displays the minute with a leading 0 (00-59).

s Displays the second without a leading 0 (0-59).

ss Displays the second with a leading 0 (00-59).

ttttt Displays the time. A leading 0 is displayed if specified by your locale.

AM/PM Displays the time using a 12-hour clock. Displays an uppercase AM for
time values before 12 noon. Displays an uppercase PM for time values
after 12 noon and before 12 midnight.

am/pm Displays the time using a 12-hour clock. Displays a lowercase am or pm at

the end.

A/P Displays the time using a 12-hour clock. Displays an uppercase A or P at

the end.

a/p Displays the time using a 12-hour clock. Displays a lowercase a or p at the
end.

AMPM Displays the time using a 12-hour clock. Displays the string s1159 for
values before 12 noon and s2359 for values after 12 noon and before 12
midnight.

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

Sub Main()
a# = 1199.234
msg = "Some general formats for '" & a# & "' are:"
msg = msg & Format$(a#,"General Number") & crlf
msg = msg & Format$(a#,"Currency") & crlf
msg = msg & Format$(a#,"Standard") & crlf
msg = msg & Format$(a#,"Fixed") & crlf
msg = msg & Format$(a#,"Percent") & crlf
msg = msg & Format$(a#,"Scientific") & crlf
msg = msg & Format$(True,"Yes/No") & crlf
msg = msg & Format$(True,"True/False") & crlf
msg = msg & Format$(True,"On/Off") & crlf
msg = msg & Format$(a#,"0,0.00") & crlf
msg = msg & Format$(a#,"##,###,###.###") & crlf
MsgBox msg

da$ = Date$
msg = "Some date formats for '" & da$ & "' are:"
msg = msg & Format$(da$,"General Date") & crlf
msg = msg & Format$(da$,"Long Date") & crlf

3-242 Docbasic User’s Guide

A-Z Reference Format, Format$ (functions)

msg = msg & Format$(da$,"Medium Date") & crlf

msg = msg & Format$(da$,"Short Date") & crlf
MsgBox msg

ti$ = Time$
msg = "Some time formats for '" & ti$ & "' are:"
msg = msg & Format$(ti$,"Long Time") & crlf
msg = msg & Format$(ti$,"Medium Time") & crlf
msg = msg & Format$(ti$,"Short Time") & crlf
MsgBox msg
End Sub

Platform(s)
All.

Platform Notes: Windows, Win32

Under Windows and Win32, default date/time formats are read from the [Intl]
section of the win.ini file.

See Also
Str, Str$ (functions)
CStr (function)

Docbasic User’s Guide 3-243

FreeFile (function) A-Z Reference

FreeFile (function)

Returns an Integer containing the next available file number.

Syntax
FreeFile[()]

Description
The number returned is suitable for use in the Open statement and will always be
between 1 and 255 inclusive.

Example
This example assigns A to the next free file number and displays it in a dialog box.
Sub Main()
a = FreeFile
MsgBox "The next free file number is: " & a
End Sub

Platform(s)
All.

See Also
FileAttr (function)
Open (statement)

3-244 Docbasic User’s Guide

A-Z Reference Function...End Function (statement)

Function...End Function (statement)

Creates a user-defined function.

Syntax
[Private | Public] [Static] Function name[(arglist)] [As ReturnType]
[statements]
End Sub

where arglist is a comma-separated list of the following (up to 30 arguments are

allowed):
[Optional] [ByVal | ByRef] parameter [()] [As type]

Description
The Function statement has the following parts:

Part Description

Private Indicates that the function being defined cannot be called

from other procedures.

Public Indicates that the function being defined can be called from
other procedures. If both the Private and Public keywords
are missing, then Public is assumed.

Static Recognized by the compiler but currently has no effect.

name Name of the function, which must follow Docbasic naming

conventions:

1. Must start with a letter.

2. May contain letters, digits, and the underscore character

(_). Punctuation and type-declaration characters are not
allowed. The exclamation point (!) can appear within the
name as long as it is not the last character, in which case it
is interpreted as a type-declaration character.

3. Must not exceed 80 characters in length.

Additionally, the name parameter can end with an optional

type-declaration character specifying the type of data
returned by the function (i.e., any of the following
characters: %, &, !, #, @).

Docbasic User’s Guide 3-245

Function...End Function (statement) A-Z Reference

Optional Keyword indicating that the parameter is optional. All

optional parameters must be of type Variant. Furthermore,
all parameters that follow the first optional parameter must
also be optional.

If this keyword is omitted, then the parameter is required.

Note: You can use the IsMissing function to determine if an

optional parameter was actually passed by the caller.

ByVal Keyword indicating that parameter is passed by value.

ByRef Keyword indicating that parameter is passed by reference.

If neither the ByVal nor the ByRef keyword is given, then
ByRef is assumed.

parameter Name of the parameter, which must follow the same

naming conventions as those used by variables. This name
can include a type-declaration character, appearing in place
of As type.

type Type of the parameter (i.e., Integer, String, and so on).

Arrays are indicated with parentheses. For example, an
array of integers would be declared as follows:

Function Test(a() As Integer)

End Function

ReturnType Type of data returned by the function. If the return type is

not given, then Variant is assumed. The ReturnType can
only be specified if the function name (i.e., the name
parameter) does not contain an explicit type-declaration
character.

A function returns to the caller when either of the following statements is

encountered:
End Function
Exit Function

Functions can be recursive.

Returning Values from Functions

To assign a return value, an expression must be assigned to the name of the

function, as shown below:
Function TimesTwo(a As Integer) As Integer
TimesTwo = a * 2
End Function

3-246 Docbasic User’s Guide

A-Z Reference Function...End Function (statement)

If no assignment is encountered before the function exits, then one of the following
values is returned:

Table 3-44 Default Return Values of Functions

Value Data Type Returned by the Function

0 Integer, Long, Single, Double, Currency

Zero-length string String

Nothing Object (or any data object)

Error Variant

December 30, 1899 Date

False Boolean

The type of the return value is determined by the As ReturnType clause on the
Function statement itself. As an alternative, a type-declaration character can be
added to the Function name. For example, the following two definitions of Test
both return String values:
Function Test() As String
Test = "Hello, world"
End Function

Function Test$()
Test = "Hello, world"
End Function

Passing Parameters to Functions

Parameters are passed to a function either by value or by reference, depending on

the declaration of that parameter in arglist. If the parameter is declared using the
ByRef keyword, then any modifications to that passed parameter within the
function change the value of that variable in the caller. If the parameter is declared
using the ByVal keyword, then the value of that variable cannot be changed in the
called function. If neither the ByRef or ByVal keywords are specified, then the
parameter is passed by reference.

You can override passing a parameter by reference by enclosing that parameter

within parentheses. For instance, the following example passes the variable j by
reference, regardless of how the third parameter is declared in the arglist of
UserFunction:

i = UserFunction(10,12,(j))

Optional Parameters

Docbasic allows you to skip parameters when calling functions, as shown in the
following example:

Docbasic User’s Guide 3-247

Function...End Function (statement) A-Z Reference

Function Test(a%,b%,c%) As Variant

End Function

Sub Main
a = Test(1,,4)'Parameter 2 was skipped.
End Sub

You can skip any parameter with the following restrictions:

The call cannot end with a comma. For instance, using the above example,
the following is not valid:
a = Test(1,,)

The call must contain the minimum number of parameters as requred by the
called function. For instance, using the above example, the following are
invalid:
a = Test(,1)'Only passes two out of three required parameters.
a = Test(1,2)'Only passes two out of three required parameters.

When you skip a parameter in this manner, Docbasic creates a temporary variable
and passes this variable instead. The value of this temporary variable depends on
the data type of the corresponding parameter in the argument list of the called
function, as described in the following table:

Table 3-45 Default Values of Skipped Function Parameters

Value Data Type

0 Integer, Long, Single, Double, Currency

Zero-length string String

Nothing Object (or any data object)

Error Variant

December 30, 1899 Date

False Boolean

Within the called function, you will be unable to determine if a parameter was
skipped unless the parameter was declared as a variant in the argument list of the
function. In this case, you can use the IsMissing function to determine if the
parameter was skipped:
Function Test(a,b,c)
If IsMissing(a) Or IsMissing(b) Then Exit Sub
End Function

Example
Function Factorial(n%) As Integer
'This function calculates N! (N-factoral).

3-248 Docbasic User’s Guide

A-Z Reference Function...End Function (statement)

f% = 1
For i = n To 2 Step -1
f = f * i
Next i
Factorial = f
End Function

Sub Main()
'This example calls user-defined function Factoral and displays the
'result in a dialog box.
a% = 0
Do While a% < 2
a% = Val(InputBox$("Enter an integer number greater than 2.","Compute
Factorial"))
Loop
b# = Factorial(a%)
MsgBox "The factoral of " & a% & " is: " & b#
End Sub

Platform(s)
All.

See Also
Sub...End Sub (statement)

Docbasic User’s Guide 3-249

Fv (function) A-Z Reference

Fv (function)

Calculates the future value of an annuity based on periodic fixed payments and a
constant rate of interest.

Syntax
Fv(Rate, Nper, Pmt,Pv,Due)

Description
An annuity is a series of fixed payments made to an insurance company or other
investment company over a period of time. Examples of annuities are mortgages
and monthly savings plans.

The Fv function requires the following parameters:

Rate Double representing the interest rate per period. Make sure
that annual rates are normalized for monthly periods
(divided by 12).

NPer Double representing the total number of payments

(periods) in the annuity.

Pmt Double representing the amount of each payment per

period. Payments are entered as negative values, whereas
receipts are entered as positive values.

Pv Double representing the present value of your annuity. In

the case of a loan, the present value would be the amount
of the loan, whereas in the case of a retirement annuity, the
present value would be the amount of the fund.

Due Integer indicating when payments are due for each

payment period. A 0 specifies payment at the end of each
period, whereas a 1 indicates payment at the start of each
period.

Rate and NPer values must be expressed in the same units. If Rate is expressed as a
percentage per month, then NPer must also be expressed in months. If Rate is an
annual rate, then the NPer must also be given in years.

Positive numbers represent cash received, whereas negative numbers represent

cash paid out.

3-250 Docbasic User’s Guide

A-Z Reference Fv (function)

Example
This example calculates the future value of 100 dollars paid periodically for a
period of 10 years (120 months) at a rate of 10% per year (or .10/12 per month) with
payments made on the first of the month. The value is displayed in a dialog box.
Note: that payments are negative values.
Sub Main()
a# = Fv((.10/12),120,-100.00,0,1)
MsgBox "Future value is: " & Format(a#,"Currency")
End Sub

Platform(s)
All.

See Also
IRR (function)
MIRR (function)
Npv (function)
Pv (function)

Docbasic User’s Guide 3-251

Get (statement) A-Z Reference

Get (statement)

Retrieves data from a random or binary file and stores that data into the specified
variable.

Syntax
Get [#] filenumber, [recordnumber], variable

Description
The Get statement accepts the following parameters:

filenumber Integer used by Docbasic to identify the file. This is the

same number passed to the Open statement.

recordnumber Long specifying which record is to be read from the file.

For binary files, this number represents the first byte to be

read starting with the beginning of the file (the first byte is
1). For random files, this number represents the record
number starting with the beginning of the file (the first
record is 1). This value ranges from 1 to 2147483647.

If the recordnumber parameter is omitted, the next record is

read from the file (if no records have been read yet, then
the first record in the file is read). When this parameter is
omitted, the commas must still appear, as in the following
example:

Get #1,,recvar

If recordnumber is specified, it overrides any previous

change in file position specified with the Seek statement.

variable Variable into which data will be read. The type of the
variable determines how the data is read from the file, as
described below.

With random files, a runtime error will occur if the length of the data being read
exceeds the reclen parameter specified with the Open statement. If the length of the
data being read is less than the record length, the file pointer is advanced to the
start of the next record. With binary files, the data elements being read are
contiguousthe file pointer is never advanced.

3-252 Docbasic User’s Guide

A-Z Reference Get (statement)

The type of the variable parameter determines how data will be read from the file.
It can be any of the following types:

Table 3-46 Effect of the Data Type of the Variable Parameter

Variable type Storage description

Integer 2 bytes are read from the file.

Long 4 bytes are read from the file.

String (variable-length) In binary files, variable-length strings are read by first

determining the specified string variable’s length and then
reading that many bytes from the file. For example, to read a
string of eight characters:
s$=String$(8,"")
Get#1,,s$
In random files, variable-length strings are read by first reading
a 2-byte length and then reading that many characters from the
file.

String (fixed-length) Fixed-length strings are read by reading a fixed number of

characters from the file equal to the string’s declared length.

Double 8 bytes are read from the file(IEEE format).

Single 4 bytes are read from the file (IEEE format).

Date 8 bytes are read from the file (IEEE double format).

Boolean 2 bytes are read from the file. Nonzero values are True, and
zero values are False.

Variant A 2-byte VarType is read form the file, which determines the
format of the data that follows. Once the VarType is known, the
data is read individually, as described above. With user-
defined errors, after the 2-byte VarType, a 2-byte unsigned
integer is read and assigned as the value of the user-defined
error, followed by 2 additional bytes of information about the
error.
The exception is with strings, which are always preceded by a 2-
byte length.

User-defined type Each member of a user-defined data type is read individually.

In binary files, variable-length strings within user-defined types
are read by first reading a 2-byte length followed by the string’s
content. This storage is different from variable-length strings
outside of user-defined types.
When reading user-defined types, the record length must be
greater than or equal to the combined size of each element
within the data type.

Arrays Arrays cannot be read from a file using the Get statement.

Object Object variables cannot be read from a file using the Get
statement.

Docbasic User’s Guide 3-253

Get (statement) A-Z Reference

Example
This example opens a file for random write, then writes ten records into the file
with the values 10...50. Then the file is closed and reopened in random mode for
read, and the records are read with the Get statement. The result is displayed in a
message box.
Sub Main()
Open "test.dat" For Random Access Write As #1
For x = 1 to 10
y% = x * 10
Put #1,x,y
Next x
Close

Open "test.dat" For Random Access Read As #1

For y = 1 to 5
Get #1,y,x%
msg = msg & "Record " & y & ": " & x% & Basic.Eoln$
Next y

MsgBox msg
Close
End Sub

Platform(s)
All.

See Also
Open (statement)
Put (statement)
Input# (statement)
Line Input# (statement)
Input, Input$ (functions)

3-254 Docbasic User’s Guide

A-Z Reference GetAppInfo (function)

GetAppInfo (function)

Retrieves a string from a specified section of a specified file.

Syntax
GetAppInfo(section$,entry$,filename$)

Description
The GetAppInfo function accepts the following parameters:

section$ The name of the section containing the entry in the file. The
name can contain only alphabetic characters and is case-
sensitive. Do not include brackets ([ ]) around the name.

entry$ The name of the entry to retrieve.

filename$ The name of the file where the settings are stored. Do not
include a file name extension. Docbasic automatically adds
".ini" as the file name extension.

Use GetAppInfo to retrieve a string stored using SetAppInfo. GetAppInfo assumes

the string is stored in the following format:
[section$]
entry$ = string$

Example
This example retrieves an entry called "WindowPosition" in a section called
"MyApplication" in MyFile.ini.
Sub Main()
ret$ = GetAppInfo("My Application","WindowPosition","MyFile")
End Sub

Platform(s)
All.

See Also
SetAppInfo (function)

Docbasic User’s Guide 3-255

GetAttr (function) A-Z Reference

GetAttr (function)

Returns an Integer containing the attributes of the specified file.

Syntax
GetAttr(filename$)

Description
The attribute value returned is the sum of the attributes set for the file. The value
of each attribute is as follows:

Table 3-47 File Attribute Values

Constant Value Includes

ebNormal 0 Read-only files, archive files, subdirectories, and files with

no attributes

ebReadOnly 1 Read-only files

ebHidden 2 Hidden files

ebSystem 4 System files

ebVolume 9 Volume labe

ebArchive 32 Files that have changed since the last backup

ebNone 64 Files with no attributes

To determine whether a particular attribute is set, you can And the values shown
above with the value returned by GetAttr. If the result is True, the attribute is set,
as shown below:
Dim w As Integer
w = GetAttr("sample.txt")
If w And ebReadOnly Then MsgBox "This file is read-only."

Example
This example tests to see whether the file test.dat exists. If it does not, then it
creates the file. The file attributes are 'then retrieved with the GetAttr function, and
the result is displayed.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
If Not FileExists("test.dat") Then
Open "test.dat" For Random Access Write As #1

3-256 Docbasic User’s Guide

A-Z Reference GetAttr (function)

Close
End If

y% = GetAttr("test.dat")
If y% And ebNone Then msg = msg & "No archive bit is set." & crlf
If y% And ebReadOnly Then msg = msg & "The read-only bit is set." & crlf
If y% And ebHidden Then msg = msg & "The hidden bit is set." & crlf
If y% And ebSystem Then msg = msg & "The system bit is set." & crlf
If y% And ebVolume Then msg = msg & "The volume bit is set." & crlf
If y% And ebDirectory Then msg = msg & "The directory bit is set." & crlf
If y% And ebArchive Then msg = msg & "The archive bit is set."

MsgBox msg
Kill "test.dat"
End Sub

Platform(s)
All.

Platform Notes: UNIX

On UNIX platforms, the hidden file attribute corresponds to files without the read
or write attributes.

See Also
SetAttr (statement)
FileAttr (function)

Docbasic User’s Guide 3-257

GetObject (function) A-Z Reference

GetObject (function)

Returns the object specified by filename$ or returns a previously instantiated object

of the given class$.

Syntax
GetObject(filename$ [,class$])

Description
This function is used to retrieve an existing OLE automation object, either one that
comes from a file or one that has previously been instantiated.

The filename$ argument specifies the full pathname of the file containing the object
to be activated. The application associated with the file is determined by OLE at
runtime. For example, suppose that a file called c:\docs\resume.doc was created
by a word processor called wordproc.exe. The following statement would invoke
wordproc.exe, load the file called c:\docs\resume.doc, and assign that object to a
variable:
Dim doc As Object
Set doc = GetObject("c:\docs\resume.doc")

To activate a part of an object, add an exclamation point to the filename followed

by a string representing the part of the object that you want to activate. For
example, to activate the first three pages of the document in the previous example:
Dim doc As Object
Set doc = GetObject("c:\docs\resume.doc!P1-P3")

The GetObject function behaves differently depending on whether the first

parameter is omitted. The following table summarizes the different behaviors of
GetObject:

Table 3-48 Effect of Parameters on the GetObject Function

Filename$ Class$ GetObject returns

Not Specified Specified A reference to an existing instance of the specified

object. A runtime error results if the object is not
already loaded.

"" Specified A reference to a new object (as specified by class$).

A runtime error occurs if an object of the specified
class cannot be found.
This is the same as CreateObject.

Specified Not Specified The default object from filename$. The application
to activate is determined by OLE based on the given
filename.

3-258 Docbasic User’s Guide

A-Z Reference GetObject (function)

Table 3-48 Effect of Parameters on the GetObject Function

Filename$ Class$ GetObject returns

Specified Specified The object given class$ from the file given by
filename$. A runtime error occurs if an object of the
given class cannot be found in the given file.

Examples
This first example instantiates the existing copy of Excel.
Dim Excel As Object
Set Excel = GetObject(,"Excel.Application")

This second example loads the OLE server associated with a document.
Dim MyObject As Object
Set MyObject = GetObject("c:\documents\resume.doc",)

Platform(s)
Windows, Win32, Macintosh.

See Also
CreateObject (function)
Object (data type)

Docbasic User’s Guide 3-259

GetSession (function) A-Z Reference

GetSession (function)

Returns an alias representing the current session.

Syntax
GetSession()

Description
Use GetSession() to retrieve the current session for use in Workspace or Server API
commands that require a session identifier. GetSession() is most useful when more
than one session is open. You can also use GetSession() to determine if any session
is open at all.

If no session is open, GetSession() returns a NULL string; otherwise, GetSession()

returns an alias representing the current session.

Example
This example uses GetSession() to retrieve the current session and inserts the result
into a Fetch command:
Sub Main()
Session$ = GetSession()
cmd% = "fetch," + session$ + ",0900000987893e31"
ret% = dmAPIExec( cmd$ )
End Sub

Platform(s)
All.

3-260 Docbasic User’s Guide

A-Z Reference Global (statement)

Global (statement)

Description
See Public (statement).

Platform(s)
All.

GoSub (statement)

Causes execution to continue at the specified label.

Syntax
GoSub label

Description
Execution can later be returned to the statement following the GoSub by using the
Return statement.

The label parameter must be a label within the current function or subroutine.
GoSub outside the context of the current function or subroutine is not allowed.

Example
This example gets a name from the user and then branches to a subroutine to check
the input. If the user clicks Cancel or enters a blank name, the program terminates;
otherwise, the name is set to MICHAEL, and a message is displayed.
Sub Main()
uname$ = Ucase$(InputBox$("Enter your name:","Enter Name"))
GoSub CheckName
MsgBox "Hello, " & uname$
Exit Sub

CheckName:
If (uname$ = "") Then
GoSub BlankName
ElseIf uname$ = "MICHAEL" Then
GoSub RightName
Else
GoSub OtherName
End If

Docbasic User’s Guide 3-261

Global (statement) A-Z Reference

Return

BlankName:
MsgBox "No name? Clicked Cancel? I'm shutting down."
Exit Sub

RightName:
Return

OtherName:
MsgBox "I am renaming you MICHAEL!"
uname$ = "MICHAEL"
Return
End Sub

Platform(s)
All.

See Also
Goto (statement)
Return (statement)

3-262 Docbasic User’s Guide

A-Z Reference Goto (statement)

Goto (statement)

Transfers execution to the line containing the specified label.

Syntax
Goto label

Description
The compiler will produce an error if label does not exist.

The label must appear within the same subroutine or function as the Goto.

Labels are identifiers that follow these rules:

Must begin with a letter.

May contain letters, digits, and the underscore character.

Must not exceed 80 characters in length.

Must be followed by a colon (:).

Labels are not case-sensitive.

Example
This example gets a name from the user and then branches to a statement,
depending on the input name. If the name is not MICHAEL, it is reset to
MICHAEL unless it is null or the user clicks Cancel--in which case, the program
displays a message and terminates.
Sub Main()
uname$ = Ucase$(InputBox$("Enter your name:","Enter Name"))
If uname$ = "MICHAEL" Then
Goto RightName
Else
Goto WrongName
End If

WrongName:
If (uname$ = "") Then
MsgBox "No name? Clicked Cancel? I'm shutting down."
Else
MsgBox "I am renaming you MICHAEL!"
uname$ = "MICHAEL"
Goto RightName
End If
Exit Sub

Docbasic User’s Guide 3-263

Goto (statement) A-Z Reference

RightName:
MsgBox "Hello, MICHAEL!"
End Sub

Platform(s)
All.

Platform Notes: Windows, Win32

To break out of an infinite loop, press Ctrl+Break.

Platform Notes: UNIX

To break out of an infinite loop, press Ctrl+C.

Platform Notes: Macintosh

To break out of an infinite loop, press Ctrl+Period.

See Also
GoSub (statement)
Call (statement)

3-264 Docbasic User’s Guide

A-Z Reference Hex, Hex$ (functions)

Hex, Hex$ (functions)

Returns a String containing the hexadecimal equivalent of number.

Syntax
Hex[$](number)

Description
Hex$ returns a String, whereas Hex returns a String variant.

The returned string contains only the number of hexadecimal digits necessary to
represent the number, up to a maximum of eight.

The number parameter can be any type but is rounded to the nearest whole number
before converting to hex. If the passed number is an integer, then a maximum of
four digits are returned; otherwise, up to eight digits can be returned.

The number parameter can be any expression convertible to a number. If number is

Null, then Null is returned. Empty is treated as 0.

Example
This example inputs a number and displays it in decimal and hex until the input
number is 0 or an invalid input.
Sub Main()
Do
xs$ = InputBox$("Enter a number to convert:","Hex Convert")
x = Val(xs$)
If x <> 0 Then
MsgBox "Dec: " & x & " Hex: " & Hex$(x)
Else
MsgBox "Goodbye."
End If
Loop While x <> 0
End Sub

Platform(s)
All.

See Also
Oct, Oct$ (functions)

Docbasic User’s Guide 3-265

Hour (function) A-Z Reference

Hour (function)

Returns the hour of the day encoded in the time parameter.

Syntax
Hour(time)

Description
The value returned is as an Integer between 0 and 23 inclusive.

The time parameter is any expression that converts to a Date.

Example
This example takes the current time; extracts the hour, minute, and second; and
displays them as the current time.
Sub Main()
xt# = TimeValue(Time$())
xh# = Hour(xt#)
xm# = Minute(xt#)
xs# = Second(xt#)
MsgBox "The current time is: " & xh# & ":" & xm# & ":" & xs#
End Sub

Platform(s)
All.

See Also
Day (function)
Minute (function)
Second (function)
Month (function)
Year (function)
Weekday (function)
DatePart (function)

3-266 Docbasic User’s Guide

A-Z Reference If...Then...Else (statement)

If...Then...Else (statement)

Conditionally executes a statement or group of statements.

Syntax 1
If condition Then statements [Else else_statements]

Syntax 2
If condition Then
[statements]
[ElseIf else_condition Then
[elseif_statements]]
[Else
[else_statements]]
End If

Description
The single-line conditional statement (syntax 1) has the following parameters:

condition Any expression evaluating to a Boolean value.

statements One or more statements separated with colons.

This group of statements is executed when
condition is True.

else_statements One or more statements separated with colons.

This group of statements is executed when
condition is False.

The multiline conditional statement (syntax 2) has the following parameters:

condition Any expression evaluating to a Boolean value.

statements One or more statements to be executed when

condition is True.

else_condition Any expression evaluating to a Boolean value. The

else condition is evaluated if condition is False.

elseif_statements One or more statements to be executed when

condition is False and else_condition is True.

Docbasic User’s Guide 3-267

If...Then...Else (statement) A-Z Reference

else_statments One or more statements to be executed when both

condition and else_condition are False.

There can be as many ElseIf conditions as required.

Example
This example inputs a name from the user and checks to see whether it is
MICHAEL or MIKE using three forms of the If...Then...Else statement. It then
branches to a statement that displays a welcome message depending on the user's
name.
Sub Main()
uname$ = UCase$(InputBox$("Enter your name:","Enter Name"))
If uname$ = "MICHAEL" Then GoSub MikeName

If uname$ = "MIKE" Then

GoSub MikeName
Exit Sub
End If

If uname$ = "" Then

MsgBox "Since you don't have a name, I'll call you MIKE!"
uname$ = "MIKE"
GoSub MikeName
ElseIf uname$ = "MICHAEL" Then
GoSub MikeName
Else
GoSub OtherName
End If
Exit Sub

MikeName:
MsgBox "Hello, MICHAEL!"
Return

OtherName:
MsgBox "Hello, " & uname$ & "!"
Return
End Sub

Platform(s)
All.

See Also
Choose (function)
Switch (function)
IIf (function)
Select...Case (statement)

3-268 Docbasic User’s Guide

A-Z Reference IIf (function)

IIf (function)

Returns TrueExpression if condition is True; otherwise, returns FalseExpression.

Syntax
IIf(condition,TrueExpression,FalseExpression)

Description
Both expressions are calculated before IIf returns.

The IIf function is shorthand for the following construct:

If condition Then
variable = TrueExpression
Else
variable = FalseExpression
End If

Example
Sub Main()
s$ = "Car"
MsgBox IIf(s$ = "Car","Nice Car","Nice Automobile")
End Sub

Platform(s)
All.

See Also
Choose (function)
Switch (function)
If...Then...Else (statement)
Select...Case (statement)

Docbasic User’s Guide 3-269

Imp (operator) A-Z Reference

Imp (operator)

Performs a logical or binary implication on two expressions.

Syntax
expression1 Imp expression2

Description
If both expressions are either Boolean, Boolean variants, or Null variants, then a
logical implication is performed as follows:

Table 3-49 Effect of Boolean and Null Expressions on the Imp Operator

If the first expression is and the second expression is Then the result is

True True True

True False False

True Null Null

False True True

False False True

False Null True

Null True True

Null False Null

Null Null Null

Binary Implication

If the two expressions are Integer, then a binary implication is performed,

returning an Integer result. All other numeric types (including Empty variants) are
converted to Long and a binary implication is then performed, returning a Long
result.

Binary implication forms a new value based on a bit-by-bit comparison of the

binary representations of the two expressions, according to the following table:

3-270 Docbasic User’s Guide

A-Z Reference Imp (operator)

Table 3-50 Binary Implication

1 Imp 1 = 1 Example:

0 Imp 1 = 1 5 01101001

1 Imp 0 = 0 6 10101010

0 Imp 0 = 1 Imp 1011110

Example
This example compares the result of two expressions to determine whether one
implies the other.
Sub Main()
a = 10 : b = 20 : c = 30 : d = 40

If (a < b) Imp (c < d) Then

MsgBox "a is less than b implies that c is less than d."
Else
MsgBox "a is less than b does not imply that c is less than d."
End If

If (a < b) Imp (c > d) Then

MsgBox "a is less than b implies that c is greater than d."
Else
MsgBox "a is less than b does not imply that c is greater than d."
End If
End Sub

Platform(s)
All.

See Also
Operator Precedence (topic)
Or (operator)
Xor (operator)
Eqv (operator)
And (operator)

Docbasic User’s Guide 3-271

Inline (statement) A-Z Reference

Inline (statement)

Allows execution or interpretation of a block of text.

Syntax
Inline name [parameters]
anytext
End Inline

Description
The Inline statement takes the following parameters:

name Identifier specifying the type of inline statement.

parameters Comma-separated list of parameters.

anytext Text to be executed by the Inline statement. This text must

be in a format appropriate for execution by the Inline
statement.

The end of the text is assumed to be the first occurrence of

the words End Inline appearing on a line.

Example
Sub Main()
Inline MacScript
-- This is an AppleScript comment.
Beep
Display Dialog "AppleScript" buttons "OK" default button "OK"
Display Dialog Current Date
End Inline
End Sub

Platform(s)
All.

See Also
MacScript (statement)

3-272 Docbasic User’s Guide

A-Z Reference Input# (statement)

Input# (statement)

Reads data from the file referenced by filenumber into the given variables.

Syntax
Input [#]filenumber%,variable[,variable]...

Description
The filenumber parameter is a number that is used by Docbasic to refer to the open
filethe number passed to the Open statement.

The file number must reference a file opened in Input mode. It is good practice to
use the Write statement to write date elements to files read with the Input
statement to ensure that the variable list is consistent between the input and output
routines.

Each variable must be type-matched to the data in the file. For example, a String
variable must be matched to a string in the file.

The following parsing rules are observed while reading each variable in the
variable list:

Leading white space is ignored (spaces and tabs).

When reading String variables, if the first character on the line is a quotation
mark, then characters are read up to the next quotation mark or the end of
the line, whichever comes first. Blank lines are read as empty strings. If the
first character read is not a quotation mark, then characters are read up to
the first comma or the end of the line, whichever comes first. String
delimiters (quotes, comma, end-of-line) are not included in the returned
string.

When reading numeric variables, scanning of the number stops when the
first non-number character (such as a comma, a letter, or any other
unexpected character) is encountered. Numeric errors are ignored while
reading numbers from a file. The resultant number is automatically
converted to the same type as the variable into which the value will be
placed. If there is an error in conversion, then 0 is stored into the variable.

After reading the number, input is skipped up to the next delimiter—a

comma, an end-of-line, or an end-of-file.

Numbers must adhere to any of the following syntaxes:

[-|+]digits[.digits][E[-|+]digits][!|#|%|&|@]

&Hhexdigits[!|#|%|&]

&[O]octaldigits[!|#|%|&|@]

Docbasic User’s Guide 3-273

Input# (statement) A-Z Reference

When reading Boolean variables, the first character must be #; otherwise, a

runtime error occurs. If the first character is #, then input is scanned up to
the next delimiter (a comma, an end-of-line, or an end-of-file). If the input
matches #FALSE#, then False is stored in the Boolean; otherwise True is
stored.

When reading Date variables, the first character must be #; otherwise, a
runtime error occurs. If the first character is #, then the input is scanned up
to the next delimiter (a comma, an end-of-line, or an end-of-file). If the input
ends in a # and the text between the #'s can be correctly interpreted as a date,
then the date is stored; otherwise, December 31, 1899, is stored.

Normally, dates that follow the universal date format are input from
sequential files. These dates use this syntax:
#YYYY-MM-DD HH:MM:SS#

where YYYY is a year between 100 and 9999, MM is a month between 1 and
12, DD is a day between 1 and 31, HH is an hour between 0 and 23, MM is a
minute between 0 and 59, and SS is a second between 0 and 59.

When reading Variant variables, if the data begins with a quotation mark,
then a string is read consisting of the characters between the opening
quotation mark and the closing quotation mark, end-of-line, or end-of-file.

If the input does not begin with a quotation mark, then input is scanned up
to the next comma, end-of-line, or end-of-file and a determination is made as
to what data is being represented. If the data cannot be represented as a
number, Date, Error, Boolean, or Null, then it is read as a string.

The following table describes how special data is interpreted as variants:

Table 3-51How the Input# Statement Interprets Variant Data

Data Interpretation

Blank line Read as an Empty variant.

#NULL# Read as a Null variant.

#TRUE# Read as a Boolean variant.

#FALSE# Read as a Boolean variant.

"ERROR code" Read as a user-defined error.

#date# Read as a Date variant.

"text" Read as a String variant.

If an error occurs in interpretation of the data as a particular type, then that

data is read as a String variant.

When reading numbers into variants, the optional type-declaration character

determines the VarType of the resulting variant. If no type-declaration

3-274 Docbasic User’s Guide

A-Z Reference Input# (statement)

character is specified, then Docbasic will read the number according to the
following rules:

Rule 1: If the number contains a decimal point or an exponent, then the

number is read as Currency. If there is an error converting to Currency, then
the number is treated as a Double.

Rule 2: If the number does not contain a decimal point or an exponent, then
the number is stored in the smallest of the following data types that most
accurately represents that value: Integer, Long, Currency, Double.

End-of-line is interpreted as either a single line feed, a single carriage return,
or a carriage-return/line-feed pair. Thus, text files from any platform can be
interpreted using this command.

Example
This example creates a file called test.dat and writes a series of variables into it.
Then the variables are read using the Input# function.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
Open "test.dat" For Output As #1
Write #1,2112,"David","McCue","123-45-6789"
Close

Open "test.dat" For Input As #1

Input #1,x%,st1$,st2$,st3$
msg = "Employee " & x% & " Information" & crlf & crlf
msg = msg & "First Name: " & st1$ & crlf
msg = msg & "Last Name: "& st2$ & crlf
msg = msg & "Social Security Number: " & sy3$
MsgBox msg
Close

Kill "test.dat"
End Sub

Platform(s)
All.

See Also
Open (statement)
Get (statement)
Line Input# (statement)
Input, Input$ (functions)

Docbasic User’s Guide 3-275

Input, Input$ (functions) A-Z Reference

Input, Input$ (functions)

Returns numbytes characters read from a given sequential file.

Syntax
Input[$](numbytes,[#]filenumber)

Description
Input$ returns a String, whereas Input returns a String variant.

The Input/Input$ functions require the following parameters:

numbytes Integer containing the number of bytes to be read from the

file.

filenumber Integer referencing a file opened in either Input or Binary

mode. This is the same number passed to the Open
statement.

This function reads all characters, including spaces and end-of-lines.

Example
This example opens the autoexec.bat file and displays it in a dialog box.
Const crlf = Chr$(13) & Chr$(10)

Sub Main()
x& = FileLen("c:\autoexec.bat")
If x& > 0 Then
Open "c:\autoexec.bat" For Input As #1
Else
MsgBox "File not found or empty."
Exit Sub
End If

If x& > 80 Then

ins = Input(80,#1)
Else
ins = Input(x,#1)
End If
Close
MsgBox "File length: " & x& & crlf & ins
End Sub

3-276 Docbasic User’s Guide

A-Z Reference Input, Input$ (functions)

Platform(s)
All.

See Also
Open (statement)
Get (statement)
Input# (statement)
Line Input# (statement)

Docbasic User’s Guide 3-277

InputBox, InputBox$ (functions) A-Z Reference

InputBox, InputBox$ (functions)

Displays a dialog box with a text box into which the user can type.

Syntax
InputBox[$](prompt [,[title] [,[default] [,X,Y]]])

Description
The content of the text box is returned as a String (in the case of InputBox$) or as a
String variant (in the case of InputBox). A zero-length string is returned if the user
selects Cancel.

Argument Descriptions
The InputBox/InputBox$ functions take the following parameters:

prompt Text to be displayed above the text box. The prompt

parameter can contain multiple lines, each separated with
an end-of-line (a carriage return, line feed, or carriage-
return/line-feed pair). A runtime error is generated if
prompt is Null.

title Caption of the dialog box. If this parameter is omitted, then

no title appears as the dialog box's caption. A runtime error
is generated if title is Null.

default Default response. This string is initially displayed in the

text box. A runtime error is generated if default is Null.

X, Y Integer coordinates, given in twips (twentieths of a point),

specifying the upper left corner of the dialog box relative to
the upper left corner of the screen. If the position is
omitted, then the dialog box is positioned on or near the
application executing the procedure.

Example
Sub Main()
s$ = InputBox$("File to copy:","Copy","sample.txt")
End Sub

3-278 Docbasic User’s Guide

A-Z Reference InputBox, InputBox$ (functions)

Platform(s)
Windows.

See Also
MsgBox (statement)
OpenFilename$ (function)
SaveFilename$ (function)

Docbasic User’s Guide 3-279

InStr (function) A-Z Reference

InStr (function)

Returns the first character position of string find within string search.

Syntax
InStr([start,] search, find [,compare])

Description
The InStr function takes the following parameters:

start Integer specifying the character position where searching

begins. The start parameter must be between 1 and 32767.

If this parameter is omitted, then the search starts at the

beginning (start = 1).

search Text to search. This can be any expression convertible to a

String.

find Text for which to search. This can be any expression

convertible to a String.

compare Integer controlling how string comparisons are performed:

0 – String comparisons are case-sensitive.

1 – String comparisons are case-insensitive.

For any other value, a runtime error is produced.

If this parameter is omitted, then string comparisons use

the current Option Compare setting. If no Option Compare
statement has been encountered, then Binary is used (i.e.,
string comparisons are case-sensitive).

If the string is found, then its character position within search is returned, with 1
being the character position of the first character. If find is not found, or start is
greater than the length of search, or search is zero-length, then 0 is returned.

Example
This example checks to see whether one string is in another and, if it is, then it
copies the string to a variable and displays the result.

3-280 Docbasic User’s Guide

A-Z Reference InStr (function)

Sub Main()
a$ = "This string contains the name Stuart and other characters."
x% = InStr(a$,"Stuart",1)
If x% <> 0 Then
b$ = Mid$(a$,x%,6)
MsgBox b$ & " was found."
Exit Sub
Else
MsgBox "Stuart not found."
End If
End Sub

Platform(s)
All.

See Also
Mid, Mid$ (functions)
Option Compare (statement)
Item$ (function)
Word$ (function)
Line$ (function)

Docbasic User’s Guide 3-281

Int (function) A-Z Reference

Int (function)

Returns the integer part of number.

Syntax
Int(number)

Description
This function returns the integer part of a given value by returning the first integer
less than the number. The sign is preserved.

The Int function returns the same type as number, with the following exceptions:

If number is Empty, then an Integer variant of value 0 is returned.

If number is a String, then a Double variant is returned.

If number is Null, then a Null variant is returned.

Example
This example extracts the integer part of a number.
Sub Main()
a# = -1234.5224
b% = Int(a#)
MsgBox "The integer part of -1234.5224 is: " & b%
End Sub

Platform(s)
All.

See Also
Fix (function)
CInt (function)

3-282 Docbasic User’s Guide

A-Z Reference Integer (data type)

Integer (data type)

A data type used to declare whole numbers with up to four digits of precision.

Syntax
Integer

Description
Integer variables are used to hold numbers within the following range:
-32768 <= integer <= 32767

Internally, integers are 2-byte short values. Thus, when appearing within a
structure, integers require 2 bytes of storage. When used with binary or random
files, 2 bytes of storage are required.

When passed to external routines, Integer values are sign-extended to the size of
an integer on that platform (either 16 or 32 bits) before pushing onto the stack.

The type-declaration character for Integer is %.

Platform(s)
All.

See Also
Currency (data type)
Date (data type)
Double (data type)
Long (data type)
Object (data type)
Single (data type)
String (data type)
Variant (data type)
Boolean (data type)
DefType (statement)
CInt (function)

Docbasic User’s Guide 3-283

IPmt (function) A-Z Reference

IPmt (function)

Returns the interest payment for a given period of an annuity based on periodic,
fixed payments and a fixed interest rate.

Syntax
IPmt(Rate, Per, Nper, Pv, Fv, Due)

Description
An annuity is a series of fixed payments made to an insurance company or other
investment company over a period of time. Examples of annuities are mortgages,
monthly savings plans, and retirement plans.

The following table describes the different parameters:

Rate Double representing the interest rate per period. If the

payment periods are monthly, be sure to divide the annual
interest rate by 12 to get the monthly rate.

Per Double representing the payment period for which you are
calculating the interest payment. If you want to know the
interest paid or received during period 20 of an annuity,
this value would be 20.

Nper Double representing the total number of payments in the

annuity. This is usually expressed in months, and you
should be sure that the interest rate given above is for the
same period that you enter here.

Pv Double representing the present value of your annuity. In

the case of a loan, the present value would be the amount
of the loan because that is the amount of cash you have in
the present. In the case of a retirement plan, this value
would be the current value of the fund because you have a
set amount of principal in the plan.

Fv Double representing the future value of your annuity. In

the case of a loan, the future value would be zero because
you will have paid it off. In the case of a savings plan, the
future value would be the balance of the account after all
payments are made.

3-284 Docbasic User’s Guide

A-Z Reference IPmt (function)

Due Integer indicating when payments are due. If this

parameter is 0, then payments are due at the end of each
period (usually, the end of the month). If this value is 1,
then payments are due at the start of each period (the
beginning of the month).

Rate and Nper must be in expressed in the same units. If Rate is expressed in
percentage paid per month, then Nper must also be expressed in months. If Rate is
an annual rate, then the period given in Nper should also be in years or the annual
Rate should be divided by 12 to obtain a monthly rate.

If the function returns a negative value, it represents interest you are paying out,
whereas a positive value represents interest paid to you.

Example
This example calculates the amount of interest paid on a $1,000.00 loan financed
over 36 months with an annual interest rate of 10%. Payments are due at the
beginning of the month. The interest paid during the first 10 months is displayed
in a table.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
For x = 1 to 10
ipm# = IPmt((.10/12),x,36,1000,0,1)
msg = msg & Format(x,"00") & " : " & Format(ipm#," 0,0.00") & crlf
Next x
MsgBox msg
End Sub

Platform(s)
All.

See Also
NPer (function)
Pmt (function)
PPmt (function)
Rate (function)

Docbasic User’s Guide 3-285

IRR (function) A-Z Reference

IRR (function)

Returns the internal rate of return for a series of periodic payments and receipts.

Syntax
IRR(ValueArray(),Guess)

Description
The internal rate of return is the equivalent rate of interest for an investment
consisting of a series of positive and/or negative cash flows over a period of
regular intervals. It is usually used to project the rate of return on a business
investment that requires a capital investment up front and a series of investments
and returns on investment over time.

The IRR function requires the following parameters:

ValueArray() Array of Double numbers that represent payments and

receipts. Positive values are payments, and negative values
are receipts.

There must be at least one positive and one negative value

to indicate the initial investment (negative value) and the
amount earned by the investment (positive value).

Guess Double containing your guess as to the value that the IRR
function will return. The most common guess is .1 (10
percent).

The value of IRR is found by iteration. It starts with the value of Guess and cycles
through the calculation adjusting Guess until the result is accurate within 0.00001
percent. After 20 tries, if a result cannot be found, IRR fails, and the user must pick
a better guess.

Example
This example illustrates the purchase of a lemonade stand for $800 and a series of
incomes from the sale of lemonade over 12 months. The projected incomes for this
example are generated in two For...Next Loops, and then the internal rate of return
is calculated and displayed. (Not a bad investment!)
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
Dim valu#(12)
valu(1) = -800 'Initial investment

3-286 Docbasic User’s Guide

A-Z Reference IRR (function)

msg = valu#(1) & ", "

'Calculate the second through fifth months' sales.

For x = 2 To 5
valu(x) = 100 + (x * 2)
msg = msg & valu(x) & ", "
Next x

'Calculate the sixth through twelfth months' sales.

For x = 6 To 12
valu(x) = 100 + (x * 10)
msg = msg & valu(x) & ", "
Next x

'Calculate the equivalent investment return rate.

retrn# = IRR(valu,.1)
msg = "The values: " & crlf & msg & crlf & crlf
MsgBox msg & "Return rate: " & Format(retrn#,"Percent")
End Sub

Platform(s)
All.

See Also
Fv (function)
MIRR (function)
Npv (function)
Pv (function)

Docbasic User’s Guide 3-287

Is (operator) A-Z Reference

Is (operator)

Returns True if the two operands refer to the same object; returns False otherwise.

Syntax
object Is [object | Nothing]

Description
This operator is used to determine whether two object variables refer to the same
object. Both operands must be object variables of the same type (i.e., the same data
object type or both of type Object).

The Nothing constant can be used to determine whether an object variable is

uninitialized:
If MyObject Is Nothing Then MsgBox "MyObject is uninitialized."

Uninitialized object variables reference no object.

Example
This function inserts the date into a Microsoft Word document.
Sub InsertDate(ByVal WinWord As Object)
If WinWord Is Nothing Then
MsgBox "Object variant is not set."
Else
WinWord.Insert Date$
End If
End Sub

Sub Main()
Dim WinWord As Object
On Error Resume Next
WinWord = CreateObject("word.basic")
InsertDate WinWord
End Sub

Platform(s)
All.

3-288 Docbasic User’s Guide

A-Z Reference Is (operator)

Platform Notes: Windows, Win32, Macintosh

When comparing OLE automation objects, the Is operator will only return True if
the operands reference the same OLE automation object. This is different from data
objects. For example, the following use of Is (using the object class called
excel.application) returns True:
Dim a As Object
Dim b As Object
a = CreateObject("excel.application")
b = a
If a Is b Then Beep

The following use of Is will return False, even though the actual objects may be the
same:
Dim a As Object
Dim b As Object
a = CreateObject("excel.application")
b = GetObject(,"excel.application")
If a Is b Then Beep

The Is operator may return False in the above case because, even though a and b
reference the same object, they may be treated as different objects by OLE 2.0 (this
is dependent on the OLE 2.0 server application).

See Also
Operator Precedence (topic)
Like (operator)

Docbasic User’s Guide 3-289

IsDate (function) A-Z Reference

IsDate (function)

Returns True if expression can be legally converted to a date; returns False

otherwise.

Syntax
IsDate(expression)

Example
Sub Main()
Dim a As Variant
Retry:
a = InputBox("Enter a date.", "Enter Date")
If IsDate(a) Then
MsgBox Format(a,"long date")
Else
Msgbox "Not quite, please try again!"
Goto Retry
End If
End Sub

Platform(s)
All.

See Also
Variant (data type)
IsEmpty (function)
IsError (function)
IsObject (function)
VarType (function)
IsNull (function)

3-290 Docbasic User’s Guide

A-Z Reference IsEmpty (function)

IsEmpty (function)

Returns True if expression is a Variant variable that has never been initialized;
returns False otherwise.

Syntax
IsEmpty(expression)

Description
The IsEmpty function is the same as the following:
(VarType(expression) = ebEmpty)

Example
Sub Main()
Dim a As Variant
If IsEmpty(a) Then
a = 1.0# 'Give uninitialized data a Double value 0.0.
MsgBox "The variable has been initialized to: " & a
Else
MsgBox "The variable was already initialized!"
End If
End Sub

Platform(s)
All.

See Also
Variant (data type)
IsDate (function)
IsError (function)
IsObject (function)
VarType (function)
IsNull (function)

Docbasic User’s Guide 3-291

IsError (function) A-Z Reference

IsError (function)

Returns True if expression is a user-defined error value; returns False otherwise.

Syntax
IsError(expression)

Example
This example creates a function that divides two numbers. If there is an error
dividing the numbers, then a variant of type "error" is returned. Otherwise, the
function returns the result of the division. The IsError function is used to determine
whether the function encountered an error.
Function Div(ByVal a,ByVal b) As Variant
If b = 0 Then
Div = CVErr(2112)'Return a special error value.
Else
Div = a / b 'Return the division.
End If
End Function

Sub Main()
Dim a As Variant
a = Div(10,12)
If IsError(a) Then
MsgBox "The following error occurred: " & CStr(a)
Else
MsgBox "The result is: " & a
End If
End Sub

Platform(s)
All.

See Also
Variant (data type)
IsEmpty (function)
IsDate (function)
IsObject (function)
VarType (function)
IsNull (function)

3-292 Docbasic User’s Guide

A-Z Reference IsMissing (function)

IsMissing (function)

Returns True if variable was passed to the current subroutine or function; returns
False if omitted.

Syntax
IsMissing(variable)

Description
IsMissing is used with variant variables passed as optional parameters (using the
Optional keyword) to the current subroutine or function. For non-variant variables
or variables that were not declared with the Optional keyword, IsMissing will
always return True.

Example
The following function runs an application and optionally minimizes it. If the
optional isMinimize parameter is not specified by the caller, then the application is
not minimized.
Sub Test(AppName As String,Optional isMinimize As Variant)
app = Shell(AppName)
If Not IsMissing(isMinimize) Then
AppMinimize app
Else
AppMaximize app
End If
End Sub

Sub Main
Test "Notepad"'Maximize this application
Test "Notepad",True'Minimize this application
End Sub

Platform(s)
All.

See Also
Declare (statement)
Sub...End Sub (statement)
Function...End Function (statement)

Docbasic User’s Guide 3-293

IsNull (function) A-Z Reference

IsNull (function)

Returns True if expression is a Variant variable that contains no valid data; returns
False otherwise.

Syntax
IsNull(expression)

Description
The IsNull function is the same as the following:
(VarType(expression) = ebNull)

Example
Sub Main()
Dim a As Variant'Initialized as Empty
If IsNull(a) Then MsgBox "The variable contains no valid data."
a = Empty * Null
If IsNull(a) Then MsgBox "Null propagated through the expression."
End Sub

Platform(s)
All.

See Also
Empty (constant)
Variant (data type)
IsEmpty (function)
IsDate (function)
IsError (function)
IsObject (function)
VarType (function)

3-294 Docbasic User’s Guide

A-Z Reference IsNumeric (function)

IsNumeric (function)

Returns True if expression can be converted to a number; returns False otherwise.

Syntax
IsNumeric(expression)

Description
If passed a number or a variant containing a number, then IsNumeric always
returns True.

If a String or String variant is passed, then IsNumeric will return True only if the
string can be converted to a number. The following syntaxes are recognized as
valid numbers:
&Hhexdigits[&|%|!|#|@]

&[O]octaldigits[&|%|!|#|@]

[-|+]digits[.[digits]][E[-|+]digits][!|%|&|#|@]

If an Object variant is passed, then the default property of that object is retrieved
and one of the above rules is applied.

IsNumeric returns False if expression is a Date.

Example
Sub Main()
Dim s$ As String
s$ = InputBox("Enter a number.","Enter Number")

If IsNumeric(s$) Then
MsgBox "You did good!"
Else
MsgBox "You didn't do so good!"
End If
End Sub

Platform(s)
All.

Docbasic User’s Guide 3-295

IsNumeric (function) A-Z Reference

See Also
Variant (data type)
IsEmpty (function)
IsDate (function)
IsError (function)
IsObject (function)
VarType (function)
IsNull (function)

3-296 Docbasic User’s Guide

A-Z Reference IsObject (function)

IsObject (function)

Returns True if expression is a Variant variable containing an Object; returns False

otherwise.

Syntax
IsObject(expression)

Example
This example will attempt to find a running copy of Excel and create an Excel
object that can be referenced as any other object in Docbasic.
Sub Main()
Dim v As Variant
On Error Resume Next
Set v = GetObject(,"Excel.Application")

If IsObject(v) Then
MsgBox"The default object value is: " & v = v.Value'Access value
property of the object.
Else
MsgBox "Excel not loaded."
End If
End Sub

Platform(s)
All.

See Also
Variant (data type)
IsEmpty (function)
IsDate (function)
IsError (function)
VarType (function)
IsNull (function)

Docbasic User’s Guide 3-297

Item$ (function) A-Z Reference

Item$ (function)

Returns all the items between first and last within the specified formatted text list.

Syntax
Item$(text$,first,last [,delimiters$])

Description
The Item$ function takes the following parameters:

text$ String containing the text from which a range of items is

returned.

first Integer containing the index of the first item to be returned.

If first is greater than the number of items in text$, then a
zero-length string is returned.

last Integer containing the index of the last item to be returned.

All of the items between first and last are returned. If last is
greater than the number of items in text$, then all items
from first to the end of text are returned.

delimiters$ String containing different item delimiters.

By default, items are separated by commas and end-of-

lines. This can be changed by specifying different
delimiters in the delimiters$ parameter.

Example
This example creates two delimited lists and extracts a range from each, then
displays the result in a dialog box.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
ilist$ = "1,2,3,4,5,6,7,8,9,10,11,12,13,14,15"
slist$ = "1/2/3/4/5/6/7/8/9/10/11/12/13/14/15"
list1$ = Item$(ilist$,5,12)
list2$ = Item$(slist$,2,9,"/")
MsgBox "The returned lists are: " & crlf & list1$ & crlf & list2$
End Sub

3-298 Docbasic User’s Guide

A-Z Reference Item$ (function)

Platform(s)
All.

See Also
ItemCount (function)
Line$ (function)
LineCount (function)
Word$ (function)
WordCount (function)

Docbasic User’s Guide 3-299

ItemCount (function) A-Z Reference

ItemCount (function)

Returns an Integer containing the number of items in the specified delimited text.

Syntax
ItemCount(text$ [,delimiters$])

Description
Items are substrings of a delimited text string. Items, by default, are separated by
commas and/or end-of-lines. This can be changed by specifying different
delimiters in the delimiters$ parameter. For example, to parse items using a
backslash:
n = ItemCount(text$,"\")

Example
This example creates two delimited lists and then counts the number of items in
each. The counts are displayed in a dialog box.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
ilist$ = "1,2,3,4,5,6,7,8,9,10,11,12,13,14,15"
slist$ = "1/2/3/4/5/6/7/8/9/10/11/12/13/14/15/16/17/18/19"

l1% = ItemCount(ilist$)
l2% = ItemCount(slist$,"/")
msg = "The first lists contains: " & l1% & " items." & crlf
msg = msg & "The second list contains: " & l2% & " items."
MsgBox msg
End Sub

Platform(s)
All.

See Also
Item$ (function)
Line$ (function)
LineCount (function)
Word$ (function)
WordCount (function)

3-300 Docbasic User’s Guide

A-Z Reference Keywords (topic)

Keywords (topic)

A keyword is any word or symbol recognized by Docbasic as part of the language.

All of the following are keywords:

Built-in subroutine names, such as MsgBox and Print.

Built-in function names, such as Str$, CDbl, and Mid$.

Special keywords, such as To, Next, Case, and Binary.

Names of any extended language elements.

Restrictions
All keywords are reserved by Docbasic, in that you cannot create a variable,
function, constant, or subroutine with the same name as a keyword. However, you
are free to use all keywords as the names of structure members.

Platform(s)
All.

Docbasic User’s Guide 3-301

Kill (statement) A-Z Reference

Kill (statement)

Deletes all files matching filespec$.

Syntax
Kill filespec$

Description
The filespec$ argument can include wildcards, such as * and ?. The * character
matches any sequence of zero or more characters, whereas the ? character matches
any single character. Multiple *'s and ?'s can appear within the expression to form
complex searching patterns. The following table shows some examples.

Table 3-52 Examples of * and ? Wildcards in Filespec$ Parameter

This pattern Matches these files Doesn’t match these files

*S.*TXT SAMPLE. TXT SAMPLE

GOOSE.TXT SAMPLE.DAT
SAMS.TXT

C*T.TXT CAT.TXT CAP.TXT

ACATS.TXT

C*T CAT CAT.DOC

CAP.TXT

C?T CAT CAT.TXT

CUT CAPIT
CT

* (All files)

Example
This example looks to see whether file test1.dat exists. If it does not, then it creates
both test1.dat and test2.dat. The existence of the files is tested again; if they exist, a
message is generated, and then they are deleted. The final test looks to see whether
they are still there and displays the result.
Sub Main()
If Not FileExists("test1.dat") Then
Open "test1.dat" For Output As #1
Open "test2.dat" For Output As #2
Close
End If

If FileExists ("test1.dat") Then

MsgBox "File test1.dat exists."

3-302 Docbasic User’s Guide

A-Z Reference Kill (statement)

Kill "test?.dat"
End If

If FileExists ("test1.dat") Then

MsgBox "File test1.dat still exists."
Else
MsgBox "test?.dat successfully deleted."
End If
End Sub

Platform(s)
All.

Platform Notes: Macintosh

The Macintosh does not support wildcard characters such as * and ?. These are
valid filename characters. Instead of wildcards, the Macintosh uses the MacID
function to specify a collection of files of the same type. The syntax for this function
is:
Kill MacID(text$)

The text$ parameter is a four-character string containing a file type, a resource type,
an application signature, or an Apple event. A runtime error occurs if the MacID
function is used on platforms other than the Macintosh.

See Also
Name (statement)

Docbasic User’s Guide 3-303

LBound (function) A-Z Reference

LBound (function)

Returns an Integer containing the lower bound of the specified dimension of the
specified array variable.

Syntax
LBound(ArrayVariable() [,dimension])

Description
The dimension parameter is an integer specifying the desired dimension. If this
parameter is not specified, then the lower bound of the first dimension is returned.

The LBound function can be used to find the lower bound of a dimension of an
array returned by an OLE automation method or property:
LBound(object.property [,dimension])

LBound(object.method [,dimension])

Examples
Sub Main()
'This example dimensions two arrays and displays their lower bounds.

Dim a(5 To 12)

Dim b(2 To 100, 9 To 20)

lba = LBound(a)
lbb = LBound(b,2)
MsgBox "The lower bound of a is: " & lba & " The lower bound of b is: "
& lbb

'This example uses LBound and UBound to dimension a dynamic array to

'hold a copy of an array redimmed by the FileList statement.

Dim fl$()
FileList fl$,"*.*"
count = UBound(fl$)
If ArrayDims(a) Then
Redim nl$(LBound(fl$) To UBound(fl$))
For x = 1 To count
nl$(x) = fl$(x)
Next x
MsgBox "The last element of the new array is: " & nl$(count)
End If
End Sub

3-304 Docbasic User’s Guide

A-Z Reference LBound (function)

Platform(s)
All.

See Also
UBound (function)
ArrayDims (function)
Arrays (topic)

Docbasic User’s Guide 3-305

LCase, LCase$ (functions) A-Z Reference

LCase, LCase$ (functions)

Returns the lowercase equivalent of the specified string.

Syntax
LCase[$](text)

Description
LCase$ returns a String, whereas LCase returns a String variant.

Null is returned if text is Null.

Example
This example shows the LCase function used to change uppercase names to
lowercase with an uppercase first letter.
Sub Main()
lname$ = "WILLIAMS"
fl$ = Left$(lname$,1)
rest$ = Mid$(lname$,2,Len(lname$))
lname$ = fl$ & LCase$(rest$)
MsgBox "The converted name is: " & lname$
End Sub

Platform(s)
All.

See Also
UCase, UCase$ (functions)

3-306 Docbasic User’s Guide

A-Z Reference Left, Left$ (functions)

Left, Left$ (functions)

Returns the leftmost NumChars characters from a given string.

Syntax
Left[$](text,NumChars)

Description
Left$ returns a String, whereas Left returns a String variant.

NumChars is an Integer value specifying the number of character to return. If

NumChars is 0, then a zero-length string is returned. If NumChars is greater than or
equal to the number of characters in the specified string, then the entire string is
returned.

Null is returned if text is Null.

Example
This example shows the Left$ function used to change uppercase names to
lowercase with an uppercase first letter.
Sub Main()
lname$ = "WILLIAMS"
fl$ = Left$(lname$,1)
rest$ = Mid$(lname$,2,Len(lname$))
lname$ = fl$ & LCase$(rest$)
MsgBox "The converted name is: " & lname$
End Sub

Platform(s)
All.

See Also
Right, Right$ (functions)

Docbasic User’s Guide 3-307

Len (function) A-Z Reference

Len (function)

Returns the length of a given expression.

Syntax
Len(expression)

Description
If expression evaluates to a string, then Len returns the number of characters in a
given string or 0 if the string is empty. When used with a Variant variable, the
length of the variant when converted to a String is returned. If expression is a Null,
then Len returns a Null variant.

If used with a non-String or non-Variant variable, the function returns the number
of bytes occupied by that data element.

When used with user-defined data types, the function returns the combined size
of each member within the structure. Since variable-length strings are stored
elsewhere, the size of each variable-length string within a structure is 2 bytes.

The following table describes the sizes of the individual data elements:

Table 3-53 Size of Data Types

Data element Size

Integer 2 bytes.

Long 4 bytes.

Float 4 bytes.

Double 8 bytes.

Currency 8 bytes.

String (variable-length) Number of characters in the string.

String (fixed-length) The length of the string as it appears in the string’s

declaration.

Objects 0 bytes. Both data object variables and variables of type

Object are always returned as 0 size.

3-308 Docbasic User’s Guide

A-Z Reference Len (function)

Table 3-53 Size of Data Types

Data element Size

User-defined type Combined size of each structure member.

Variable-length strings within structures require 2 bytes of
storage.
Arrays within structures are fixed in their dimensions. The
elements for fixed arrays are stored within the structure
and therefore require the number of bytes for each array
element multiplied by the size of each array dimension:
element_size*dimension1*dimension2...

The Len function always returns 0 with object variables or any data object variable.

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

Sub Main()
'This example shows the Len function used in a routine to change
'uppercase names to lowercase with an uppercase first letter.

lname$ = "WILLIAMS"
fl$ = Left$(lname$,1)
ln% = Len(lname$)
rest$ = Mid$(lname$,2,ln%)
lname$ = fl$ & LCase$(rest$)
MsgBox "The converted name is: " & lname$

'This example returns a table of lengths for standard numeric types.

Dim lns(4)
a% = 100 : b& = 200 : c! = 200.22 : d# = 300.22
lns(1) = Len(a%)
lns(2) = Len(b&)
lns(3) = Len(c!)
lns(4) = Len(d#)
msg = "Lengths of standard types:" & crlf
msg = msg & "Integer: " & lns(1) & crlf
msg = msg & "Long: " & lns(2) & crlf
msg = msg & "Single: " & lns(3) & crlf
msg = msg & "Double: " & lns(4) & crlf
MsgBox msg
End Sub

Platform(s)
All.

See Also
InStr (function)

Docbasic User’s Guide 3-309

Let (statement) A-Z Reference

Let (statement)

Assigns the result of an expression to a variable.

Syntax
[Let] variable = expression

Description
The use of the word Let is supported for compatibility with other implementations
of Docbasic. Normally, this word is dropped.

When assigning expressions to variables, internal type conversions are performed

automatically between any two numeric quantities. Thus, you can freely assign
numeric quantities without regard to type conversions. However, it is possible for
an overflow error to occur when converting from larger to smaller types. This
happens when the larger type contains a numeric quantity that cannot be
represented by the smaller type. For example, the following code will produce a
runtime error:
Dim amount As Long
Dim quantity As Integer

amount = 400123'Assign a value out of range for int.

quantity = amount'Attempt to assign to Integer.

When performing an automatic data conversion, underflow is not an error.

Example
Sub Main()
Let a$ = "This is a string."
Let b% = 100
Let c# = 1213.3443
End Sub

Platform(s)
All.

See Also
= (keyword)
Expression Evaluation (topic)

3-310 Docbasic User’s Guide

A-Z Reference Like (operator)

Like (operator)

Compares two strings and returns True if the expression matches the given pattern;
returns False otherwise.

Syntax
expression Like pattern

Description
Case sensitivity is controlled by the Option Compare setting.

The pattern can contain special characters that allow more flexible matching:

Table 3-54 Special Characters for Use with the Like Operator

Character Evaluates To

? Matches a single character.

* Matches one or more characters.

# Matches any digit.

[range] Matches if the character in question is within the specified range.

[!range] Matches if the character in question is not within the specified range.

A range specifies a grouping of characters. To specify a match of any of a group of

characters, use the syntax [ABCDE]. To specify a range of characters, use the syntax
[A-Z]. Special characters must appear within brackets, such as []*?#.

If expression or pattern is not a string, then both are converted to String variants and
compared, returning a Boolean variant. If either variant is Null, then Null is
returned.

The following table shows some examples:

Table 3-55 Like Operator Examples

expression True if pattern is False if pattern is

"EBW" "E*W", "E*" "E*B"

"Basic" "B*[r-t]ic" "B[r-t]ic"

"Version" "V[e]?s*n" "V[r]?s*N"

Docbasic User’s Guide 3-311

Like (operator) A-Z Reference

Table 3-55 Like Operator Examples

expression True if pattern is False if pattern is

"2.0" "#.#","#?#" "###","#?[!0-9]"

"[ABC]" "[[]*]" "[ABC]","[*]"

Example
This example demonstrates various uses of the Like function.
Sub Main()
a$ = "This is a string variable of 123456 characters"
b$ = "123.45"
If a$ Like "[A-Z][g-i]*" Then MsgBox "The first comparison is True."
If b$ Like "##3.##" Then MsgBox "The second comparison is True."
If a$ Like "*variable*" Then MsgBox "The third comparison is True."
End Sub

Platform(s)
All.

See Also
Operator Precedence (topic)
Is (operator)
Option Compare (statement)

3-312 Docbasic User’s Guide

A-Z Reference Line Input# (statement)

Line Input# (statement)

Reads an entire line into the given variable.

Syntax
Line Input [#]filenumber,variable

Description
The filenumber parameter is a number that is used by Docbasic to refer to the open
filethe number passed to the Open statement. The file number must reference a
file opened in Input mode.

The file is read up to the next end-of-line, but the end-of-line character(s) is (are)
not returned in the string. The file pointer is positioned after the terminating end-
of-line.

The variable parameter is any string or variant variable reference. This statement
will automatically declare the variable if the specified variable has not yet been
used or dimensioned.

This statement recognizes either a single line feed or a carriage-return/line-feed

pair as the end-of-line delimiter.

Example
This example reads five lines of the autoexec.bat file and displays them in a dialog
box.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
Open "c:\autoexec.bat" For Input As #1
For x = 1 To 5
Line Input #1,lin$
msg = msg & lin$ & crlf
Next x
MsgBox "The first 5 lines of your autoexec.bat are:" & crlf & Msg
End Sub

Platform(s)
All.

Docbasic User’s Guide 3-313

Line Input# (statement) A-Z Reference

See Also
Open (statement)
Get (statement)
Input# (statement)
Input, Input$ (functions)

3-314 Docbasic User’s Guide

A-Z Reference Line Numbers (topic)

Line Numbers (topic)

Line numbers are not supported by Docbasic.

As an alternative to line numbers, you can use meaningful labels as targets for
absolute jumps, as shown below:
Sub Main()
Dim i As Integer
On Error Goto MyErrorTrap

i = 0
LoopTop:
i = i + 1
If i < 10 Then Goto LoopTop

MyErrorTrap:
MsgBox "An error occurred."

End Sub

Docbasic User’s Guide 3-315

Line$ (function) A-Z Reference

Line$ (function)

Returns a String containing a single line or a group of lines between first and last.

Syntax
Line$(text$,first[,last])

Description
Lines are delimited by carriage return, line feed, or carriage-return/line-feed pairs.

The Line$ function takes the following parameters:

text$ String containing the text from which the lines will be
extracted.

first Integer representing the index of the first line to return. If

last is omitted, then this line will be returned. If first is
greater than the number of lines in text$, then a zero-length
string is returned.

last Integer representing the index of the last line to return.

Example
This example reads five lines of the autoexec.bat file, extracts the third and fourth
lines with the Line$ function, and displays them in a dialog box.
Const crlf = Chr$(13) + Chr$(10)
Sub Main()
Open "c:\autoexec.bat" For Input As #1
For x = 1 To 5
Line Input #1,lin$
txt = txt & lin$ & crlf
Next x
lines$ = Line$(txt,3,4)
MsgBox lines$
End Sub

Platform(s)
All.

3-316 Docbasic User’s Guide

A-Z Reference Line$ (function)

See Also
Item$ (function)
ItemCount (function)
LineCount (function)
Word$ (function)
WordCount (function)

Docbasic User’s Guide 3-317

LineCount (function) A-Z Reference

LineCount (function)

Returns an Integer representing the number of lines in text$.

Syntax
LineCount(text$)

Description
Lines are delimited by carriage return, line feed, or both.

Example
This example reads the first ten lines of your autoexec.bat file, uses the LineCount
function to determine the number of lines, and then displays them in a message
box.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
x = 1
Open "c:\autoexec.bat" For Input As #1
While (x < 10) And Not EOF(1)
Line Input #1,lin$
txt = txt & lin$ & crlf
x = x + 1
Wend
lines! = LineCount(txt)
MsgBox "The number of lines in txt is: " & lines! & crlf & crlf & txt
End Sub

Platform(s)
All.

See Also
Item$ (function)
ItemCount (function)
Line$ (function)
Word$ (function)
WordCount (function)

3-318 Docbasic User’s Guide

A-Z Reference Literals (topic)

Literals (topic)

Literals are values of a specific type. The following table shows the different types
of literals supported by Docbasic:

Table 3-56 Types of Literals

Literal Description

10 Integer whose value is 10.

43265 Long whose value is 43,265.

5# Double whose value is 5.0. A number's type can be explicitly set using any
of the following type-declaration characters:

% Integer

& Long

# Double

! Single

5.5 Double whose value is 5.5. Any number with decimal point is considered
a double.

5.4E100 Double expressed in scientific notation.

&HFF Integer expressed in hexadecimal.

&O47 Integer expressed in octal.

&HFF# Double expressed in hexadecimal.

"hello" String of five characters: hello.

"""hello""" String of seven characters: "hello". Quotation marks can be embedded

within strings by using two consecutive quotation marks.

#1/1/1994# Date value whose internal representation is 34335.0. Any valid date can
appear with #'s. Date literals are interpreted at execution time using the
locale settings of the host environment. To ensure that date literals are
correctly interpreted for all locales, use the international date format:

#YYYY-MM-DD HH:MM:SS#

Docbasic User’s Guide 3-319

Literals (topic) A-Z Reference

Constant Folding
Docbasic supports constant folding where constant expressions are calculated by
the compiler at compile time. For example, the expression
i% = 10 + 12

is the same as:

i% = 22

Similarly, with strings, the expression

s$ = "Hello," + " there" + Chr(46)

is the same as:

s$ = "Hello, there."

3-320 Docbasic User’s Guide

A-Z Reference Loc (function)

Loc (function)

Returns a Long representing the position of the file pointer in the given file.

Syntax
Loc(filenumber)

Description
The filenumber parameter is an Integer used by Docbasic to refer to the number
passed by the Open statement to Docbasic.

The Loc function returns different values depending on the mode in which the file
was opened:

Table 3-57 Effect of File Open Mode on the Loc Function

File Mode Returns

Input Current byte position divided by 128

Output Current byte position divided by 128

Append Current byte position divided by 128

Binary Position of the last byte read or written

Random Number of the last record read or written

Example
This example reads 5 lines of the autoexec.bat file, determines the current location
of the file pointer, and displays it in a dialog box.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
Open "c:\autoexec.bat" For Input As #1
For x = 1 To 5
If Not EOF(1) Then Line Input #1,lin$
Next x
lc% = Loc(1)
Close
MsgBox "The file location is: " & lc%
End Sub

Docbasic User’s Guide 3-321

Loc (function) A-Z Reference

Platform(s)
All.

See Also
Seek (function)
Seek (statement)
FileLen (function)

3-322 Docbasic User’s Guide

A-Z Reference Lock (statement)

Lock (statement)

Locks a section of the specified file, preventing other processes from accessing that
section of the file until the Unlock statement is issued.

Syntax
Lock [#] filenumber [,{record | [start] To end}]

Description
The Lock statement requires the following parameters:

filenumber Integer used by Docbasic to refer to the open file—the

number passed to the Open statement.

record Long specifying which record to lock.

start Long specifying the first record within a range to be locked.

end Long specifying the last record within a range to be locked.

For sequential files, the record, start, and end parameters are ignored. The entire file
is locked.

The section of the file is specified using one of the following:

Table 3-58 How to Use Parameters of the Lock Statement

Syntax Description

No parameters Locks the entire file (no record specification is given).

record Locks the specified record number (for Random files) or byte (for Binary
files).

to end Locks from the beginning of the file to the specified record (for Random
files) or byte (for Binary files).

start to end Locks the specified range of records (for Random files) or bytes (for Binary
files).

The lock range must be the same as that used to subsequently unlock the file range,
and all locked ranges must be unlocked before the file is closed. Ranges within files
are not unlocked automatically by Docbasic when your procedure terminates,
which can cause file access problems for other processes. It is a good idea to group
the Lock and Unlock statements close together in the code, both for readability and

Docbasic User’s Guide 3-323

Lock (statement) A-Z Reference

so subsequent readers can see that the lock and unlock are performed on the same
range. This practice also reduces errors in file locks.

Example
This example creates test.dat and fills it with ten string variable records. These are
displayed in a dialog box. The file is then reopened for read/write, and each record
is locked, modified, rewritten, and unlocked. The new records are then displayed
in a dialog box.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
a$ = "This is record number: "
b$ = "0"
rec$ = ""

msg = ""
Open "test.dat" For Random Access Write Shared As #1
For x = 1 To 10
rec$ = a$ & x
Lock #1,x
Put #1,,rec$
Unlock #1,x
msg = msg & rec$ & crlf
Next x
Close
MsgBox "The records are:" & crlf & msg

msg = ""
Open "test.dat" For Random Access Read Write Shared As #1
For x = 1 To 10
rec$ = Mid$(rec$,1,23) & (11 - x)
Lock #1,x
Put #1,x,rec$
Unlock #1,x
msg = msg & rec$ & crlf
Next x
MsgBox "The records are: " & crlf & msg
Close

Kill "test.dat"
End Sub

Platform(s)
All.

See Also
Unlock (statement)
Open (statement)

3-324 Docbasic User’s Guide

A-Z Reference Lof (function)

Lof (function)

Returns a Long representing the number of bytes in the given file.

Syntax
Lof(filenumber)

Description
The filenumber parameter is an Integer used by Docbasic to refer to the open
filethe number passed to the Open statement.

This example creates a test file, writes ten records into it, then finds the length of
the file and displays it in a message box.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
a$ = "This is record number: "

Open "test.dat" For Random Access Write Shared As #1

For x = 1 To 10
rec$ = a$ & x
put #1,,rec$
msg = msg & rec$ & crlf
Next x
Close

Open "test.dat" For Random Access Read Write Shared As #1

r% = Lof(1)
Close
MsgBox "The length of test.dat is: " & r%
End Sub

Platform(s)
All.

See Also
Loc (function)
Open (statement)
FileLen (function)

Docbasic User’s Guide 3-325

Log (function) A-Z Reference

Log (function)

Returns a Double representing the natural logarithm of a given number.

Syntax
Log(number)

Description
The value of number must be a Double greater than 0.

The value of e is 2.71828.

Example
This example calculates the natural log of 100 and displays it in a message box.
Sub Main()
x# = Log(100)
MsgBox "The natural logarithm of 100 is: " & x#
End Sub

Platform(s)
All.

See Also
Exp (function)

3-326 Docbasic User’s Guide

A-Z Reference Long (data type)

Long (data type)

Syntax
Long

Description
Long variables are used to hold numbers (with up to ten digits of precision) within
the following range:

-2,147,483,648 <= Long <= 2,147,483,647

Internally, longs are 4-byte values. Thus, when appearing within a structure, longs
require 4 bytes of storage. When used with binary or random files, 4 bytes of
storage are required.

The type-declaration character for Long is &.

Platform(s)
All.

See Also
Currency (data type)
Date (data type)
Double (data type)
Integer (data type)
Object (data type)
Single (data type)
String (data type)
Variant (data type)
Boolean (data type)
DefType (statement)
CLng (function)

Docbasic User’s Guide 3-327

LSet (statement) A-Z Reference

LSet (statement)

Left-aligns the source string in the destination string or copies one user-defined
type to another.

Syntax 1
LSet dest = source

Syntax 2
LSet dest_variable = source_variable

Description

Syntax 1

The LSet statement copies the source string source into the destination string dest.
The dest parameter must be the name of either a String or Variant variable. The
source parameter is any expression convertible to a string.

If source is shorter than dest, then the string is left-aligned within dest, and the
remaining characters are padded with spaces. If source is longer than dest, then
source is truncated, copying only the leftmost number of characters that will fit in
dest.

The destvariable parameter specifies a String or Variant variable. If destvariable is a

Variant containing Empty, then no characters are copied. If destvariable is not
convertible to a String, then a runtime error occurs. A runtime error results if
destvariable is Null.

Syntax 2

The source structure is copied byte for byte into the destination structure. This is
useful for copying structures of different types. Only the number of bytes of the
smaller of the two structures is copied. Neither the source structure nor the
destination structure can contain strings.

Example
This example replaces a 40-character string of asterisks (*) with an RSet and LSet
string and then displays the result.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()

3-328 Docbasic User’s Guide

A-Z Reference LSet (statement)

Dim msg, tmpstr$

tmpstr$ = String$(40, "*")
msg = "Here are two strings that have been right-" + crlf
msg = msg & "and left-justified in a 40-character string."
msg = msg & crlf & crlf
RSet tmpstr$ = "Right->"
msg = msg & tmpstr$ & crlf
LSet tmpstr$ = "<-Left"
msg = msg & tmpstr$ & crlf
MsgBox msg
End Sub

Platform(s)
All.

See Also
RSet (statement)

Docbasic User’s Guide 3-329

LTrim, LTrim$ (functions) A-Z Reference

LTrim, LTrim$ (functions)

Returns text with the leading spaces removed.

Syntax
LTrim[$](text)

Description
LTrim$ returns a String, whereas LTrim returns a String variant.

Null is returned if text is Null.

Example
This example displays a right-justified string and its LTrim result.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
a$ = " <= This is a right-justified string"
b$ = LTrim$(a$)
MsgBox a$ & crlf & b$
End Sub

Platform(s)
All.

See Also
RTrim, RTrim$ (functions)
Trim, Trim$ (functions)

3-330 Docbasic User’s Guide

A-Z Reference MacID (function)

MacID (function)

Returns a value representing a collection of same-type files on the Macintosh.

Syntax
MacID(text$)

Description
Since this platform does not support wildcards (i.e., * or ?), this function is the only
way to specify a group of files. This function can only be used with the following
statements:

Dir$
Kill
Shell

The text$ parameter is a four-character string containing a file type, a resource type,
an application signature, or an Apple event. A runtime error occurs if the MacID
function is used on platforms other than the Macintosh.

Example
This example retrieves the names of all the text files.
Sub Main()
s$ = Dir$(MacID("TEXT"))'Get the first text file.
While s$ <> ""
MsgBox s$ 'Display it.
s$ = Dir$ 'Get the next text file in the list.
Wend

'Delete all the text files.

Kill MacID("TEXT")
End Sub

Platform(s)
Macintosh.

See Also
Kill (statement)
Dir, Dir$ (functions)
Shell (function)

Docbasic User’s Guide 3-331

MacScript (statement) A-Z Reference

MacScript (statement)

Executes the specified AppleScript script.

Syntax
MacScript script$

Description
When using the MacScript statement, you can separate multiple lines by
embedding carriage returns:
MacScript "Beep" + Chr(13) + "Display Dialog ""Hello"""

If embedding carriage returns proves cumbersome, you can use the Inline
statement. The following Inline statement is equivalent to the above example:
Inline MacScript
Beep
Display Dialog "Hello"
End Inline

Example
Sub Main()
MacScript "display dialog ""AppleScript"""
End Sub

Platform(s)
Macintosh.

Platform Notes: Macintosh

Requires Macintosh System 7.0 or later.

See Also
Inline (statement)

3-332 Docbasic User’s Guide

A-Z Reference Main (statement)

Main (statement)

Defines the subroutine where execution begins.

Syntax
Sub Main()
End Sub

Example
Sub Main()
MsgBox "This is the Main() subroutine and entry point."
End Sub

Platform(s)
All.

Docbasic User’s Guide 3-333

Mci (function) A-Z Reference

Mci (function)

Executes an Mci command, returning an Integer indicating whether the command

was successful.

Syntax
Mci(command$,result$ [,error$])

Description
The Mci function takes the following parameters:

command$ String containing the command to be executed.

result$ String variable into which the result is placed. If the

command doesn't return anything, then a zero-length
string is returned.

To ignore the returned string, pass a zero-length string:

r% = Mci("open chimes.wav type waveaudio","")

error$ Optional String variable into which an error string will be

placed. A zero-length string will be returned if the function
is successful.

Example
This first example plays a wave file. The wave file is played to completion before
execution can continue.
Sub Main()
Dim result As String
Dim ErrorMessage As String
Dim Filename As String
Dim rc As Integer

'Establish name of file in the Windows directory.

Filename = FileParse$("c:\windows\system\chimes.wav")

'Open the file and driver.

rc = Mci("open " & Filename & " type waveaudio alias
CoolSound","",ErrorMessage)
If (rc) Then
'Error occurred--display error message to user.
MsgBox ErrorMessage
Exit Sub

3-334 Docbasic User’s Guide

A-Z Reference Mci (function)

End If

rc = Mci("play CoolSound wait","","")'Wait for sound to finish.

rc = Mci("close CoolSound","","")'Close driver and file.
End Sub

Example
This next example shows how to query an Mci device and play an MIDI file in
the background.
Sub Main()
Dim result As String
Dim ErrMsg As String
Dim Filename As String
Dim rc As Integer

'Check to see whether MIDI device can play for us.

rc = Mci("capability sequencer can play",result,ErrorMessage)

'Check for error.

If rc Then
MsgBox ErrorMessage
Exit Sub
End If

'Can it play?
If result <> "true" Then
MsgBox "MIDI device is not capable of playing."
Exit Sub
End If

'Assemble a filename from the Windows directory.

Filename = FileParse$(System.WindowsDirectory$ & "\" & "canyon.mid")

'Open the driver and file.

rc = Mci("open " & Filename & " type sequencer alias song",result$,ErrMsg)
If rc Then
MsgBox ErrMsg
Exit Sub
End If

rc = Mci("play song","","")'Play in the background.

MsgBox "Press OK to stop the music.",ebOKOnly
rc = Mci("close song","","")
End Sub

Platform(s)
Windows.

Platform Notes: Windows

The Mci function accepts any Mci command as defined in the Multimedia
Programmers Reference in the Windows 3.1 SDK.

Docbasic User’s Guide 3-335

Mci (function) A-Z Reference

See Also
Beep (statement)

3-336 Docbasic User’s Guide

A-Z Reference Mid, Mid$ (functions)

Mid, Mid$ (functions)

Returns a substring of the specified string, beginning with start, for length
characters.

Syntax
Mid[$](text,start [,length])

Description
The returned substring starts at character position start and will be length
characters long.

Mid$ returns a String, whereas Mid returns a String variant.

The Mid/Mid$ functions take the following parameters:

text Any String expression containing the text from which

characters are returned.

start Integer specifying the character position where the

substring begins. If start is greater than the length of text$,
then a zero-length string is returned.

length Integer specifying the number of characters to return. If

this parameter is omitted, then the entire string is returned,
starting at start.

The Mid function will return Null if text$ is Null.

Example
This example displays a substring from the middle of a string variable using the
Mid$ function and replaces the first four characters with "NEW " using the Mid$
statement.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
a$ = "This is the Main string containing text."
b$ = Mid$(a$,13,Len(a$))
Mid$ (b$,1)= "NEW "
MsgBox a$ & crlf & b$
End Sub

Docbasic User’s Guide 3-337

Mid, Mid$ (functions) A-Z Reference

Platform(s)
All.

See Also
InStr (function)
Option Compare (statement)
Mid, Mid$ (statements)

3-338 Docbasic User’s Guide

A-Z Reference Mid, Mid$ (statements)

Mid, Mid$ (statements)

Replaces one part of a string with another.

Syntax
Mid[$](variable,start[,length]) = newvalue

Description
The Mid/Mid$ statements take the following parameters:

variable String or Variant variable to be changed.

start Integer specifying the character position within variable

where replacement begins. If start is greater than the length
of variable, then variable remains unchanged.

length Integer specifying the number of characters to change. If

this parameter is omitted, then the entire string is changed,
starting at start.

newvalue Expression used as the replacement. This expression must

be convertible to a String.

The resultant string is never longer than the original length of variable.

With Mid, variable must be a Variant variable convertible to a String, and newvalue
is any expression convertible to a string. A runtime error is generated if either
variant is Null.

Example
This example displays a substring from the middle of a string variable using the
Mid$ function, replacing the first four characters with "NEW " using the Mid$
statement.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
a$ = "This is the Main string containing text."
b$ = Mid$(a$,13,Len(a$))
Mid$(b$,1) = "NEW "
MsgBox a$ & crlf & b$
End Sub

Docbasic User’s Guide 3-339

Mid, Mid$ (statements) A-Z Reference

Platform(s)
All.

See Also
Mid, Mid$ (functions)
Option Compare (statement)

3-340 Docbasic User’s Guide

A-Z Reference Minute (function)

Minute (function)

Returns the minute of the day encoded in the time parameter.

Syntax
Minute(time)

Description
The value returned is as an Integer between 0 and 59 inclusive.

The time parameter is any expression that converts to a Date.

Example
This example takes the current time; extracts the hour, minute, and second; and
displays them as the current time.
Sub Main()
xt# = TimeValue(Time$())
xh# = Hour(xt#)
xm# = Minute(xt#)
xs# = Second(xt#)
MsgBox "The current time is: " & xh# & ":" & xm# & ":" & xs#
End Sub

Platform(s)
All.

See Also
Day (function)
Second (function)
Month (function)
Year (function)
Hour (function)
Weekday (function)
DatePart (function)

Docbasic User’s Guide 3-341

MIRR (function) A-Z Reference

MIRR (function)

Returns a Double representing the modified internal rate of return for a series of
periodic payments and receipts.

Syntax
MIRR(ValueArray(),FinanceRate,ReinvestRate)

Description
The modified internal rate of return is the equivalent rate of return on an
investment in which payments and receipts are financed at different rates. The
interest cost of investment and the rate of interest received on the returns on
investment are both factors in the calculations.

The MIRR function requires the following parameters:

ValueArray() Array of Double numbers representing the payments and

receipts. Positive values are payments (invested capital),
and negative values are receipts (returns on investment).

There must be at least one positive (investment) value and

one negative (return) value.

FinanceRate Double representing the interest rate paid on invested

monies (paid out).

ReinvestRate Double representing the rate of interest received on

incomes from the investment (receipts).

FinanceRate and ReinvestRate should be expressed as percentages. For example, 11

percent should be expressed as 0.11.

To return the correct value, be sure to order your payments and receipts in the
correct sequence.

Example
This example illustrates the purchase of a lemonade stand for $800 financed with
money borrowed at 10%. The returns are estimated to accelerate as the stand gains
popularity. The proceeds are placed in a bank at 9 percent interest. The incomes are
estimated (generated) over 12 months. This program first generates the income
stream array in two For...Next loops, and then the modified internal rate of return

3-342 Docbasic User’s Guide

A-Z Reference MIRR (function)

is calculated and displayed. Notice that the annual rates are normalized to
monthly rates by dividing them by 12.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
Dim valu#(12)
valu(1) = -800 'Initial investment
msg = valu(1) & ", "
For x = 2 To 5
valu(x) = 100 + (x * 2)'Incomes months 2-5
msg = msg & valu(x) & ", "
Next x
For x = 6 To 12
valu(x) = 100 + (x * 10)'Incomes months 6-12
msg = msg & valu(x) & ", "
Next x
retrn# = MIRR(valu,.1/12,.09/12)'Note: normalized annual rates

msg = "The values: " & crlf & msg & crlf & crlf
MsgBox msg & "Modified rate: " & Format(retrn#,"Percent")
End Sub

Platform(s)
All.

See Also
Fv (function)
IRR (function)
Npv (function)
Pv (function)

Docbasic User’s Guide 3-343

MkDir (statement) A-Z Reference

MkDir (statement)

Creates a new directory as specified by dir$.

Syntax
MkDir dir$

Example
This example creates a new directory on the default drive. If this causes an error,
then the error is displayed and the program 'terminates. If no error is generated,
the directory is removed with 'the RmDir statement.
Sub Main()
On Error Resume Next
MkDir "TestDir"
If Err <> 0 Then
MsgBox "The following error occurred: " & Error(Err)
Else
MsgBox "Directory was created and is about to be removed."
RmDir "TestDir"
End If
End Sub

Platform(s)
All.

See Also
ChDir (statement)
ChDrive (statement)
CurDir, CurDir$ (functions)
Dir, Dir$ (functions)
RmDir (statement)

3-344 Docbasic User’s Guide

A-Z Reference Mod (operator)

Mod (operator)

Returns the remainder of expression1 / expression2 as a whole number.

Syntax
expression1 Mod expression2

Description
If both expressions are integers, then the result is an integer. Otherwise, each
expression is converted to a Long before performing the operation, returning a
Long.

A runtime error occurs if the result overflows the range of a Long.

If either expression is Null, then Null is returned. Empty is treated as 0.

Example
This example uses the Mod operator to determine the value of a randomly selected
card where card 1 is the ace (1) of clubs and card 52 is the king (13) of spades. Since
the values recur in a sequence of 13 cards within 4 suits, we can use the Mod
function to determine the value of any given card number.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
cval$ =
"ACE,TWO,THREE,FOUR,FIVE,SIX,SEVEN,EIGHT,NINE,TEN,JACK,QUEEN,KING"
Randomize
card% = Random(1,52)
value = card% Mod 13
If value = 0 Then value = 13
CardNum$ = Item$(cval,value)
If card% < 53 Then suit$ = "spades"
If card% < 40 Then suit$ = "hearts"
If card% < 27 Then suit$ = "diamonds"
If card% < 14 Then suit$ = "clubs"
msg = "Card number " & card% & " is the "
msg = msg & CardNum & " of " & suit$
MsgBox msg
End Sub

Platform(s)
All.

Docbasic User’s Guide 3-345

Mod (operator) A-Z Reference

See Also
/ (operator)
\ (operator)

3-346 Docbasic User’s Guide

A-Z Reference Month (function)

Month (function)

Returns the month of the date encoded in the date parameter.

Syntax
Month(date)

Description
The value returned is as an Integer between 1 and 12 inclusive.

The date parameter is any expression that converts to a Date.

Example
This example returns the current month in a dialog box.
Sub Main()
mons$ = "Jan., Feb., Mar., Apr., May, Jun., Jul., Aug., Sep., Oct., Nov.,
Dec."
tdate$ = Date$
tmonth! = Month(DateValue(tdate$))
MsgBox "The current month is: " & Item$(mons$,tmonth!)
End Sub

Platform(s)
All.

See Also
Day (function)
Minute (function)
Second (function)
Year (function)
Hour (function)
Weekday (function)
DatePart (function)

Docbasic User’s Guide 3-347

MsgBox (function) A-Z Reference

MsgBox (function)

Displays a message in a dialog box with a set of predefined buttons, returning an

Integer representing which button was selected.

Syntax
MsgBox(msg)

Description
The MsgBox function takes the following parameters:

msg Message to be displayed—any expression convertible to a

String.

End-of-lines can be used to separate lines (either a carriage

return, line feed, or both). If a given line is too long, it will
be word-wrapped. If msg contains character 0, then only
the characters up to the character 0 will be displayed.

The width and height of the dialog box are sized to hold
the entire contents of msg.

A runtime error is generated if msg is Null.

Breaking Text across Lines

The msg parameter can contain end-of-line characters, forcing the text that follows
to start on a new line. The following example shows how to display a string on two
lines:
MsgBox "This is on" + Chr(13) + Chr(10) + "two lines."

The carriage-return or line-feed characters can be used by themselves to designate

an end-of-line.

Example
This example displays a message.

3-348 Docbasic User’s Guide

A-Z Reference MsgBox (function)

r = MsgBox("Hello, World")

Platform(s)
Windows, Win32, Macintosh.

Platform Notes:
The appearance of the MsgBox dialog box and its icons differs slightly depending
on the platform.

Platform Notes: Windows, Win32

MsgBox displays all text in its dialog box in 8-point MS Sans Serif.

See Also
MsgBox (statement)

Docbasic User’s Guide 3-349

MsgBox (statement) A-Z Reference

MsgBox (statement)

This command is the same as the MsgBox function, except that the statement form
does not return a value. See MsgBox (function).

Syntax
MsgBox msg

Example
Sub Main()
MsgBox "This is text displayed in a message box."'Display text.
MsgBox "The result is: " & (10 * 45)'Display a number.
End Sub

Platform(s)
Windows, Win32, Macintosh.

See Also
MsgBox (function)

3-350 Docbasic User’s Guide

A-Z Reference Name (statement)

Name (statement)

Renames a file.

Syntax
Name oldfile$ As newfile$

Description
Each parameter must specify a single filename. Wildcard characters such as * and
? are not allowed.

Some platforms allow naming of files to different directories on the same physical
disk volume. For example, the following rename will work under Windows:
Name "c:\samples\mydoc.txt" As "c:\backup\doc\mydoc.bak"

You cannot rename files across physical disk volumes. For example, the following
will error under Windows:
Name "c:\samples\mydoc.txt" As "a:\mydoc.bak"'This will error!

To rename a file to a different physical disk, you must first copy the file, then erase
the original:
FileCopy "c:\samples\mydoc.txt","a:\mydoc.bak"'Make a copy
Kill "c:\samples\mydoc.txt"'Delete the original

Example
This example creates a file called test.dat and then renames it to test2.dat.
Sub Main()
On Error Resume Next
If FileExists("test.dat") Then
Name "test.dat" As "test2.dat"
If Err <> 0 Then
msg = "File exists and cannot be renamed! Error: " & Err
Else
msg = "File exists and renamed to test2.dat."
End If
Else
Open "test.dat" For Output As #1
Close
Name "test.dat" As "test2.dat"
If Err <> 0 Then
msg = "File created but not renamed! Error: " & Err
Else
msg = "File created and renamed to test2.dat."
End If

Docbasic User’s Guide 3-351

Name (statement) A-Z Reference

End If
MsgBox msg
End Sub

Platform(s)
All.

See Also
Kill (statement)
FileCopy (statement)

3-352 Docbasic User’s Guide

A-Z Reference New (keyword)

New (keyword)

Creates a new instance of the specified object type, assigning it to the specified
object variable.

Syntax 1
Dim ObjectVariable As New ObjectType

Syntax 2
Set ObjectVariable = New ObjectType

Description
The New keyword is used to declare a new instance of the specified data object.
This keyword can only be used with data object types.

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

When that variable goes out of scope (i.e., the Sub or Function procedure in which
the variable is declared ends), the application is notified. The application then
performs some appropriate action, such as destroying the physical object.

Platform(s)
All.

See Also
Dim (statement)
Set (statement)

Docbasic User’s Guide 3-353

Not (operator) A-Z Reference

Not (operator)

Returns either a logical or binary negation of expression.

Syntax
Not expression

Description
The result is determined as shown in the following table:

Table 3-59 Effect of Expression Parameter on the Not Operator

If the Expression Is Then the Result is

True False

False True

Null Null

Any numeric type A binary negation of the number. If the number is an

Integer, then an Integer is returned. Otherwise, the
expression is first converted to a Long, then a binary
negation is performed, returning a Long.

Empty Treated as a Long value 0.

Example
This example demonstrates the use of the Not operator in comparing logical
expressions and for switching a True/False toggle variable.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
a = False
b = True
If (Not a and b) Then msg = "a = False, b = True" & crlf

toggle% = True
msg = msg & "toggle% is now " & Format(toggle%,"True/False") & crlf
toggle% = Not toggle%
msg = msg & "toggle% is now " & Format(toggle%,"True/False") & crlf
toggle% = Not toggle%
msg = msg & "toggle% is now " & Format(toggle%,"True/False")
MsgBox msg
End Sub

3-354 Docbasic User’s Guide

A-Z Reference Not (operator)

Platform(s)
All.

See Also
Boolean (data type)
Comparison Operators (topic)

Docbasic User’s Guide 3-355

Nothing (constant) A-Z Reference

Nothing (constant)

A value indicating that an object variable no longer references a valid object.

Syntax
Nothing

Example
Sub Main()
Dim a As Object
If a Is Nothing Then
MsgBox "The object variable references no object."
Else
MsgBox "The object variable references: " & a.Value
End If
End Sub

Platform(s)
All.

See Also
Set (statement)
Object (data type)

3-356 Docbasic User’s Guide

A-Z Reference Now (function)

Now (function)

Returns a Date variant representing the current date and time.

Syntax
Now[()]

Example
This example shows how the Now function can be used as an elapsed-time
counter.
Sub Main()
t1# = Now()
MsgBox "Wait a while and click OK."
t2# = Now()
t3# = Second(t2#) - Second(t1#)
MsgBox "Elapsed time was: " & t3# & " seconds."
End Sub

Platform(s)
All.

See Also
Date, Date$ (functions)
Time, Time$ (functions)

Docbasic User’s Guide 3-357

NPer (function) A-Z Reference

NPer (function)

Returns the number of periods for an annuity based on periodic fixed payments
and a constant rate of interest.

Syntax
NPer(Rate,Pmt,Pv,Fv,Due)

Description
An annuity is a series of fixed payments paid to or received from an investment
over a period of time. Examples of annuities are mortgages, retirement plans,
monthly savings plans, and term loans.

The NPer function requires the following parameters:

Rate Double representing the interest rate per period. If the

periods are monthly, be sure to normalize annual rates by
dividing them by 12.

Pmt Double representing the amount of each payment or

income. Income is represented by positive values, whereas
payments are represented by negative values.

Pv Double representing the present value of your annuity. In

the case of a loan, the present value would be the amount
of the loan, and the future value (see below) would be zero.

Fv Double representing the future value of your annuity. In

the case of a loan, the future value would be zero, and the
present value would be the amount of the loan.

Due Integer indicating when payments are due for each

payment period. A 0 specifies payment at the end of each
period, whereas a 1 indicates payment at the start of each
period.

Positive numbers represent cash received, whereas negative numbers represent

cash paid out.

3-358 Docbasic User’s Guide

A-Z Reference NPer (function)

Example
This example calculates the number of $100.00 monthly payments necessary to
accumulate $10,000.00 at an annual rate of 10%. Payments are made at the
beginning of the month.
Sub Main()
ag# = NPer((.10/12),100,0,10000,1)
MsgBox "The number of monthly periods is: " & Format(ag#,"Standard")
End Sub

Platform(s)
All.

See Also
IPmt (function)
Pmt (function)
PPmt (function)
Rate (function)

Docbasic User’s Guide 3-359

Npv (function) A-Z Reference

Npv (function)

Returns the net present value of an annuity based on periodic payments and
receipts, and a discount rate.

Syntax
Npv(Rate,ValueArray())

Description
The Npv function requires the following parameters:

Rate Double that represents the interest rate over the length of
the period. If the values are monthly, annual rates must be
divided by 12 to normalize them to monthly rates.

ValueArray() Array of Double numbers representing the payments and

receipts. Positive values are payments, and negative values
are receipts.

There must be at least one positive and one negative value.

Positive numbers represent cash received, whereas negative numbers represent

cash paid out.

For accurate results, be sure to enter your payments and receipts in the correct
order because Npv uses the order of the array values to interpret the order of the
payments and receipts.

If your first cash flow occurs at the beginning of the first period, that value must
be added to the return value of the Npv function. It should not be included in the
array of cash flows.

Npv differs from the Pv function in that the payments are due at the end of the
period and the cash flows are variable. Pv's cash flows are constant, and payment
may be made at either the beginning or end of the period.

Example
This example illustrates the purchase of a lemonade stand for $800 financed with
money borrowed at 10%. The returns are estimated to accelerate as the stand gains
popularity. The incomes are estimated (generated) over 12 months. This program
first generates the income stream array in two For...Next loops, and then the net

3-360 Docbasic User’s Guide

A-Z Reference Npv (function)

present value (Npv) is calculated and displayed. Note normalization of the annual
10% rate.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
Dim valu#(12)
valu(1) = -800 'Initial investment
msg = valu(1) & ", "
For x = 2 To 5 'Months 2-5
valu(x) = 100 + (x * 2)
msg = msg & valu(x) & ", "
Next x
For x = 6 To 12 'Months 6-12
valu(x) = 100 + (x * 10)'Accelerated income
msg = msg & valu(x) & ", "
Next x
NetVal# = NPV((.10/12),valu)
msg = "The values:" & crlf & msg & crlf & crlf
MsgBox msg & "Net present value: " & Format(NetVal#,"Currency")
End Sub

Platform(s)
All.

See Also
Fv (function)
IRR (function)
MIRR (function)
Pv (function)

Docbasic User’s Guide 3-361

Null (constant) A-Z Reference

Null (constant)

Represents a variant of VarType 1.

Syntax
Null

Description
The Null value has special meaning indicating that a variable contains no data.

Most numeric operators return Null when either of the arguments is Null. This
"propagation" of Null makes it especially useful for returning error values through
a complex expression. For example, you can write functions that return Null when
an error occurs, then call this function within an expression. You can then use the
IsNull function to test the final result to see whether an error occurred during
calculation.

Since variants are Empty by default, the only way for Null to appear within a
variant is for you to explicitly place it there. Only a few Docbasic functions return
this value.

Example
Sub Main()
Dim a As Variant
a = Null
If IsNull(a) Then MsgBox "The variable is Null."
MsgBox "The VarType of a is: " & VarType(a)'Should display 1.
End Sub

Platform(s)
All.

3-362 Docbasic User’s Guide

A-Z Reference Object (data type)

Object (data type)

A data type used to declare OLE automation variables.

Syntax
Object

Description
The Object type is used to declare variables that reference objects within an
application using OLE automation.

Each object is a 4-byte (32-bit) value that references the object internally. The value
0 (or Nothing) indicates that the variable does not reference a valid object, as is the
case when the object has not yet been given a value. Accessing properties or
methods of such Object variables generates a runtime error.

Using Objects

Object variables are declared using the Dim, Public, or Private statement:
Dim MyApp As Object

Object variables can be assigned values (thereby referencing a real physical object)
using the Set statement:
Set MyApp = CreateObject("phantom.application")
Set MyApp = Nothing

Properties of an Object are accessed using the dot (.) separator:

MyApp.Color = 10
i% = MyApp.Color

Methods of an Object are also accessed using the dot (.) separator:
MyApp.Open "sample.txt"
isSuccess = MyApp.Save("new.txt",15)

Automatic Destruction

Docbasic keeps track of the number of variables that reference a given object so that
the object can be destroyed when there are no longer any references to it:
Sub Main() 'Number of references to object
Dim a As Object '0
Dim b As Object '0
Set a = CreateObject("phantom.application)'1
Set b = a '2

Docbasic User’s Guide 3-363

Object (data type) A-Z Reference

Set a = Nothing '1

End Sub '0 (object destroyed)

Note: An OLE automation object is instructed by Docbasic to destroy itself when

no variables reference that object. However, it is the responsibility of the OLE
automation server to destroy it. Some servers do not destroy their objects—usually
when the objects have a visual component and can be destroyed manually by the
user.

Platform(s)
Windows, Win32, Macintosh.

See Also
Boolean (data type)
Currency (data type)
Date (data type)
Double (data type)
Integer (data type)
Long (data type)
Single (data type)
String (data type)
Variant (data type)
DefType (statement)

3-364 Docbasic User’s Guide

A-Z Reference Objects (topic)

Objects (topic)

Docbasic defines two types of objects: data objects and OLE automation objects.

Syntactically, these are referenced in the same way.

What Is an Object
An object in Docbasic is an encapsulation of data and routines into a single unit.
The use of objects in Docbasic has the effect of grouping together a set of functions
and data items that apply only to a specific object type.

Objects expose data items for programmability called properties. For example, a
sheet object may expose an integer called NumColumns. Usually, properties can be
both retrieved (get) and modified (set).

Objects also expose internal routines for programmability called methods. In

Docbasic, an object method can take the form of a function or a subroutine. For
example, a OLE automation object called MyApp may contain a method
subroutine called Open that takes a single argument (a filename), as shown below:
MyApp.Open "c:\files\sample.txt"

Declaring Object Variables

In order to gain access to an object, you must first declare an object variable using
either Dim, Public, or Private:
Dim o As Object'OLE automation object

Initially, objects are given the value 0 (or Nothing). Before an object can be
accessed, it must be associated with a physical object.

Assigning a Value to an Object Variable

An object variable must reference a real physical object before accessing any
properties or methods of that object. To instantiate an object, use the Set statement.
Dim MyApp As Object
Set MyApp = CreateObject("Server.Application")

Accessing Object Properties

Once an object variable has been declared and associated with a physical object, it
can be modified using Docbasic code. Properties are syntactically accessible using
the dot operator, which separates an object name from the property being accessed:
MyApp.BackgroundColor = 10

Docbasic User’s Guide 3-365

Objects (topic) A-Z Reference

i% = MyApp.DocumentCount

Properties are set using Docbasic's normal assignment statement:

MyApp.BackgroundColor = 10

Object properties can be retrieved and used within expressions:

i% = MyApp.DocumentCount + 10
MsgBox "Number of documents = " & MyApp.DocumentCount

Accessing Object Methods

Like properties, methods are accessed via the dot operator. Object methods that do
not return values behave like subroutines in Docbasic (i.e., the arguments are not
enclosed within parentheses):
MyApp.Open "c:\files\sample.txt",True,15

Object methods that return a value behave like function calls in Docbasic. Any
arguments must be enclosed in parentheses:
If MyApp.DocumentCount = 0 Then MsgBox "No open documents."
NumDocs = app.count(4,5)

There is no syntactic difference between calling a method function and retrieving

a property value, as shown below:
variable = object.property(arg1,arg2)
variable = object.method(arg1,arg2)

Comparing Object Variables

The values used to represent objects are meaningless to the procedure in which
they are used, with the following exceptions:

Objects can be compared to each other to determine whether they refer to the same
object.

Objects can be compared with Nothing to determine whether the object variable
refers to a valid object.

Object comparisons are accomplished using the Is operator:

If a Is b Then MsgBox "a and b are the same object."
If a Is Nothing Then MsgBox "a is not initialized."
If b Is Not Nothing Then MsgBox "b is in use."

Collections
A collection is a set of related object variables. Each element in the set is called a
member and is accessed via an index, either numeric or text, as shown below:

3-366 Docbasic User’s Guide

A-Z Reference Objects (topic)

MyApp.Toolbar.Buttons(0)
MyApp.Toolbar.Buttons("Tuesday")

It is typical for collection indexes to begin with 0.

Each element of a collection is itself an object, as shown in the following examples:

Dim MyToolbarButton As Object

Set MyToolbarButton = MyApp.Toolbar.Buttons("Save")

MyAppp.Toolbar.Buttons(1).Caption = "Open"

The collection itself contains properties that provide you with information about
the collection and methods that allow navigation within that collection:
Dim MyToolbarButton As Object

NumButtons% = MyApp.Toolbar.Buttons.Count
MyApp.Toolbar.Buttons.MoveNext
MyApp.Toolbar.Buttons.FindNext "Save"

For i = 1 To MyApp.Toolbar.Buttons.Count
Set MyToolbarButton = MyApp.Toolbar.Buttons(i)
MyToolbarButton.Caption = "Copy"
Next i

Predefined Objects
Docbasic predefines a few objects for use in all procedures. These are:

Clipboard

Basic

Note: Some of these objects are not available on all platforms.

Docbasic User’s Guide 3-367

Oct, Oct$ (functions) A-Z Reference

Oct, Oct$ (functions)

Returns a String containing the octal equivalent of the specified number.

Syntax
Oct[$](number)

Description
Oct$ returns a String, whereas Oct returns a String variant.

The returned string contains only the number of octal digits necessary to represent
the number.

The number parameter is any numeric expression. If this parameter is Null, then
Null is returned. Empty is treated as 0. The number parameter is rounded to the
nearest whole number before converting to the octal equivalent.

Example
This example displays the octal equivalent of several numbers.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
st$ = "The octal values are: " & crlf
For x = 1 To 5
y% = x * 10
st$ = st$ & y% & " : " & Oct$(y%) & crlf
Next x
MsgBox st$
End Sub

Platform(s)
All.

See Also
Hex, Hex$ (functions)

3-368 Docbasic User’s Guide

A-Z Reference On Error (statement)

On Error (statement)

Defines the action taken when a trappable runtime error occurs.

Syntax
On Error {Goto label | Resume Next | Goto 0}

Description
The form On Error Goto label causes execution to transfer to the specified label
when a runtime error occurs.

The form On Error Resume Next causes execution to continue on the line following
the line that caused the error.

The form On Error Goto 0 causes any existing error trap to be removed.

If an error trap is in effect when the procedure ends, then an error will be
generated.

An error trap is only active within the subroutine or function in which it appears.

Once an error trap has gained control, appropriate action should be taken, and
then control should be resumed using the Resume statement. The Resume
statement resets the error handler and continues execution. If a procedure ends
while an error is pending, then an error will be generated. (The Exit Sub or Exit
Function statement also resets the error handler, allowing a procedure to end
without displaying an error message.)

Errors within an Error Handler

If an error occurs within the error handler, then the error handler of the caller (or
any procedure in the call stack) will be invoked. If there is no such error handler,
then the error is fatal, causing the procedure to stop executing. The following
statements reset the error state (i.e., these statements turn off the fact that an error
occurred):
Resume
Err=-1

The Resume statement forces execution to continue either on the same line or on
the line following the line that generated the error. The Err=-1 statement allows
explicit resetting of the error state so that the procedure can continue normal
execution without resuming at the statement that caused the error condition.

Docbasic User’s Guide 3-369

On Error (statement) A-Z Reference

The On Error statement will not reset the error. Thus, if an On Error statement
occurs within an error handler, it has the effect of changing the location of a new
error handler for any new errors that may occur once the error has been reset.

Example
This example will demonstrate three types of error handling. The first case simply
by-passes an expected error and continues with program operation. The second
case creates an error branch that jumps to a common error handling routine that
processes incoming errors, clears the error (with the Resume statement) and
'resumes program execution. The third case clears all internal error 'handling so
that execution will stop when the next error is 'encountered.
Sub Main()
Dim x%
a = 10000
b = 10000

On Error Goto Pass'Branch to this label on error.

Do
x% = a * b
Loop

Pass:
Err = -1 'Clear error status.
MsgBox "Cleared error status and continued."

On Error Goto Overflow'Branch to new error routine on any

x% = 1000 'subsequent errors.
x% = a * b
x% = a / 0

On Error Goto 0'Clear error branching.

x% = a * b 'Program will stop here.
Exit Sub 'Exit before common error routine.

Overflow: 'Beginning of common error routine.

If Err = 6 then
MsgBox "Overflow Branch."
Else
MsgBox Error(Err)
End If

Resume Next
End Sub

Platform(s)
All.

3-370 Docbasic User’s Guide

A-Z Reference On Error (statement)

See Also
Error Handling (topic)
Error (statement)
Resume (statement)

Docbasic User’s Guide 3-371

Open (statement) A-Z Reference

Open (statement)

Opens a file.

Syntax
Open filename$ [For mode] [Access accessmode] [lock] As [#] filenumber _
[Len = reclen]

Description
The filename$ parameter is a string expression that contains a valid filename.

The filenumber parameter is a number between 1 and 255. The FreeFile function can
be used to determine an available file number.

The mode parameter determines the type of operations that can be performed on
that file:

Table 3-60 Effect of the Mode Parameter on File Operations

Mode Operations

Input Opens an existing file for sequential input (filename$ must exist). The value
of accessmode, if specified, must be Read.

Output Opens an existing file for sequential output, truncating its length to zero,
or creates a new file. The value of accessmode, if specified, must be Write.

Append Opens an existing file for sequential output, positioning the file pointer at
the end of the file, or creates a new file. The value of accessmode, if
specified, must be Read Write.

Binary Opens an existing file for binary I/O or creates a new file. Existing binary
files are never truncated in length. The value of accessmode, if specified,
determines how the file can subsequently be accessed.

Random files are truncated only if accessmode is Write. The reclen

parameter determines the record length for I/O operations.

If the mode parameter is missing, then Random is used.

The accessmode parameter determines what type of I/O operations can be

performed on the file:

Table 3-61 Effect of Accessmode Parameter on File Operations

Access Mode Operations

Read Opens the file for reading only. This value is valid only for files opened in
Binary, Random, or Input mode.

3-372 Docbasic User’s Guide

A-Z Reference Open (statement)

Table 3-61 Effect of Accessmode Parameter on File Operations

Access Mode Operations

Write Opens the file for writing only. This value is valid only for files opened in
Binary, Random, or Output mode.

Read Write Opens the file for both reading and writing. This value is valid only for
files opened in Binary, Random, or Append mode.

If the accessmode parameter is not specified, the following defaults are used:

Table 3-62 Default Values for Accessmode Parameter

File Mode Default Value for accessmode

Input Read

Output Write

Append Read Write

Binary When the file is initially opened, access is attempted three times in the
following order:

1.Read Write
2.Write
3.Read

Random Same as Binary files

The lock parameter determines what access rights are granted to other processes
that attempt to open the same file. The following table describes the values for lock:

Table 3-63 Effect of Lock Parameter on File Access

lock Value Description

Shared Another process can both read this file and write to it. (Deny none.)

Lock Read Another process can write to this file but not read it. (Deny read.)

Lock Write Another process can read this file but not write to it. (Deny write.)

Lock Read Write Another process is prevented both from reading this file and from writing
to it. (Exclusive.)

If lock is not specified, then the file is opened in Shared mode.

If the file does not exist and the lock parameter is specified, the file is opened
twiceonce to create the file and again to establish the correct sharing mode.

Files opened in Random mode are divided up into a sequence of records, each of
the length specified by the reclen parameter. If this parameter is missing, then 128
is used. For files opened for sequential I/O, the reclen parameter specifies the size

Docbasic User’s Guide 3-373

Open (statement) A-Z Reference

of the internal buffer used by Docbasic when performing I/O. Larger buffers mean
faster file access. For Binary files, the reclen parameter is ignored.

Example
This example opens several files in various configurations.
Sub Main()
Open "test.dat" For Output Access Write Lock Write As #2
Close
Open "test.dat" For Input Access Read Shared As #1
Close
Open "test.dat" For Append Access Write Lock Read Write as #3
Close
Open "test.dat" For Binary Access Read Write Shared As #4
Close
Open "test.dat" For Random Access Read Write Lock Read As #5
Close
Open "test.dat" For Input Access Read Shared As #6
Close
Kill "test.dat"
End Sub

Platform(s)
All.

See Also
Close (statement)
Reset (statement)
FreeFile (function)

3-374 Docbasic User’s Guide

A-Z Reference OpenFilename$ (function)

OpenFilename$ (function)

Displays a dialog box that prompts the user to select from a list of files, returning
the full pathname of the file the user selects or a zero-length string if the user selects
Cancel.

Syntax
OpenFilename$[([title$ [,extensions$]])]

Description
This function displays the standard file open dialog box, which allows the user to
select a file. It takes the following parameters:

title$ String specifying the title that appears in the dialog box's
title bar. If this parameter is omitted, then "Open" is used.

extension$ String specifying the available file types. The format for
this string depends on the platform on which Docbasic is
running. If this parameter is omitted, then all files are
displayed.

e$ = "All Files:*.BMP,*.WMF;Bitmaps:*.BMP;Metafiles:*.WMF"

f$ = OpenFilename$("Open Picture",e$)

Docbasic User’s Guide 3-375

OpenFilename$ (function) A-Z Reference

Example
This example asks the user for the name of a file, then proceeds to read the first line
from that file.
Sub Main
Dim f As String,s As String
f$ = OpenFilename$("Open Picture","Text Files:*.TXT")
If f$ <> "" Then
Open f$ For Input As #1
Line Input #1,s$
Close #1
MsgBox "First line from " & f$ & " is " & s$
End If
End Sub

Platform(s)
Windows, Win32, Macintosh.

Platform Notes: Windows, Win32

The extensions$ parameter must be in the following format:
type:ext[,ext][;type:ext[,ext]]...

type Specifies the name of the grouping of files, such as All Files.

ext Specifies a valid file extension, such as *.BAT or *.?F?.

For example, the following are valid extensions$ specifications:

"All Files:*.*"
"Documents:*.TXT,*.DOC"
"All Files:*.*;Documents:*.TXT,*.DOC"

Platform Notes: Macintosh

On the Macintosh, the extensions$ parameter contains a comma-separated list of
four-character file types. For example:
"TEXT,XLS4,MSWD"

On the Macintosh, the title$ parameter is ignored.

See Also
MsgBox (statement)

3-376 Docbasic User’s Guide

A-Z Reference Operator Precedence (topic)

Operator Precedence (topic)

The following table shows the precedence of the operators supported by Docbasic.
Operations involving operators of higher precedence occur before operations
involving operators of lower precedence. When operators of equal precedence
occur together, they are evaluated from left to right.

Table 3-64 Operator Precedence

Operator Description Precedence Order

() Parentheses Highest

^ Exponentiation

- Unary minus

/,* Division and multiplication

\ Integer division

Mod Modulo

+,- Addition and subtraction

& String concatenation

=,<>,>,<,<=,>= Relational

Like, Is String and object comparison

Not Logical negation

And Logical or binary conjunction

Or Logical or binary disjunction

Xor, Eqv, Imp Logical or binary operators Lowest

The precedence order can be controlled using parentheses, as shown below:

a = 4 + 3 * 2a becomes 10.

a = (4 + 3) * 2a becomes 14.

Docbasic User’s Guide 3-377

Operator Precision (topic) A-Z Reference

Operator Precision (topic)

When numeric, binary, logical or comparison operators are used, the data type of
the result is generally the same as the data type of the more precise operand. For
example, adding an Integer and a Long first converts the Integer operand to a
Long, then preforms a long addition, overflowing only if the result cannot be
contained with a Long. The order of precision is shown in the following table:

Empty Least precise

Boolean

Integer

Long

Single

Date

Double

Currency Most precise

There are exceptions noted in the descriptions of each operator.

The rules for operand conversion are further complicated when an operator is used
with variant data. In many cases, an overflow causes automatic promotion of the
result to the next highest precise data type. For example, adding two Integer
variants results in an Integer variant unless it overflows, in which case the result is
automatically promoted to a Long variant.

3-378 Docbasic User’s Guide

A-Z Reference Option Base (statement)

Option Base (statement)

Sets the lower bound for array declarations.

Syntax
Option Base {0 | 1}

Description
By default, the lower bound used for all array declarations is 0.

This statement must appear outside of any functions or subroutines.

Example
Option Base 1
Sub Main()
Dim a(10) 'Contains 10 elements (not 11).
End Sub

Platform(s)
All.

See Also
Dim (statement)
Public (statement)
Private (statement)

Docbasic User’s Guide 3-379

Option Compare (statement) A-Z Reference

Option Compare (statement)

Controls how strings are compared.

Syntax
Option Compare [Binary | Text]

Description
When Option Compare is set to Binary, then string comparisons are case-sensitive
(e.g., "A" does not equal "a"). When it is set to Text, string comparisons are case-
insensitive (e.g., "A" is equal to "a").

The default value for Option Compare is Binary.

The Option Compare statement affects all string comparisons in any statements
that follow the Option Compare statement. Additionally, the setting affects the
default behavior of Instr, StrComp, and the Like operator. The following types of
string comparisons are affected by this setting:

> < <>

<= >= Instr

StrComp Like

The Option Compare statement must appear outside the scope of all subroutines
and functions. In other words, it cannot appear within a Sub or Function block.

Example
This example shows the use of Option Compare.
Option Compare Binary
Sub CompareBinary
a$ = "This String Contains UPPERCASE."
b$ = "this string contains uppercase."
If a$ = b$ Then
MsgBox "The two strings were compared case-insensitive."
Else
MsgBox "The two strings were compared case-sensitive."
End If
End Sub

Option Compare Text

Sub CompareText
a$ = "This String Contains UPPERCASE."
b$ = "this string contains uppercase."

3-380 Docbasic User’s Guide

A-Z Reference Option Compare (statement)

If a$ = b$ Then
MsgBox "The two strings were compared case-insensitive."
Else
MsgBox "The two strings were compared case-sensitive."
End If
End Sub

Sub Main()
CompareBinary 'Calls subroutine above.
CompareText 'Calls subroutine above.
End Sub

Platform(s)
All.

See Also
Like (operator)
InStr (function)
StrComp (function)
Comparison Operators (topic)

Docbasic User’s Guide 3-381

Option CStrings (statement) A-Z Reference

Option CStrings (statement)

Turns on or off the ability to use C-style escape sequences within strings.

Syntax
Option CStrings {On | Off}

Description
When Option CStrings On is in effect, the compiler treats the backslash character
as an escape character when it appears within strings. An escape character is
simply a special character that cannot otherwise be ordinarily typed by the
computer keyboard.

Table 3-65 Typing Special Characters with Option CStrings On

Escape Description Equivalent Expression

\r Carriage return Char$(13)

\n Line Feed Char$(10)

\a Bell Char$(7)

\b Backspace Char$(8)

\f Form Feed Char$(12)

\t Tab Char$(9)

\v Vertical tab Char$(11)

\0 Null Char$(0_

\" Double quote "" or Char$(34)

\\ Backslash Char$(92)

\? Question mark ?

\’ Single quote ’

\xhh Hexadecimal number Char$(Val("&Hhh))

\ooo Octal number Char$(Val("&Oooo"))

\anycharacter Any character anycharacter

With hexadecimal values, Docbasic stops scanning for digits when it encounters a
nonhexadecimal digit or two digits, whichever comes first. Similarly, with octal

3-382 Docbasic User’s Guide

A-Z Reference Option CStrings (statement)

values, Docbasic stops scanning when it encounters a nonoctal digit or three digits,
whichever comes first.

When Option CStrings Off is in effect, then the backslash character has no special
meaning. This is the default.

Example
Option CStrings On

Sub Main()
MsgBox "They said, \"Watch out for that clump of grass!\""
MsgBox "First line.\r\nSecond line."
MsgBox "Char A: \x41 \r\n Char B: \x42"
End Sub

Platform(s)
All.

Docbasic User’s Guide 3-383

Or (operator) A-Z Reference

Or (operator)

Performs a logical or binary disjunction on two expressions.

Syntax
expression1 Or expression2

Description
If both expressions are either Boolean, Boolean variants, or Null variants, then a
logical disjunction is performed as follows:

Table 3-66 Effect of Boolean, Boolean Variant, and Null Expressions on the Or Operator

If the first expression is and the second expression is Then the result is

True True True

True False True

True Null True

False True True

False False False

False Null Null

Null True True

Null False Null

Null Null Null

Binary Disjunction

If the two expressions are Integer, then a binary disjunction is performed, returning
an Integer result. All other numeric types (including Empty variants) are
converted to Long and a binary disjunction is then performed, returning a Long
result.

Binary disjunction forms a new value based on a bit-by-bit comparison of the

binary representations of the two expressions according to the following table:

1 Imp 1 = 1

0 Imp 1 = 1

1 Imp 0 = 1

3-384 Docbasic User’s Guide

A-Z Reference Or (operator)

0 Imp 0 = 0

Examples
This first example shows the use of logical Or.
Dim s$ As String

s$ = InputBox$("Enter a string.")
If s$ = "" Or Mid$(s$,1,1) = "A" Then
s$ = LCase$(s$)
End If

This second example shows the use of binary Or.

Dim w As Integer

TryAgain:
s$ = InputBox$("Enter a hex number (four digits max).")
If Mid$(s$,1,1) <> "&" Then
s$ = "&H" & s$
End If
If Not IsNumeric(s$) Then Goto TryAgain

w = CInt(s$)
MsgBox "Your number is &H" & Hex$(w)
w = w Or &H8000
MsgBox "Your number with the high bit set is &H" & Hex$(w)

Platform(s)
All.

See Also
Operator Precedence (topic)
And (operator)
Eqv (operator)
Imp (operator)
Xor (operator)

Docbasic User’s Guide 3-385

Pi (constant) A-Z Reference

Pi (constant)

The Double value 3.141592653589793238462643383279.

Syntax
Pi

Description
Pi can also be determined using the following formula:
4 * Atn(1)

Example
This example illustrates the use of the Pi constant.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
dia# = 5
circ# = Pi * dia#
area# = Pi * ((dia# / 2) ^ 2)
msg = "Diameter: 5" & crlf
msg = msg & "Circumference: " & Format(circ#,"Standard") & crlf
msg = msg & "Area: " & Format(area#,"Standard")
MsgBox msg
End Sub

Platform(s)
All.

See Also
Tan (function)
Atn (function)
Cos (function)
Sin (function)

3-386 Docbasic User’s Guide

A-Z Reference Pmt (function)

Pmt (function)

Returns the payment for an annuity based on periodic fixed payments and a
constant rate of interest.

Syntax
Pmt(Rate,NPer,Pv,Fv,Due)

Description
An annuity is a series of fixed payments made to an insurance company or other
investment company over a period of time. Examples of annuities are mortgages
and monthly savings plans.

The Pmt function requires the following parameters:

Rate Double representing the interest rate per period. If the

periods are given in months, be sure to normalize annual
rates by dividing them by 12.

NPer Double representing the total number of payments in the

annuity.

Pv Double representing the present value of your annuity. In

the case of a loan, the present value would be the amount
of the loan.

Fv Double representing the future value of your annuity. In

the case of a loan, the future value would be 0.

Due Integer indicating when payments are due for each

payment period. A 0 specifies payment at the end of each
period, whereas a 1 specifies payment at the start of each
period.

Rate and NPer must be expressed in the same units. If Rate is expressed in months,
then NPer must also be expressed in months.

Positive numbers represent cash received, whereas negative numbers represent

cash paid out.

Docbasic User’s Guide 3-387

Pmt (function) A-Z Reference

Example
This example calculates the payment necessary to repay a $1,000.00 loan over 36
months at an annual rate of 10%. Payments are due at the beginning of the period.
Sub Main()
x = Pmt((.1/12),36,1000.00,0,1)
msg = "The payment to amortize $1,000 over 36 months @ 10% is: "
MsgBox msg & Format(x,"Currency")
End Sub

Platform(s)
All.

See Also
IPmt (function)
NPer (function)
PPmt (function)
Rate (function)

3-388 Docbasic User’s Guide

A-Z Reference PPmt (function)

PPmt (function)

Calculates the principal payment for a given period of an annuity based on

periodic, fixed payments and a fixed interest rate.

Syntax
PPmt(Rate,Per,NPer,Pv,Fv,Due)

Description
An annuity is a series of fixed payments made to an insurance company or other
investment company over a period of time. Examples of annuities are mortgages
and monthly savings plans.

The PPmt function requires the following parameters:

Rate Double representing the interest rate per period.

Per Double representing the number of payment periods. Per

can be no less than 1 and no greater than NPer.

NPer Double representing the total number of payments in your

annuity.

Pv Double representing the present value of your annuity. In

the case of a loan, the present value would be the amount
of the loan.

Fv Double representing the future value of your annuity. In

the case of a loan, the future value would be 0.

Due Integer indicating when payments are due. If this

parameter is 0, then payments are due at the end of each
period; if it is 1, then payments are due at the start of each
period.

Rate and NPer must be in the same units to calculate correctly. If Rate is expressed
in months, then NPer must also be expressed in months.

Negative values represent payments paid out, whereas positive values represent
payments received.

Docbasic User’s Guide 3-389

PPmt (function) A-Z Reference

Example
This example calculates the principal paid during each year on a loan of $1,000.00
with an annual rate of 10% for a period of 10 years. The result is displayed as a table
containing the following information: payment, principal payment, principal
balance.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
pay = Pmt(.1,10,1000.00,0,1)
msg = "Amortization table for 1,000" & crlf & "at 10% annually for"
msg = msg & " 10 years: " & crlf & crlf
bal = 1000.00
For per = 1 to 10
prn = PPmt(.1,per,10,1000,0,0)
bal = bal + prn
msg = msg & Format(pay,"Currency") & " " & Format$(Prn,"Currency")
msg = msg & " " & Format(bal,"Currency") & crlf
Next per
MsgBox msg
End Sub

Platform(s)
All.

See Also
IPmt (function)
NPer (function)
Pmt (function)
Rate (function)

3-390 Docbasic User’s Guide

A-Z Reference Print (statement)

Print (statement)

Prints data to an output device.

Syntax
Print [[{Spc(n) | Tab(n)}][expressionlist][{; | ,}]]

Description
The actual output device depends on the platform on which Docbasic is running.

The following table describes how data of different types is written:

Table 3-67 Effect of Data Type on Printing

Data type Description

String Printed in their literal form, with no enclosing quotes.

Any numeric type Printed with an initial space reserved for the sign (space =
positive). Additionally, there is a space following each number.

Boolean Printed as "True" or "False".

Date Printed using the short date format. If either the date or time
component is missing, only the provided portion is printed (this
is consistent with the "general date" format understood by the
Format/Format$ functions).

Empty Nothing is printed

Null Prints "Null".

User-defined errors User-defined errors are printed to files as "Error code", where
code is the value of the user-defined error. The word "Error" is
not translated.

Each expression in expressionlist is separated with either a comma (,) or a

semicolon (;). A comma means that the next expression is output in the next print
zone. A semicolon means that the next expression is output immediately after the
current expression. Print zones are defined every 14 spaces.

If the last expression in the list is not followed by a comma or a semicolon, then a
carriage return is printed to the file. If the last expression ends with a semicolon,
no carriage return is printedthe next Print statement will output information
immediately following the expression. If the last expression in the list ends with a
comma, the file pointer is positioned at the start of the next print zone on the
current line.

Docbasic User’s Guide 3-391

Print (statement) A-Z Reference

The Tab and Spc functions provide additional control over the column position.
The Tab function moves the file position to the specified column, whereas the Spc
function outputs the specified number of spaces.

Examples
Sub Main()
i% = 10
s$ = "This is a test."
Print "The value of i=";i%,"the value of s=";s$

'This example prints the value of i% in print zone 1 and s$ in print

'zone 3.
Print i%,,s$

'This example prints the value of i% and s$ separated by 10 spaces.

Print i%;Spc(10);s$

'This example prints the value of i in column 1 and s$ in column 30.

Print i%;Tab(30);s$

'This example prints the value of i% and s$.

Print i%;s$,
Print 67
End Sub

Platform(s)
All.

Platform Notes: UNIX, Win32, Macintosh

On all UNIX platforms, Win32, and the Macintosh, the Print statement prints data
to stdout.

3-392 Docbasic User’s Guide

A-Z Reference Print# (statement)

Print# (statement)

Writes data to a sequential disk file.

Syntax
Print [#]filenumber, [[{Spc(n) | Tab(n)}][expressionlist][{;|,}]]

Description
The filenumber parameter is a number that is used by Docbasic to refer to the open
file—the number passed to the Open statement.

The following table describes how data of different types is written:

Table 3-68 Effect of Data Type on Printing

Data type Description

String Printed in their literal form, with no enclosing quotes.

Any numeric type Printed with an initial space reserved for the sign (space =
positive). Additionally, there is a space following each number.

Boolean Printed as "True" or "False".

Date Printed using the short date format. If either the date or time
component is missing, only the provided portion is printed (this
is consistent with the "general date" format understood by the
Format/Format$ functions).

Empty Nothing is printed

Null Prints "Null".

User-defined errors User-defined errors are printed to files as "Error code", where
code is the value of the user-defined error. The word "Error" is
not translated.

Each expression in expressionlist is separated with either a comma (,) or a semicolon

(;). A comma means that the next expression is output in the next print zone. A
semicolon means that the next expression is output immediately after the current
expression. Print zones are defined every 14 spaces.

If the last expression in the list is not followed by a comma or a semicolon, then an
end-of-line is printed to the file. If the last expression ends with a semicolon, no
end-of-line is printedthe next Print statement will output information
immediately following the expression. If the last expression in the list ends with a
comma, the file pointer is positioned at the start of the next print zone on the
current line.

Docbasic User’s Guide 3-393

Print# (statement) A-Z Reference

The Write statement always outputs information ending with an end-of-line. Thus,
if a Print statement is followed by a Write statement, the file pointer is positioned
on a new line.

The Print statement can only be used with files that are opened in Output or
Append mode.

The Tab and Spc functions provide additional control over the file position. The
Tab function moves the file position to the specified column, whereas the Spc
function outputs the specified number of spaces.

In order to correctly read the data using the Input# statement, you should write the
data using the Write statement.

Examples
Sub Main()
'This example opens a file and prints some data.
Open "test.dat" For Output As #1
i% = 10
s$ = "This is a test."
Print #1,"The value of i=";i%,"the value of s=";s$

'This example prints the value of i% in print zone 1 and s$ in

'print zone 3.
Print #1,i%,,s$

'This example prints the value of i% and s$ separated by ten spaces.

Print #1,i%;Spc(10);s$

'This example prints the value of i in column 1 and s$ in column 30.

Print #1,i%;Tab(30);s$

'This example prints the value of i% and s$.

Print #1,i%;s$,
Print #1,67

Close #1
Kill "test.dat"
End Sub

Platform(s)
All.

Platform Notes
The end-of-line character is different on many platforms. On some platforms, it is
defined as a carriage-return/line-feed pair, and on other platforms, it is defined as
only a line feed. The Docbasic statements that read sequential files don't care about
the end-of-line character—either will work.

3-394 Docbasic User’s Guide

A-Z Reference Print# (statement)

See Also
Open (statement)
Put (statement)
Write# (statement)

Docbasic User’s Guide 3-395

Private (statement) A-Z Reference

Private (statement)

Declares a list of private variables and their corresponding types and sizes.

Syntax
Private name [(subscripts)] [As type] [,name [(subscripts)] [As type]]...

Description
Private variables are global to every Sub and Function within the currently
executing procedure.

If a type-declaration character is used when specifying name (such as %, @, &, $,

or !), the optional [As type] expression is not allowed. For example, the following
are allowed:
Private foo As Integer
Private foo%

The subscripts parameter allows the declaration of arrays. This parameter uses the
following syntax:
[lower To] upper [,[lower To] upper]...

The lower and upper parameters are integers specifying the lower and upper
bounds of the array. If lower is not specified, then the lower bound as specified by
Option Base is used (or 1 if no Option Base statement has been encountered). Up
to 60 array dimensions are allowed.

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

Dynamic arrays are declared by not specifying any bounds:

Private a()

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

If a variable is seen that has not been explicitly declared with either Dim, Public, or
Private, then it will be implicitly declared local to the routine in which it is used.

Fixed-Length Strings

Fixed-length strings are declared by adding a length to the String type-declaration

character:
Private name As String * length

3-396 Docbasic User’s Guide

A-Z Reference Private (statement)

where length is a literal number specifying the string's length.

Initial Values

All declared variables are given initial values, as described in the following table:

Table 3-69 Initial Values of Declared Variables

Data Type Initial Value

Integer 0

Long 0

Double 0.0

Single 0.0

Currency 0.0

Object Nothing

Date December 31, 1899 00:00:00

Boolean False

Variant Empty

String "" (zero-length string)

User-defined type Each element of the structure is given a default value, as described above.

Arrays Each element of the array is given a default value, as described above.

Example
See Public (statement).

Platform(s)
All.

See Also
Dim (statement)
Redim (statement)
Public (statement)
Option Base (statement)

Docbasic User’s Guide 3-397

Public (statement) A-Z Reference

Public (statement)

Declares a list of public variables and their corresponding types and sizes.

Syntax
Public name [(subscripts)] [As type] [,name [(subscripts)] [As type]]...

Description
Public variables are global to all Subs and Functions in all procedures.

If a type-declaration character is used when specifying name (such as %, @, &, $,

or !), the optional [As type] expression is not allowed. For example, the following
are allowed:
Public foo As integer
Public foo%

The subscripts parameter allows the declaration of arrays. This parameter uses the
following syntax:
[lower To] upper [,[lower To] upper]...

The lower and upper parameters are integers specifying the lower and upper
bounds of the array. If lower is not specified, then the lower bound as specified by
Option Base is used (or 1 if no Option Base statement has been encountered). Up
to 60 array dimensions are allowed.

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

Dynamic arrays are declared by not specifying any bounds:

Public a()

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

If a variable is seen that has not been explicitly declared with either Dim, Public, or
Private, then it will be implicitly declared local to the routine in which it is used.

For compatibility, the keyword Global is also supported. It has the same meaning
as Public.

Fixed-Length Strings

Fixed-length strings are declared by adding a length to the String type-declaration

character:

3-398 Docbasic User’s Guide

A-Z Reference Public (statement)

Public name As String * length

where length is a literal number specifying the string's length.

All declared variables are given initial values, as described in the following table:

Table 3-70 Initial Values of Declared Variables

Data Type Initial Value

Integer 0

Long 0

Double 0.0

Single 0.0

Currency 0.0

Date December 31, 1899 00:00:00

Object Nothing

Boolean False

Variant Empty

String "" (zero-length string)

User-defined type Each element of the structure is given a default value, as described above.

Arrays Each element of the array is given a default value, as described above.

Sharing Variables

When sharing variables, you must ensure that the declarations of the shared
variables are the same in each procedure that uses those variables. If the public
variable being shared is a user-defined structure, then the structure definitions
must be exactly the same.

Example
This example uses a subroutine to calculate the area of ten circles and displays the
result in a dialog box. The variables R and Ar are declared as Public variables so
that they can be used in both Main and Area.
Const crlf = Chr$(13) + Chr$(10)

Public x#, ar#

Sub Area()
ar# = (x# ^ 2) * Pi
End Sub

Docbasic User’s Guide 3-399

Public (statement) A-Z Reference

Sub Main()
msg = "The area of the ten circles are:" & crlf
For x# = 1 To 10
Area
msg = msg & x# & ": " & ar# & Basic.Eoln$
Next x#
MsgBox msg
End Sub

Platform(s)
All.

See Also
Dim (statement)
Redim (statement)
Private (statement)
Option Base (statement)

3-400 Docbasic User’s Guide

A-Z Reference Put (statement)

Put (statement)

Writes data from the specified variable to a Random or Binary file.

Syntax
Put [#]filenumber, [recordnumber], variable

Description
The Put statement accepts the following parameters:

filenumber Integer representing the file to be written to. This is the

same value as returned by the Open statement.

recordnumber Long specifying which record is to be written to the file.

For Binary files, this number represents the first byte to be

written starting with the beginning of the file (the first byte
is 1). For Random files, this number represents the record
number starting with the beginning of the file (the first
record is 1). This value ranges from 1 to 2147483647.

If the recordnumber parameter is omitted, the next record

is written to the file (if no records have been written yet,
then the first record in the file is written). When
recordnumber is omitted, the commas must still appear, as
in the following example:
Put #1,,recvar

If recordlength is specified, it overrides any previous

change in file position specified with the Seek statement.

The variable parameter is the name of any variable of any of the following types:

Table 3-71 Valid Data Types for Variable Parameter

Variable type File storage description

Integer 2 bytes are written to the file.

Long 4 bytes are written to the file.

String (variable-length) In Binary files, variable-length strings are written by first

determining the specified string variable’s length, then
writing that many bytes to a file.
In random files, variable-length strings are written by first
writing a 2 -byte length, then writing that many characters
to the file.

Docbasic User’s Guide 3-401

Put (statement) A-Z Reference

Table 3-71 Valid Data Types for Variable Parameter

Variable type File storage description

String (fixed-length) Fixed-length strings are written to Random and Binary

files in the same way: the number of characters equal to
the string’s declared length are written.

Double 8 bytes are written to the file (IEEE format),

Single 4 bytes are written to the file (IEEE format).

Date 8 bytes are written to the file (IEEE double format).

Boolean 2 bytes are written to the file (either D1 for True or 0 for
False).

Variant A 2-byte VarType is written to the file followed by the data

as described above. With variants of type 10 (user-defined
errors), the 2-byte VarType is followed by a 2-byte
unsigned integer (the error value), which is then followed
by 2 additional bytes of information.
The exception is with strings, which are always preceded
by a 2-byte string length.

User-defined types Each member of a user-defined data type is written

individually.
In Binary files, variable-length strings within user-defined
types are written by first writing a 2-byte length followed
by the string’s content. This storage is different than
variable-length strings outside of user-defined types.
When writing user-defined types, the record length must
be greater than or equal to the combined size of each
element within the data type.

Arrays Arrays cannot be written to a file using the Put statement.

Objects Object variables cannot be written to a file using the Put

statement.

With Random files, a runtime error will occur if the length of the data being written
exceeds the record length (specified as the reclen parameter with the Open
statement). If the length of the data being written is less than the record length, the
entire record is written along with padding (whatever data happens to be in the I/
O buffer at that time). With Binary files, the data elements are written
contiguously: they are never separated with padding.

Example
This example opens a file for random write, then writes ten records into the file
with the values 10-50. Then the file is closed and reopened in random mode for
read, and the records are read with the Get statement. The result is displayed in a
dialog box.
Sub Main()
Open "test.dat" For Random Access Write As #1
For x = 1 To 10

3-402 Docbasic User’s Guide

A-Z Reference Put (statement)

r% = x * 10
Put #1,x,r%
Next x
Close

Open "test.dat" For Random Access Read As #1

For x = 1 To 10
Get #1,x,r%
msg = msg & "Record " & x & " is: " & r% & Basic.Eoln$
Next x

MsgBox msg
Close
Kill "test.dat"
End Sub

Platform(s)
All.

See Also
Open (statement)
Put (statement)
Write# (statement)
Print# (statement)

Docbasic User’s Guide 3-403

Pv (function) A-Z Reference

Pv (function)

Calculates the present value of an annuity based on future periodic fixed payments
and a constant rate of interest.

Syntax
Pv(Rate,NPer,Pmt,Fv,Due)

Description
The Pv function requires the following parameters:

Rate Double representing the interest rate per period. When

used with monthly payments, be sure to normalize annual
percentage rates by dividing them by 12.

NPer Double representing the total number of payments in the

annuity.

Pmt Double representing the amount of each payment per

period.

Fv Double representing the future value of the annuity after

the last payment has been made. In the case of a loan, the
future value would be 0.

Due Integer indicating when the payments are due for each
payment period. A 0 specifies payment at the end of each
period, whereas a 1 specifies payment at the start of each
period.

Rate and NPer must be expressed in the same units. If Rate is expressed in months,
then NPer must also be expressed in months.

Positive numbers represent cash received, whereas negative numbers represent

cash paid out.

Example
This example demonstrates the present value (the amount you'd have to pay (now)
for a $100,000 annuity that pays an annual income of $5,000 over 20 years at an
annual interest rate of 10%.
Sub Main()
pval = Pv(.1,20,-5000,100000,1)

3-404 Docbasic User’s Guide

A-Z Reference Pv (function)

MsgBox "The present value is: " & Format(pval,"Currency")

End Sub

Platform(s)
All.

See Also
Fv (function)
IRR (function)
MIRR (function)
Npv (function)

Docbasic User’s Guide 3-405

Random (function) A-Z Reference

Random (function)

Returns a Long value greater than or equal to min and less than or equal to max.

Syntax
Random(min,max)

Description
Both the min and max parameters are rounded to Long. A runtime error is
generated if min is greater than max.

Example
This example uses the random number generator to generate ten lottery numbers.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
Randomize 'Start with new random seed.
For x = 1 To 10
y = Random(0,100)'Generate numbers.
msg = msg & y & crlf
Next x
MsgBox "Ten numbers for the lottery: " & crlf & msg
End Sub

Platform(s)
All.

See Also
Randomize (statement)
Random (function)

3-406 Docbasic User’s Guide

A-Z Reference Randomize (statement)

Randomize (statement)

Initializes the random number generator with a new seed.

Syntax
Randomize [seed]

Description
If seed is not specified, then the current value of the system clock is used.

Example
This example sets the randomize seed to a random number between 100 and 1000,
then generates ten random numbers for the lottery.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
Randomize 'Start with new random seed.
For x = 1 To 10
y = Random(0,100)'Generate numbers.
msg = msg + Str(y) + crlf
Next x
MsgBox "Ten numbers for the lottery: " & crlf & msg
End Sub

Platform(s)
All.

See Also
Random (function)
Rnd (function)

Docbasic User’s Guide 3-407

Rate (function) A-Z Reference

Rate (function)

Returns the rate of interest for each period of an annuity.

Syntax
Rate(NPer,Pmt,Pv,Fv,Due,Guess)

Description
An annuity is a series of fixed payments made to an insurance company or other
investment company over a period of time. Examples of annuities are mortgages
and monthly savings plans.

The Rate function requires the following parameters:

NPer Double representing the total number of payments in the

annuity.

Pmt Double representing the amount of each payment per

period.

Pv Double representing the present value of your annuity. In a

loan situation, the present value would be the amount of
the loan.

Fv Double representing the future value of the annuity after

the last payment has been made. In the case of a loan, the
future value would be zero.

Due Integer specifying when the payments are due for each
payment period. A 0 indicates payment at the end of each
period, whereas a 1 indicates payment at the start of each
period.

Guess Double specifying a guess as to the value the Rate function

will return. The most common guess is .1 (10 percent).

Positive numbers represent cash received, whereas negative values represent cash
paid out.

The value of Rate is found by iteration. It starts with the value of Guess and cycles
through the calculation adjusting Guess until the result is accurate within 0.00001
percent. After 20 tries, if a result cannot be found, Rate fails, and the user must pick
a better guess.

3-408 Docbasic User’s Guide

A-Z Reference Rate (function)

Example
This example calculates the rate of interest necessary to save $8,000 by paying $200
each year for 48 years. The guess rate is 10%.
Sub Main()
r# = Rate(48,-200,8000,0,1,.1)
MsgBox "The rate required is: " & Format(r#,"Percent")
End Sub

Platform(s)
All.

See Also
IPmt (function)
NPer (function)
Pmt (function)
PPmt (function)

Docbasic User’s Guide 3-409

ReadIni$ (function) A-Z Reference

ReadIni$ (function)

Returns a String containing the specified item from an ini file.

Syntax
ReadIni$(section$,item$[,filename$])

Description
The ReadIni$ function takes the following parameters:

section$ String specifying the section that contains the desired

variable, such as "windows". Section names are specified
without the enclosing brackets.

item$ String specifying the item whose value is to be retrieved.

filename$ String containing the name of the ini file to read.

Platform(s)
Windows, Win32.

Platform Notes: Windows, Win32

Under Windows and Win32, if the name of the ini file is not specified, then win.ini
is assumed.

If the filename$ parameter does not include a path, then this statement looks for ini
files in the Windows directory.

See Also
WriteIni (statement)
ReadIniSection (statement)

3-410 Docbasic User’s Guide

A-Z Reference ReadIniSection (statement)

ReadIniSection (statement)

Fills an array with the item names from a given section of the specified ini file.

Syntax
ReadIniSection section$,ArrayOfItems()[,filename$]

Description
The ReadIniSection statement takes the following parameters:

section$ String specifying the section that contains the desired

variables, such as "windows". Section names are specified
without the enclosing brackets.

ArrayOfItems() Specifies either a zero- or a one-dimensioned array of

strings or variants. The array can be either dynamic or
fixed.

If ArrayOfItems() is dynamic, then it will be redimensioned

to exactly hold the new number of elements. If there are no
elements, then the array will be redimensioned to contain
no dimensions. You can use the LBound, UBound, and
ArrayDims functions to determine the number and size of
the new array's dimensions.

If the array is fixed, each array element is first erased, then

the new elements are placed into the array. If there are
fewer elements than will fit in the array, then the
remaining elements are initialized to zero-length strings
(for String arrays) or Empty (for Variant arrays). A runtime
error results if the array is too small to hold the new
elements.

filename$ String containing the name of an ini file.

On return, the ArrayOfItems() parameter will contain one array element for each
variable in the specified ini section.

Example
Sub Main()
Dim items() As String
ReadIniSection "windows",items$
MsgBox "INI Items " + items$

Docbasic User’s Guide 3-411

ReadIniSection (statement) A-Z Reference

End Sub

Platform(s)
Windows, Win32.

Platform Notes: Windows, Win32

Under Windows and Win32, if the name of the ini file is not specified, then win.ini
is assumed.

If the filename$ parameter does not include a path, then this statement looks for ini
files in the Windows directory.

See Also
ReadIni$ (function)
WriteIni (statement)

3-412 Docbasic User’s Guide

A-Z Reference Redim (statement)

Redim (statement)

Redimensions an array, specifying a new upper and lower bound for each
dimension of the array.

Syntax
Redim [Preserve] variablename (subscriptRange) [As type],...

Description
The variablename parameter specifies the name of an existing array (previously
declared using the Dim statement) or the name of a new array variable. If the array
variable already exists, then it must previously have been declared with the Dim
statement with no dimensions, as shown in the following example:
Dim a$()'Dynamic array of strings (no dimensions yet)

Dynamic arrays can be redimensioned any number of times.

The subscriptRange parameter specifies the new upper and lower bounds for each
dimension of the array using the following syntax:
[lower To] upper [,[lower To] upper]...

If lower is not specified, then 0 is used (or the value set using the Option Base
statement). A runtime error is generated if lower is less than upper. Array
dimensions must be within the following range:
-32768 <= lower <= upper <= 32767

The type parameter can be used to specify the array element type. Arrays can be
declared using any fundamental data type, user-defined data types, and objects.

Redimensioning an array erases all elements of that array unless the Preserve
keyword is specified. When this keyword is specified, existing data in the array is
preserved where possible. If the number of elements in an array dimension is
increased, the new elements are initialized to 0 (or empty string). If the number of
elements in an array dimension is decreased, then the extra elements will be
deleted. If the Preserve keyword is specified, then the number of dimensions of the
array being redimensioned must either be zero or the same as the new number of
dimensions.

Example
This example uses the FileList statement to redim an array and fill it with filename
strings. A new array is then redimmed to hold the number of elements found by
FileList, and the FileList array is copied into it and partially displayed.

Docbasic User’s Guide 3-413

Redim (statement) A-Z Reference

Sub Main()
Dim fl$()
FileList fl$,"*.*"
count = Ubound(fl$)
Redim nl$(Lbound(fl$) To Ubound(fl$))
For x = 1 to count
nl$(x) = fl(x)
Next x
MsgBox "The last element of the new array is: " & nl$(count)
End Sub

Platform(s)
All.

See Also
Dim (statement)
Public (statement)
Private (statement)
ArrayDims (function)
LBound (function)
UBound (function)

3-414 Docbasic User’s Guide

A-Z Reference Rem (statement)

Rem (statement)

Causes the compiler to skip all characters on that line.

Syntax
Rem text

Example
Sub Main()
Rem This is a line of comments that serves to illustrate the
Rem workings of the code. You can insert comments to make it more
Rem readable and maintainable in the future.
End Sub

Platform(s)
All.

See Also
' (keyword)
Comments (topic)

Docbasic User’s Guide 3-415

Reset (statement) A-Z Reference

Reset (statement)

Closes all open files, writing out all I/O buffers.

Syntax
Reset

Example
This example opens a file for output, closes it with the Reset statement, then deletes
it with the Kill statement.
Sub Main()
Open "test.dat" for Output Access Write as # 1
Reset
Kill "test.dat"

If FileExists("test.dat") Then
MsgBox "The file was not deleted."
Else
MsgBox "The file was deleted."
End If
End Sub

Platform(s)
All.

See Also
Close (statement)
Open (statement)

3-416 Docbasic User’s Guide

A-Z Reference Resume (statement)

Resume (statement)

Ends an error handler and continues execution.

Syntax
Resume {[0] | Next | label}

Description
The form Resume 0 (or simply Resume by itself) causes execution to continue with
the statement that caused the error.

The form Resume Next causes execution to continue with the statement following
the statement that caused the error.

The form Resume label causes execution to continue at the specified label.

The Resume statement resets the error state. This means that, after executing this
statement, new errors can be generated and trapped as normal.

Example
This example accepts two integers from the user and attempts to 'multiply the
numbers together. If either number is larger than an 'integer, the program
processes an error routine and then continues 'program execution at a specific
section using 'Resume <label>'. 'Another error trap is then set using 'Resume Next'.
The new error 'trap will clear any previous error branching and also 'tell' the
'program to continue execution of the program even if an error is encountered.
Sub Main()
Dim a%, b%, x%

Again:
On Error Goto Overflow
a% = InputBox("Enter 1st integer to multiply","Enter Number")
b% = InputBox("Enter 2nd integer to multiply","Enter Number")

On Error Resume Next'Continue program execution at next line x% = a% *

b% 'if an error occurs.

if err = 0 then
MsgBox x%
else
Msgbox a% & " * " & b% & " cause an overflow!"
end if

Exit Sub

Overflow: 'Error handler.

Docbasic User’s Guide 3-417

Resume (statement) A-Z Reference

MsgBox "You've entered a non-integer value, try again!"

Resume Again
End Sub

Platform(s)
All.

See Also
Error Handling (topic)
On Error (statement)

3-418 Docbasic User’s Guide

A-Z Reference Return (statement)

Return (statement)

Transfers execution control to the statement following the most recent GoSub.

Syntax
Return

Description
A runtime error results if a Return statement is encountered without a
corresponding GoSub statement.

Example
This example calls a subroutine and then returns execution to the Main routine by
the Return statement.
Sub Main()
GoSub SubTrue
MsgBox "The Main routine continues here."
Exit Sub

SubTrue:
MsgBox "This message is generated in the subroutine."
Return
Exit Sub
End Sub

Platform(s)
All.

See Also
GoSub (statement)

Docbasic User’s Guide 3-419

Right, Right$ (functions) A-Z Reference

Right, Right$ (functions)

Returns the rightmost NumChars characters from a specified string.

Syntax
Right[$](text,NumChars)

Description
Right$ returns a String, whereas Right returns a String variant.

The Right function takes the following parameters:

text String from which characters are returned. A runtime error

is generated if text is Null.

NumChars Integer specifying the number of characters to return. If

NumChars is greater than or equal to the length of the
string, then the entire string is returned. If NumChars is 0,
then a zero-length string is returned.

Example
This example shows the Right$ function used in a routine to change uppercase
names to lowercase with an uppercase first letter.
Sub Main()
lname$ = "WILLIAMS"
x = Len(lname$)
rest$ = Right$(lname$,x - 1)
fl$ = Left$(lname$,1)
lname$ = fl$ & LCase$(rest$)
MsgBox "The converted name is: " & lname$
End Sub

Platform(s)
All.

See Also
Left, Left$ (functions)

3-420 Docbasic User’s Guide

A-Z Reference RmDir (statement)

RmDir (statement)

Removes the directory specified by the String contained in dir$.

Syntax
RmDir dir$

Example
This routine creates a directory and then deletes it with RmDir.
Sub Main()
On Error Goto ErrMake
MkDir("test01")
On Error Goto ErrRemove
RmDir("test01")

ErrMake:
MsgBox "The directory could not be created."
Exit Sub

ErrRemove:
MsgBox "The directory could not be removed."
Exit Sub
End Sub

Platform(s)
All.

See Also
ChDir (statement)
ChDrive (statement)
CurDir, CurDir$ (functions)
Dir, Dir$ (functions)
MkDir (statement)

Docbasic User’s Guide 3-421

Rnd (function) A-Z Reference

Rnd (function)

Returns a random Single number between 0 and 1.

Syntax
Rnd[(number)]

Description
If number is omitted, the next random number is returned. Otherwise, the number
parameter has the following meaning:

Table 3-72 Meaning of the Number Parameter

If Then

number < 0 Always returns the same number.

number = 0 Returns the last number generated.

number > 0 Returns the next random number.

Example
This routine generates a list of random numbers and displays them.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
For x = -1 To 8
y! = Rnd(1) * 100
msg = msg & x & " : " & y! & crlf
Next x
MsgBox msg & "Last form: " & Rnd
End Sub

Platform(s)
All.

See Also
Randomize (statement)
Random (function)

3-422 Docbasic User’s Guide

A-Z Reference RSet (statement)

RSet (statement)

Copies the source string source into the destination string destvariable.

Syntax
RSet destvariable = source

Description
If source is shorter in length than destvariable, then the string is right-aligned within
destvariable and the remaining characters are padded with spaces. If source is
longer than destvariable, then source is truncated, copying only the leftmost number
of characters that will fit in destvariable. A runtime error is generated if source is
Null.

The destvariable parameter specifies a String or Variant variable. If destvariable is a

Variant containing Empty, then no characters are copied. If destvariable is not
convertible to a String, then a runtime error occurs. A runtime error results if
destvariable is Null.

Example
This example replaces a 40-character string of asterisks (*) with an RSet and LSet
string and then displays the result.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
Dim msg,tmpstr$
tmpstr$ = String$(40, "*")
msg = "Here are two strings that have been right-" & crlf
msg = msg & "and left-justified in a 40-character string."
msg = msg & crlf & crlf
RSet tmpstr$ = "Right->"
msg = msg & tmpstr$ & crlf
LSet tmpstr$ = "<-Left"
msg = msg & tmpstr$ & crlf
MsgBox msg
End Sub

Platform(s)
All.

Docbasic User’s Guide 3-423

RSet (statement) A-Z Reference

See Also
LSet (statement)

3-424 Docbasic User’s Guide

A-Z Reference RTrim, RTrim$ (functions)

RTrim, RTrim$ (functions)

Returns a string with the trailing spaces removed.

Syntax
RTrim[$](text)

Description
RTrim$ returns a String, whereas RTrim returns a String variant.

Null is returned if text is Null.

Example
This example displays a left-justified string and its RTrim result.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
a$ = "This is a left-justified string. "
b$ = RTrim$(a$)
MsgBox a$ & "<=" & crlf & b$ & "<="
End Sub

Platform(s)
All.

See Also
LTrim, LTrim$ (functions)
Trim, Trim$ (functions)

Docbasic User’s Guide 3-425

SaveFilename$ (function) A-Z Reference

SaveFilename$ (function)

Displays a dialog box that prompts the user to select from a list of files and returns
a String containing the full path of the selected file.

Syntax
SaveFilename$[([title$ [,extensions$]])]

Description
The SaveFilename$ function accepts the following parameters:

title$ String containing the title that appears on the dialog box's
caption. If this string is omitted, then "Save As" is used.

extensions$ String containing the available file types. Its format

depends on the platform on which Docbasic is running. If
this string is omitted, then all files are used.

The SaveFilename$ function returns a full pathname of the file that the user selects.
A zero-length string is returned if the user selects Cancel. If the file already exists,
then the user is prompted to overwrite it.
e$ = "All Files:*.BMP,*.WMF;Bitmaps:*.BMP;Metafiles:*.WMF"
f$ = SaveFilename$("Save Picture",e$)

3-426 Docbasic User’s Guide

A-Z Reference SaveFilename$ (function)

Example
This example creates a save dialog box, giving the user the ability to save to several
different file types.
Sub Main()
e$ = "All Files:*.BMP,*.WMF;Bitmaps:*.BMP;Metafiles:*.WMF"
f$ = SaveFilename$("Save Picture",e$)
If Not f$ = "" Then
Msgbox "User choose to save file as: " + f$
Else
Msgbox "User canceled."
End IF
End Sub

Platform(s)
Windows, Win32, Macintosh.

Platform Notes: Windows, Win32

Under Windows and Win32, the extensions$ parameter must be in the following
format:
description:ext[,ext][;description:ext[,ext]]...

description Specifies the grouping of files for the user, such as All Files.

ext Specifies a valid file extension, such as *.BAT or *.?F?.

For example, the following are valid extensions$ specifications:

"All Files:*"
"Documents:*.TXT,*.DOC"
"All Files:*;Documents:*.TXT,*.DOC"

Platform Notes: Macintosh

On the Macintosh, the extensions$ parameter contains a comma-separated list of
four-character file types. For example:
"TEXT,XLS4,MSWD"

On the Macintosh, the title$ parameter is ignored.

Docbasic User’s Guide 3-427

SaveFilename$ (function) A-Z Reference

See Also
MsgBox (statement)
OpenFilename$ (function)

3-428 Docbasic User’s Guide

A-Z Reference Second (function)

Second (function)

Returns the second of the day encoded in the time parameter.

Syntax
Second(time)

Description
The value returned is an Integer between 0 and 59 inclusive.

The time parameter is any expression that converts to a Date.

Example
This example takes the current time; extracts the hour, minute, and second; and
displays them as the current time.
Sub Main()
xt# = TimeValue(Time$())
xh# = Hour(xt#)
xm# = Minute(xt#)
xs# = Second(xt#)
Msgbox "The current time is: " & CStr(xh#) & ":" & CStr(xm#) & ":" &
CStr(xs#)
End Sub

Platform(s)
All.

See Also
Day (function)
Minute (function)
Month (function)
Year (function)
Hour (function)
Weekday (function)
DatePart (function)

Docbasic User’s Guide 3-429

Seek (function) A-Z Reference

Seek (function)

Returns the position of the file pointer in a file relative to the beginning of the file.

Syntax
Seek(filenumber)

Description
The filenumber parameter is a number that Docbasic uses to refer to the open file—
the number passed to the Open statement.

The value returned depends on the mode in which the file was opened:

Table 3-73 Effect of File Open Mode on Return Value of Seek

File Mode Returns

Input Byte position for the next read

Output Byte position for the next write

Append Byte position for the next write

Random Number of the next record to be written or read

Binary Byte position for the next read or write

The value returned is a Long between 1 and 2147483647, where the first byte (or
first record) in the file is 1.

Example
This example opens a file for random write, then writes ten records into the file
using the PUT statement. The file position is displayed using the Seek Function,
and the file is closed.
Sub Main()
Open "test.dat" For Random Access Write As #1
For x = 1 To 10
r% = x * 10
Put #1,x,r%
Next x
y = Seek(1)
MsgBox "The current file position is: " & y
Close
End Sub

3-430 Docbasic User’s Guide

A-Z Reference Seek (function)

Platform(s)
All.

See Also
Seek (statement)
Loc (function)

Docbasic User’s Guide 3-431

Seek (statement) A-Z Reference

Seek (statement)

Sets the position of the file pointer within a given file such that the next read or
write operation will occur at the specified position.

Syntax
Seek [#] filenumber,position

Description
The Seek statement accepts the following parameters:

filenumber Integer used by Docbasic to refer to the open file—the

number passed to the Open statement.

position Long that specifies the location within the file at which to
position the file pointer. The value must be between 1 and
2147483647, where the first byte (or record number) in the
file is 1. For files opened in either Binary, Output, Input, or
Append mode, position is the byte position within the file.
For Random files, position is the record number.

A file can be extended by seeking beyond the end of the file and writing data there.

Example
This example opens a file for random write, then writes ten records into the file
using the PUT statement. The file is then reopened for read, and the ninth record
is read using he Seek and Get functions.
Sub Main()
Open "test.dat" For Random Access Write As #1
For x = 1 To 10
rec$ = "Record#: " & x
Put #1,x,rec$
Next x
Close

Open "test.dat" For Random Access Read As #1

Seek #1,9
Get #1,,rec$
MsgBox "The ninth record = " & x
Close
Kill "test.dat"
End Sub

3-432 Docbasic User’s Guide

A-Z Reference Seek (statement)

Platform(s)
All.

See Also
Seek (function)
Loc (function)

Docbasic User’s Guide 3-433

Select...Case (statement) A-Z Reference

Select...Case (statement)

Used to execute a block of Docbasic statements depending on the value of a given

expression.

Syntax
Select Case testexpression
[Case expressionlist
[statement_block]]
[Case expressionlist
[statement_block]]
.
.
[Case Else
[statement_block]]
End Select

Description
The Select Case statement has the following parameters:

testexpression Any numeric or string expression.

statement_block Any group of Docbasic statements. If testexpression matches

any of the expressions contained in expressionlist, then this
statement block will be executed.

expressionlist A comma separated list of expressions to be compared

against testexpression using any of the following syntaxes:

expression [,expression]...

expression to expression

is relational_operator expression

The resultant type of expression in expressionlist must be the

same as that of testexpression.

Multiple expression ranges can be used within a single Case clause. For example:
Case 1 to 10,12,15, Is > 40

Only the statement_block associated with the first matching expression will be
executed. If no matching expression is found, then the statements following the
Case Else will be executed.

3-434 Docbasic User’s Guide

A-Z Reference Select...Case (statement)

A Select...End Select expression can also be represented with the If...Then

expression. The use of the Select statement, however, may be more readable.

Example
This example uses the Select...Case statement to output the current operating
system.
Sub Main()
OpSystem% = Basic.OS
Select Case OpSystem%
Case 0,2
s = "Microsoft Windows"
Case 3 to 8, 12
s = "UNIX"
Case Else
s = "Other"
End Select
MsgBox "This version of Docbasic is running on: " & s
End Sub

Platform(s)
All.

See Also
Choose (function)
Switch (function)
IIf (function)
If...Then...Else (statement)

Docbasic User’s Guide 3-435

Set (statement) A-Z Reference

Set (statement)

Assigns a value to an object variable.

Syntax 1
Set object_var = object_expression

Syntax 2
Set object_var = New object_type

Syntax 3
Set object_var = Nothing

Description

Syntax 1

The first syntax assigns the result of an expression to an object variable. This
statement does not duplicate the object being assigned but rather copies a reference
of an existing object to an object variable.

The object_expression is any expression that evaluates to an object of the same type
as the object_var.

With data objects, Set performs additional processing. When the Set is performed,
the object is notified that a reference to it is being made and destroyed. For
example, the following statement deletes a reference to object A, then adds a new
reference to B.
Set a = b

In this way, an object that is no longer being referenced can be destroyed.

Syntax 2

In the second syntax, the object variable is being assigned to a new instance of an
existing object type. This syntax is valid only for data objects.

When an object created using the New keyword goes out of scope (i.e., the Sub or
Function in which the variable is declared ends), the object is destroyed.

3-436 Docbasic User’s Guide

A-Z Reference Set (statement)

Syntax 3

The reserved keyword Nothing is used to make an object variable reference no

object. At a later time, the object variable can be compared to Nothing to test
whether the object variable has been instantiated:

Set a = Nothing
:
If a Is Nothing Then Beep

Example
This example creates two objects and sets their values.
Sub Main()
Dim document As Object
Dim page As Object
Set document = GetObject("c:\resume.doc")
Set page = Document.ActivePage
MsgBox page.name
End Sub

Platform(s)
All.

See Also
= (statement)
Let (statement)
CreateObject (function)
GetObject (function)
Nothing (constant)

Docbasic User’s Guide 3-437

SetAppInfo (function) A-Z Reference

SetAppInfo (function)

Writes a string to a specified section of a specified file on the user’s local disk.

Syntax
SetAppInfo(section$,entry$,string$,filename$)

Description
The SetAppInfo function accepts the following parameters:

section$ The name of a section in the file where the setting will be
written. The name can contain only alphabetic characters
and is case-sensitive. Do not include brackets ([ ]) around
the name.
If section$ does exist, Docbasic adds the entry to that
section. If section$ does not exit, Docbasic creates it.

entry$ The name of the entry to set. If entry$ is NULL, the entire
section, including all entries in the section, is deleted.

string$ The value of the setting specified by entry$. If string$ is

NULL, the entry specified by entry$ is removed.

filename$ The name of the file where the settings are stored. Do not
include a file name extension. Docbasic automatically adds
".ini" as the file name extension. If filename$ does not exist,
Docbasic creates it.

SetAppInfo lets you store persistent information about an application. For

example, you might want to store the size and position of a window and recall this
information the next time an application is run.

SetAppInfo stores the information in filename$ in the following format:

[section$]
entry$ = string$

To retrieve information saved with SetAppInfo, use the GetAppInfo function.

Example
This example saves the position of a window to a file called MyFile.ini.
Sub Main()

3-438 Docbasic User’s Guide

A-Z Reference SetAppInfo (function)

ret% = SetAppInfo("My Application","WindowPosition","0,0,600,400",_

"MyFile")
End Sub

In MyFile.ini, the information is written as follows:

[MyApplication]
WindowPosition = 0,0,600,400

Platform(s)
All.

See Also
GetAppInfo (function)

Docbasic User’s Guide 3-439

SetAttr (statement) A-Z Reference

SetAttr (statement)

Changes the attribute filename$ to the given attribute. A runtime error results if the
file cannot be found.

Syntax
SetAttr filename$,attribute

Description
The SetAttr statement accepts the following parameters:

filename$ String containing the name of the file.

attribute Integer specifying the new attribute of the file.

The attribute parameter can contain any combination of the following values:

Table 3-74 Values for Attribute Parameter

Constant Value Includes

ebNormal 0 Turns off all attributes

ebReadOnly 1 Read-only files

ebHidden 2 Hidden files

ebSystem 4 System files

ebVolume 8 Volume label

ebArchive 32 Files that have changed since the last backup

ebNone 64 Files with no attributes

The attributes can be combined using the + operator or the binary Or operator.

Example
This example creates a file and sets its attributes to Read-Only and System.
Sub Main()
Open "test.dat" For Output Access Write As #1
Close
MsgBox "The current file attribute is: " & GetAttr("test.dat")
SetAttr "test.dat",ebReadOnly Or ebSystem

3-440 Docbasic User’s Guide

A-Z Reference SetAttr (statement)

MsgBox "The file attribute was set to: " & GetAttr("test.dat")
End Sub

Platform(s)
All.

Platform Notes: UNIX

On UNIX platforms, the hidden file attribute corresponds to files without the read
or write attributes.

See Also
GetAttr (function)
FileAttr (function)

Docbasic User’s Guide 3-441

Sgn (function) A-Z Reference

Sgn (function)

Returns an Integer indicating whether a number is less than, greater than, or equal
to 0.

Syntax
Sgn(number)

Description
Returns 1 if number is greater than 0.

Returns 0 if number is equal to 0.

Returns -1 if number is less than 0.

The number parameter is a numeric expression of any type. If number is Null, then
a runtime error is generated. Empty is treated as 0.

Example
This example tests the product of two numbers and displays a message based on
the sign of the result.
Sub Main()
a% = -100
b% = 100
c% = a% * b%
Select Case Sgn(c%)
Case -1
MsgBox "The product is negative " & Sgn(c%)
Case 0
MsgBox "The product is 0 " & Sgn(c%)
Case 1
MsgBox "The product is positive " & Sgn(c%)
End Select
End Sub

Platform(s)
All.

See Also
Abs (function)

3-442 Docbasic User’s Guide

A-Z Reference Shell (function)

Shell (function)

Executes another application, returning the task ID if successful.

Syntax
Shell(command$ [,WindowStyle])

Description
The Shell statement accepts the following parameters:

command$ String containing the name of the application and any

parameters.

WindowStyle Optional Integer specifying the state of the application

window after execution. It can be any of the following
values:
1 Normal window with focus
2 Minimized with focus (default)
3 Maximized with focus
4 Normal window without focus
7 Minimized without focus

An error is generated if unsuccessful running command$.

The Shell command runs programs asynchronously: the statement following the
Shell statement will execute before the child application has exited. On some
platforms, the next statement will run before the child application has finished
loading.

Platform(s)
All.

Platform Notes: Macintosh

The Macintosh does not support wildcard characters such as * and ?. These are
valid filename characters. Instead of wildcards, the Macintosh uses the MacID
function to specify a collection of files of the same type. The syntax for this function
is:
Shell(MacID(text$) [,WindowStyle])

Docbasic User’s Guide 3-443

Shell (function) A-Z Reference

The text$ parameter is a four-character string containing an application signature.

A runtime error occurs if the MacID function is used on platforms other than the
Macintosh.

On the Macintosh, the WindowStyle parameter only specifies whether the

application receives the focus.

Platform Notes: Windows

Under Windows, this function returns the hInstance of the application. Since this
value is only a WORD in size, the upper WORD of the result is always zero.

Platform Notes: Win32

Under Win32, this function returns a global process ID that can be used to identify
the new process.

Platform Notes: UNIX

Under all versions of UNIX, the WindowStyle parameter is ignored. This function
returns the process identifier of the new process.

Under UNIX, Docbasic attempts to execute the command line using the Bourne
shell (sh), which it finds by searching the path. If the shell isn't found in the path,
then a default path of /usr/bin is assumed.

3-444 Docbasic User’s Guide

A-Z Reference Sin (function)

Sin (function)

Returns a Double value specifying the sine of angle.

Syntax
Sin(angle)

Description
The angle parameter is a Double specifying an angle in radians.

Example
This example displays the sine of pi/4 radians (45 degrees).
Sub Main()
c# = Sin(Pi / 4)
MsgBox "The sine of 45 degrees is: " & c#
End Sub

Platform(s)
All.

See Also
Tan (function)
Cos (function)
Atn (function)

Docbasic User’s Guide 3-445

Single (data type) A-Z Reference

Single (data type)

A data type used to declare variables capable of holding real numbers with up to
seven digits of precision.

Syntax
Single

Description
Single variables are used to hold numbers within the following ranges:

Table 3-75 Range of Values for Single Data Type

Sign Range

Negative -3.402823E38 <= single <= -1.401298E-45

Positive 1.401298E-45 <= single <= 3.402823E38

The type-declaration character for Single is !.

Storage

Internally, singles are stored as 4-byte (32-bit) IEEE values. Thus, when appearing
within a structure, singles require 4 bytes of storage. When used with binary or
random files, 4 bytes of storage is required.

Each single consists of the following

A 1-bit sign

An 8-bit exponent

A 24-bit mantissa

Platform(s)
All.

See Also
Boolean (data type)
Currency (data type)
Date (data type)
Double (data type)

3-446 Docbasic User’s Guide

A-Z Reference Single (data type)

Integer (data type)

Long (data type)
Object (data type)
String (data type)
Variant (data type)
DefType (statement)
CSng (function)

Docbasic User’s Guide 3-447

Sleep (statement) A-Z Reference

Sleep (statement)

Causes the procedure to pause for a specified number of milliseconds.

Syntax
Sleep milliseconds

Description
The milliseconds parameter is a Long in the following range:

0 <= milliseconds <= 2,147,483,647

Example
This example displays a message for 2 seconds.
Sub Main()
... ' Your code
Sleep(2000)
... ' Your code
End Sub

Platform(s)
All.

Platform Notes: Windows

Under Windows, the accuracy of the system clock is modulo 55 milliseconds. The
value of milliseconds will, in the worst case, be rounded up to the nearest multiple
of 55. In other words, if milliseconds is 1, it will be rounded to 55 in the worst case.

3-448 Docbasic User’s Guide

A-Z Reference Sln (function)

Sln (function)

Returns the straight-line depreciation of an asset assuming constant benefit from

the asset.

Syntax
Sln(Cost,Salvage,Life)

Description
The Sln of an asset is found by taking an estimate of its useful life in years,
assigning values to each year, and adding up all the numbers.

The formula used to find the Sln of an asset is as follows:

(Cost - Salvage Value) / Useful Life

The Sln function requires the following parameters:

Cost Double representing the initial cost of the asset.

Salvage Double representing the estimated value of the asset at the

end of its useful life.

Life Double representing the length of the asset's useful life.

The unit of time used to express the useful life of the asset is the same as the unit
of time used to express the period for which the depreciation is returned.

Example
This example calculates the straight-line depreciation of an asset that cost
$10,000.00 and has a salvage value of $500.00 as scrap after 10 years of service life.
Sub Main()
dep# = Sln(10000.00,500.00,10)
MsgBox "The annual depreciation is: " & Format(dep#,"Currency")
End Sub

Platform(s)
All.

Docbasic User’s Guide 3-449

Sln (function) A-Z Reference

See Also
SYD (function)
DDB (function)

3-450 Docbasic User’s Guide

A-Z Reference Space, Space$ (functions)

Space, Space$ (functions)

Returns a string containing the specified number of spaces.

Syntax
Space[$](NumSpaces)

Description
Space$ returns a String, whereas Space returns a String variant.

NumSpaces is an Integer between 0 and 32767.

Example
This example returns a string of ten spaces and displays it.
Sub Main()
ln$ = Space$(10)
MsgBox "Hello" & ln$ & "over there."
End Sub

Platform(s)
All.

See Also
String, String$ (functions)
Spc (function)

Docbasic User’s Guide 3-451

Spc (function) A-Z Reference

Spc (function)

Prints out the specified number of spaces. This function can only be used with the
Print and Print# statements.

Syntax
Spc(numspaces)

Description
The numspaces parameter is an Integer specifying the number of spaces to be
printed. It can be any value between 0 and 32767.

If a line width has been specified (using the Width statement), then the number of
spaces is adjusted as follows:
numspaces = numspaces Mod width

If the resultant number of spaces is greater than width - print_position, then the
number of spaces is recalculated as follows:
numspaces = numspaces - (width - print_position)

These calculations have the effect of never allowing the spaces to overflow the line
length. Furthermore, with a large value for column and a small line width, the file
pointer will never advance more than one line.

Example
This example displays 20 spaces between the arrows.
Sub Main()
Print "I am"; Spc(20); "20 spaces apart!"
Sleep (10000)'Wait 10 seconds.
End Sub

Platform(s)
All.

See Also
Tab (function)
Print (statement)
Print# (statement)

3-452 Docbasic User’s Guide

A-Z Reference Sqr (function)

Sqr (function)

Returns a Double representing the square root of number.

Syntax
Sqr(number)

Description
The number parameter is a Double greater than or equal to 0.

Example
This example calculates the square root of the numbers from 1 to 10 and displays
them.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
For x = 1 To 10
sx# = Sqr(x)
msg = msg & Format(x,"Fixed") & " - " & Format(sx#,"Fixed") & crlf
Next x
MsgBox msg
End Sub

Platform(s)
All.

Docbasic User’s Guide 3-453

Stop (statement) A-Z Reference

Stop (statement)

Suspends execution of the current procedure, returning control to a debugger if

one is present. If a debugger is not present, this command will have the same effect
as End.

Syntax
Stop

Example
The Stop statement can be used for debugging. In this example, it is used to stop
execution when Z is randomly set to 0.
Sub Main()
For x = 1 To 10
z = Random(0,10)
If z = 0 Then Stop
y = x / z
Next x
End Sub

Platform(s)
All.

See Also
Exit For (statement)
Exit Do (statement)
Exit Function (statement)
Exit Sub (statement)
End (statement)

3-454 Docbasic User’s Guide

A-Z Reference Str, Str$ (functions)

Str, Str$ (functions)

Returns a string representation of the given number.

Syntax
Str[$](number)

Description
The number parameter is any numeric expression or expression convertible to a
number. If number is negative, then the returned string will contain a leading minus
sign. If number is positive, then the returned string will contain a leading space.

Singles are printed using only 7 significant digits. Doubles are printed using 15-16
significant digits.

These functions only output the period as the decimal separator and do not output
thousands separators. Use the CStr, Format, or Format$ function for this purpose.

Example
In this example, the Str$ function is used to display the value of a numeric variable.
Sub Main()
x# = 100.22
MsgBox "The string value is: " + Str(x#)
End Sub

Platform(s)
All.

See Also
Format, Format$ (functions)
CStr (function)

Docbasic User’s Guide 3-455

StrComp (function) A-Z Reference

StrComp (function)

Returns an Integer indicating the result of comparing the two string arguments.

Syntax
StrComp(string1,string2 [,compare])

Description
The StrComp function accepts the following parameters:

string1 First string to be compared, which can be any expression

convertible to a String.

string2 Second string to be compared, which can be any expression

convertible to a String.

compare Optional Integer specifying how the comparison is to be

performed. It can be either of the following values:
0 Case-sensitive comparison
1 Case-insensitive comparison

If compare is not specified, then the current Option Compare setting is used. If no
Option Compare statement has been encountered, then Binary is used (i.e., string
comparison is case-sensitive).

Any of the following values are returned:

Table 3-76 StrComp Return Values

Value Description

0 string1 = string2

1 string1 > string2

-1 string1 < string2

Null string1 or string2 is Null

3-456 Docbasic User’s Guide

A-Z Reference StrComp (function)

Example
This example compares two strings and displays the results. It illustrates that the
function compares two strings to the length of the shorter string in determining
equivalency.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
a$ = "This string is UPPERCASE and lowercase"
b$ = "This string is uppercase and lowercase"
c$ = "This string"
d$ = "This string is uppercase and lowercase characters"
abc = StrComp(a$,b$,0)
msg = msg & "a and c (sensitive) : " & Format(abc,"True/False") & crlf
abi = StrComp(a$,b$,1)
msg = msg & "a and b (insensitive): " & Format(abi,"True/False") & crlf
aci = StrComp(a$,c$,1)
msg = msg & "a and c (insensitive): " & Format(aci,"True/False") & crlf
bdi = StrComp(b$,d$,1)
msg = msg & "b and d (sensitive) : " & Format(bdi,"True/False") & crlf
MsgBox msg
End Sub

Platform(s)
All.

See Also
Comparison Operators (topic)
Like (operator)
Option Compare (statement)

Docbasic User’s Guide 3-457

String (data type) A-Z Reference

String (data type)

A data type capable of holding a number of characters.

Syntax
String

Description
Strings are used to hold sequences of characters, each character having a value
between 0 and 255. Strings can be any length up to a maximum length of 32767
characters.

Strings can contain embedded nulls, as shown in the following example:

s$ = "Hello" + Chr$(0) + "there"'String with embedded null

The length of a string can be determined using the Len function. This function
returns the number of characters that have been stored in the string, including
unprintable characters.

The type-declaration character for String is $.

String variables that have not yet been assigned are set to zero-length by default.

Strings are normally declared as variable-length, meaning that the memory

required for storage of the string depends on the size of its content. The following
Docbasic statements declare a variable-length string and assign it a value of length
5:
Dim s As String
s = "Hello" 'String has length 5.

Fixed-length strings are given a length in their declaration:

Dim s As String * 20
s = "Hello" 'String has length 20 (internally pads with spaces).

When a string expression is assigned to a fixed-length string, the following rules

apply:

If the string expression is less than the length of the fixed-length string, then
the fixed-length string is padded with spaces up to its declared length.

If the string expression is greater than the length of the fixed-length string,
then the string expression is truncated to the length of the fixed-length string.

Fixed-length strings are useful within structures when a fixed size is required, such
as when passing structures to external routines.

3-458 Docbasic User’s Guide

A-Z Reference String (data type)

The storage for a fixed-length string depends on where the string is declared, as
described in the following :

Table 3-77 Effect of Declaration on String Storage

Declared Stored

In structures In the same data area as that of the structure. Local structures are on the
stack; public structures are stored in the public data space; and private
structures are stored in the private data space. Local structures should be
used sparingly as stack space is limited.

In arrays In the global string space along with all the other array elements.

Local routines On the stack. The stack is limited in size, so local fixed-length strings
should be used sparingly.

Platform(s)
All.

See Also
Boolean (data type)
Currency (data type)
Date (data type)
Double (data type)
Integer (data type)
Long (data type)
Object (data type)
Single (data type)
Variant (data type)
DefType (statement)
CStr (function)

Docbasic User’s Guide 3-459

String, String$ (functions) A-Z Reference

String, String$ (functions)

Returns a string of length number consisting of a repetition of the specified filler

character.

Syntax
String[$](number,[CharCode | text$])

Description
String$ returns a String, whereas String returns a String variant.

These functions take the following parameters:

number Integer specifying the number of repetitions.

CharCode Integer specifying the character code to be used as the filler

character. If CharCode is greater than 255 (the largest
character value), then Docbasic converts it to a valid
character using the following formula:

CharCode Mod 256

text$ Any String expression, the first character of which is used

as the filler character.

Example
This example uses the String function to create a line of "=" signs the length of
another string and then displays the character string underlined with the
generated string.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
a$ = "This string will appear underlined."
b$ = String$(Len(a$),"=")
MsgBox a$ & crlf & b$
End Sub

Platform(s)
All.

3-460 Docbasic User’s Guide

A-Z Reference String, String$ (functions)

See Also
Space, Space$ (functions)

Docbasic User’s Guide 3-461

Sub...End Sub (statement) A-Z Reference

Sub...End Sub (statement)

Declares a subroutine.

Syntax
[Private | Public] [Static] Sub name[(arglist)]
[statements]
End Sub

Where arglist is a comma-separated list of the following (up to 30 arguments are

allowed):
[Optional] [ByVal | ByRef] parameter[()] [As type]

Description
The Sub statement has the following parameters:

Private Indicates that the subroutine being defined cannot be

called from other procedures.

Public Indicates that the subroutine being defined can be called

from other procedures. If the Private and Public keywords
are both missing, then Public is assumed.

Static Recognized by the compiler but currently has no effect.

name Name of the subroutine, which must follow Docbasic

naming conventions:
1. Must start with a letter.
2. May contain letters, digits, and the underscore
character (_). Punctuation and type-declaration characters
are not allowed. The exclamation point (!) can appear
within the name as long as it is not the last character.
3. Must not exceed 80 characters in length.

Optional Keyword indicating that the parameter is optional. All

optional parameters must be of type Variant. Furthermore,
all parameters that follow the first optional parameter must
also be optional.

If this keyword is omitted, then the parameter is required.

Note: You can use the IsMissing function to determine if an optional

parameter was actually passed by the caller.

3-462 Docbasic User’s Guide

A-Z Reference Sub...End Sub (statement)

ByVal Keyword indicating that the parameter is passed by value.

ByRef Keyword indicating that the parameter is passed by reference. If neither

the ByVal nor the ByRef keyword is given, then ByRef is assumed.

parameter Name of the parameter, which must follow the same naming conventions
as those used by variables. This name can include a type-declaration
character, appearing in place of As type.

type Type of the parameter (i.e., Integer, String, and so on). Arrays are
indicated with parentheses. For example, an array of integers would be
declared as follows:

Sub Test(a() As Integer)

End Sub

A subroutine terminates when one of the following statements is encountered:

End Sub
Exit Sub

Subroutines can be recursive.

Passing Parameters to Subroutines

Parameters are passed to a subroutine either by value or by reference, depending

on the declaration of that parameter in arglist. If the parameter is declared using
the ByRef keyword, then any modifications to that passed parameter within the
subroutine change the value of that variable in the caller. If the parameter is
declared using the ByVal keyword, then the value of that variable cannot be
changed in the called subroutine. If neither the ByRef or ByVal keywords are
specified, then the parameter is passed by reference.

You can override passing a parameter by reference by enclosing that parameter

within parentheses. For instance, the following example passes the variable j by
reference, regardless of how the third parameter is declared in the arglist of
UserSub:
UserSub 10,12,(j)

Optional Parameters

Docbasic allows you to skip parameters when calling subroutines, as shown in the
following example:
Sub Test(a%,b%,c%)
End Sub

Sub Main
Test 1,,4'Parameter 2 was skipped.
End Sub

You can skip any parameter with the following restrictions:

Docbasic User’s Guide 3-463

Sub...End Sub (statement) A-Z Reference

The call cannot end with a comma. For instance, using the above example,
the following is not valid:
Test 1,,

The call must contain the minimum number of parameters as required by

the called subroutine. For instance, using the above example, the following
are invalid:
Test ,1Only passes two out of three required parameters.

Test 1,2Only passes two out of three required parameters.

When you skip a parameter in this manner, Docbasic creates a temporary variable
and passes this variable instead. The value of this temporary variable depends on
the data type of the corresponding parameter in the argument list of the called
subroutine, as described in the following table:

Table 3-78 Default Values for Skipped Parameters

Value Data type

0 Integer, Long, Single, Double, Currency

Zero-length string String

Nothing Object (or any data object)

Error Variant

December 30, 1899 Date

False Boolean

Within the called subroutine, you will be unable to determine if a parameter was
skipped unless the parameter was declared as a variant in the argument list of the
subroutine. In this case, you can use the IsMissing function to determine if the
parameter was skipped:
Sub Test(a,b,c)
If IsMissing(a) Or IsMissing(b) Then Exit Sub
End Sub

Example
This example uses a subroutine to calculate the area of a circle.
Sub Main()
r! = 10
PrintArea r!
End Sub

Sub PrintArea(r as single)

area! = (r! ^ 2) * Pi
MsgBox "The area of a circle with radius " & r! & " = " & area!
End Sub

3-464 Docbasic User’s Guide

A-Z Reference Sub...End Sub (statement)

Platform(s)
All.

See Also
Main (keyword)
Function...End Function (statement)

Docbasic User’s Guide 3-465

Switch (function) A-Z Reference

Switch (function)

Returns the expression corresponding to the first True condition.

Syntax
Switch(condition1,expression1 [,condition2,expression2 ...
[,condition7,expression7]])

Description
The Switch function evaluates each condition and expression, returning the
expression that corresponds to the first condition (starting from the left) that
evaluates to True. Up to seven condition/expression pairs can be specified.

A runtime error is generated it there is an odd number of parameters (i.e., there is

a condition without a corresponding expression).

The Switch function returns Null if no condition evaluates to True.

Example
The following code fragment displays the current operating platform. If the
platform is unknown, then the word "Unknown" is displayed.
Sub Main()
Dim a As Variant
a = Switch(Basic.OS = 0,"Windows 3.1",Basic.OS = 2,"Win32")
MsgBox "The current platforms is: " & IIf(IsNull(a),"Unknown",a)
End Sub

Platform(s)
All.

See Also
Choose (function)
IIf (function)
If...Then...Else (statement)
Select...Case (statement)

3-466 Docbasic User’s Guide

A-Z Reference SYD (function)

SYD (function)

Returns the sum of years' digits depreciation of an asset over a specific period of
time.

Syntax
SYD(Cost,Salvage,Life,Period)

Description
The SYD of an asset is found by taking an estimate of its useful life in years,
assigning values to each year, and adding up all the numbers.

The formula used to find the SYD of an asset is as follows:

(Cost - Salvage_Value) * Remaining_Useful_Life / SYD

The SYD function requires the following parameters:

Cost Double representing the initial cost of the asset.

Salvage Double representing the estimated value of the asset at the

end of its useful life.

Life Double representing the length of the asset's useful life.

Period Double representing the period for which the depreciation

is to be calculated. It cannot exceed the life of the asset.

To receive accurate results, the parameters Life and Period must be expressed in the
same units. If Life is expressed in terms of months, for example, then Period must
also be expressed in terms of months.

Example
In this example, an asset that cost $1,000.00 is depreciated over ten years. The
salvage value is $100.00, and the sum of the years' digits depreciation is shown for
each year.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
For x = 1 To 10
dep# = SYD(1000,100,10,x)
msg = msg & "Year: " & x & " Dep: " & Format(dep#,"Currency") &
crlf

Docbasic User’s Guide 3-467

SYD (function) A-Z Reference

Next x
MsgBox msg
End Sub

Platform(s)
All.

See Also
Sln (function)
DDB (function)

3-468 Docbasic User’s Guide

A-Z Reference Tab (function)

Tab (function)

Prints the number of spaces necessary to reach a given column position.

Syntax
Tab (column)

Description
This function can only be used with the Print and Print# statements.

The column parameter is an Integer specifying the desired column position to

which to advance. It can be any value between 0 and 32767 inclusive.

Rule 1: If the current print position is less than or equal to column, then the number
of spaces is calculated as:
column - print_position

Rule 2: If the current print position is greater than column, then column - 1 spaces
are printed on the next line.

If a line width is specified (using the Width statement), then the column position is
adjusted as follows before applying the above two rules:
column = column Mod width

The Tab function is useful for making sure that output begins at a given column
position, regardless of the length of the data already printed on that line.

Example
This example prints three column headers and three numbers aligned below the
column headers.
Sub Main()
Print "Column1";Tab(10);"Column2";Tab(20);"Column3"
Print Tab(3);"1";Tab(14);"2";Tab(24);"3"
Sleep(10000)'Wait 10 seconds.
End Sub

Platform(s)
All.

Docbasic User’s Guide 3-469

Tab (function) A-Z Reference

See Also
Spc (function)
Print (statement)
Print# (statement)

3-470 Docbasic User’s Guide

A-Z Reference Tan (function)

Tan (function)

Returns a Double representing the tangent of angle.

Syntax
Tan(angle)

Description
The angle parameter is a Double value given in radians.

Example
This example computes the tangent of pi/4 radians (45 degrees).
Sub Main()
c# = Tan(Pi / 4)
MsgBox "The tangent of 45 degrees is: " & c#
End Sub

Platform(s)
All.

See Also
Sin (function)
Cos (function)
Atn (function)

Docbasic User’s Guide 3-471

Time, Time$ (functions) A-Z Reference

Time, Time$ (functions)

Returns the system time as a String or as a Date variant.

Syntax
Time[$][()]

Description
The Time$ function returns a string that contains the time in a 24-hour time format,
whereas Time returns a Date variant.

To set the time, use the Time/Time$ statements.

Example
This example returns the system time and displays it in a dialog box.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
oldtime$ = Time$
msg = "Time was: " & oldtime$ & crlf
Time$ = "10:30:54"
msg = msg & "Time set to: " & Time$ & crlf
Time$ = oldtime$
msg = msg & "Time restored to: " & Time$
MsgBox msg
End Sub

Platform(s)
All.

See Also
Time, Time$ (statements)
Date, Date$ (functions)
Date, Date$ (statements)
Now (function)

3-472 Docbasic User’s Guide

A-Z Reference Time, Time$ (statements)

Time, Time$ (statements)

Sets the system time to the time contained in the specified string.

Syntax
Time[$] = newtime

Description
The Time$ statement requires a string variable in one of the following formats:

HH
HH:MM
HH:MM:SS

where HH is between 0 and 23, MM is between 0 and 59, and SS is between 0 and
59.

The Time statement converts any valid expression to a time, including string and
numeric values. Unlike the Time$ statement, Time recognizes many different time
formats, including 12-hour times.

Example
This example returns the system time and displays it in a dialog box.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
oldtime$ = Time$
msg = "Time was: " & oldtime$ & crlf
Time$ = "10:30:54"
msg = msg & "Time set to: " & Time$ & crlf
Time$ = oldtime$
msg = msg & "Time restored to: " & Time$
MsgBox msg
End Sub

Platform(s)
All.

Docbasic User’s Guide 3-473

Time, Time$ (statements) A-Z Reference

Platform Notes: UNIX, Win32

On all UNIX and Win32 platforms, you may not have permission to change the
time, causing runtime error 70 to be generated.

See Also
Time, Time$ (functions)
Date, Date$ (functions)
Date, Date$ (statements)

3-474 Docbasic User’s Guide

A-Z Reference Timer (function)

Timer (function)

Returns a Single representing the number of seconds that have elapsed since
midnight.

Syntax
Timer

Example
This example displays the elapsed time between execution start and the time you
clicked the OK button on the first message.
Sub Main()
start& = Timer
MsgBox "Click the OK button, please."
total& = Timer - start&
MsgBox "The elapsed time was: " & total& & " seconds."
End Sub

Platform(s)
All.

See Also
Time, Time$ (functions)
Now (function)

Docbasic User’s Guide 3-475

TimeSerial (function) A-Z Reference

TimeSerial (function)

Returns a Date variant representing the given time with a date of zero.

Syntax
TimeSerial(hour,minute,second)

Description
The TimeSerial function requires the following parameters:

hour Integer between 0 and 23.

minute Integer between 0 and 59.

second Integer between 0 and 59.

Example
Sub Main()
start# = TimeSerial(10,22,30)
finish# = TimeSerial(10,35,27)
dif# = Abs(start# - finish#)
MsgBox "The time difference is: " & Format(dif#, "hh:mm:ss")
End Sub

Platform(s)
All.

See Also
DateValue (function)
TimeValue (function)
DateSerial (function)

3-476 Docbasic User’s Guide

A-Z Reference TimeValue (function)

TimeValue (function)

Returns a Date variant representing the time contained in the specified string
argument.

Syntax
TimeValue(time_string$)

Description
This function interprets the time_string$ parameter looking for a valid time
specification.

The time_string$ parameter can contain valid time items separated by time
separators such as colon (:) or period (.).

Time strings can contain an optional date specification, but this is not used in the
formation of the returned value.

If a particular time item is missing, then it is set to 0. For example, the string "10
pm" would be interpreted as "22:00:00."

Example
This example calculates the TimeValue of the current time and displays it in a
dialog box.
Sub Main()
t1$ = "10:15"
t2# = TimeValue(t1$)
MsgBox "The TimeValue of " & t1$ & " is: " & t2#
End Sub

Platform(s)
All.

Platform Notes: Windows

Under Windows, time specifications vary, depending on the international settings
contained in the [intl] section of the win.ini file.

Docbasic User’s Guide 3-477

TimeValue (function) A-Z Reference

See Also
DateValue (function)
TimeSerial (function)
DateSerial (function)

3-478 Docbasic User’s Guide

A-Z Reference Trim, Trim$ (functions)

Trim, Trim$ (functions)

Returns a copy of the passed string expression (text) with leading and trailing
spaces removed.

Syntax
Trim[$](text)

Description
Trim$ returns a String, whereas Trim returns a String variant.

Null is returned if text is Null.

Example
This example uses the Trim$ function to extract the nonblank part of a string and
display it.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
text$ = " This is text "
tr$ = Trim$(text$)
MsgBox "Original =>" & text$ & "<=" & crlf & "Trimmed =>" & tr$ & "<="
End Sub

Platform(s)
All.

See Also
LTrim, LTrim$ (functions)
RTrim, RTrim$ (functions)

Docbasic User’s Guide 3-479

True (constant) A-Z Reference

True (constant)

Boolean constant whose value is True. Used in conditionals and Boolean

expressions.

Example
This example sets variable a to True and then tests to see whether (1) A is True; (2)
the True constant = -1; and (3) A is equal to -1 (True).
Sub Main()
a = True
If ((a = True) and (True = -1) and (a = -1)) then
MsgBox "a is True."
Else
MsgBox "a is False."
End If
End Sub

Platform(s)
All.

See Also
False (constant)
Constants (topic)
Boolean (data type)

3-480 Docbasic User’s Guide

A-Z Reference Type (statement)

Type (statement)

The Type statement creates a structure definition that can then be used with the
Dim statement to declare variables of that type. The username field specifies the
name of the structure that is used later with the Dim statement.

Syntax
Type username
variable As type
variable As type
variable As type
End Type

Description
Within a structure definition appear field descriptions in the format:
variable As type

where variable is the name of a field of the structure, and type is the data type for
that variable. Any fundamental data type or previously declared user-defined data
type can be used within the structure definition (structures within structures are
allowed). Only fixed arrays can appear within structure definitions.

The Type statement can only appear outside of subroutine and function
declarations.

When declaring strings within fixed-size types, it is useful to declare the strings as
fixed-length. Fixed-length strings are stored within the structure itself rather than
in the string space. For example, the following structure will always require 62
bytes of storage:
Type Person
FirstName As String * 20
LastName As String * 40
Age As Integer
End Type

Note: Fixed-length strings within structures are size-adjusted upward to an even

byte boundary. Thus, a fixed-length string of length 5 will occupy 6 bytes of storage
within the structure.

Example
This example displays the use of the Type statement to create a structure
representing the parts of a circle and assign values to them.
Type Circ

Docbasic User’s Guide 3-481

Type (statement) A-Z Reference

msg As String
rad As Integer
dia As Integer
are As Double
cir As Double
End Type

Sub Main()
Dim circle As Circ
circle.rad = 5
circle.dia = circle.rad * 2
circle.are = (circle.rad ^ 2) * Pi
circle.cir = circle.dia * Pi
circle.msg = "The area of the circle is: " & circle.are
MsgBox circle.msg
End Sub

Platform(s)
All.

See Also
Dim (statement)
Public (statement)
Private (statement)

3-482 Docbasic User’s Guide

A-Z Reference UBound (function)

UBound (function)

Returns an Integer containing the upper bound of the specified dimension of the
specified array variable.

Syntax
UBound(ArrayVariable() [,dimension])

Description
The dimension parameter is an integer that specifies the desired dimension. If not
specified, then the upper bound of the first dimension is returned.

The UBound function can be used to find the upper bound of a dimension of an
array returned by an OLE automation method or property:
UBound(object.property [,dimension])

UBound(object.method [,dimension])

Example
This example dimensions two arrays and displays their upper bounds.
Sub Main()
Dim a(5 To 12)
Dim b(2 To 100, 9 To 20)
uba = UBound(a)
ubb = UBound(b,2)
MsgBox "The upper bound of a is: " & uba & " The upper bound of b is: "
& ubb

This example uses Lbound and Ubound to dimension a dynamic array to hold a
copy of an array redimmed by the FileList statement.
Dim fl$()
FileList fl$,"*"
count = Ubound(fl$)
If ArrayDims(a) Then
Redim nl$(Lbound(fl$) To Ubound(fl$))
For x = 1 To count
nl$(x) = fl$(x)
Next x
MsgBox "The last element of the new array is: " & nl$(count)
End If
End Sub

Docbasic User’s Guide 3-483

UBound (function) A-Z Reference

Platform(s)
All.

See Also
LBound (function)
ArrayDims (function)
Arrays (topic)

3-484 Docbasic User’s Guide

A-Z Reference UCase, UCase$ (functions)

UCase, UCase$ (functions)

Returns the uppercase equivalent of the specified string.

Syntax
UCase[$](text)

Description
UCase$ returns a String, whereas UCase returns a String variant.

Null is returned if text is Null.

Example
This example uses the UCase$ function to change a string from lowercase to
uppercase.
Sub Main()
a1$ = "this string was lowercase, but was converted."
a2$ = UCase$(a1$)
MsgBox a2$
End Sub

Platform(s)
All.

See Also
LCase, LCase$ (functions)

Docbasic User’s Guide 3-485

Unlock (statement) A-Z Reference

Unlock (statement)

Unlocks a section of the specified file, allowing other processes access to that
section of the file.

Syntax
Unlock [#] filenumber [,{record | [start] To end}]

Description
The Unlock statement requires the following parameters:

filenumber Integer used by Docbasic to refer to the open file—the

number passed to the Open statement.

record Long specifying which record to unlock.

start Long specifying the first record within a range to be

unlocked.

end Long specifying the last record within a range to be

unlocked.

For sequential files, the record, start, and end parameters are ignored: the entire file
is unlocked.

The section of the file is specified using one of the following:

No record Unlock the entire file.

specification

record Unlock the specified record number (for Random files) or

byte (for Binary files).

to end Unlock from the beginning of the file to the specified

record (for Random files) or byte (for Binary files).

start to end Unlock the specified range of records (for Random files) or
bytes (for Binary files).

The unlock range must be the same as that used by the Lock statement.

3-486 Docbasic User’s Guide

A-Z Reference Unlock (statement)

Example
This example creates a file named test.dat and fills it with ten string variable
records. These are displayed in a dialog box. The file is then reopened for read/
write, and each record is locked, modified, rewritten, and unlocked. The new
records are then displayed in a dialog box.
Const crlf = Chr$(13) + Chr$(10)

Sub Main()
a$ = "This is record number: "
b$ = "0"
rec$ = ""

msg = ""
Open "test.dat" For Random Access Write Shared As #1
For x = 1 To 10
rec$ = a$ & x
Lock #1,x
Put #1,,rec$
Unlock #1,x
msg = msg & rec$ & crlf
Next x
Close
MsgBox "The records are: " & crlf & msg

msg = ""
Open "test.dat" For Random Access Read Write Shared As #1
For x = 1 to 10
rec$ = Mid$(rec$,1,23) & (11 - x)
Lock #1,x 'Lock it for our use.
Put #1,x,rec$'Nobody's changed it.
UnLock #1,x
msg = msg & rec$ & crlf
Next x
MsgBox "The records are: " & crlf & msg
Close

Kill "test.dat"
End Sub

Platform(s)
All.

Platform Notes: Macintosh

On the Macintosh, file locking will only succeed on volumes that are shared (i.e.,
file sharing is on).

Docbasic User’s Guide 3-487

Unlock (statement) A-Z Reference

Platform Notes: UNIX

Under all versions of UNIX, file locking is ignored.

See Also
Lock (statement)
Open (statement)

3-488 Docbasic User’s Guide

A-Z Reference User-Defined Types (topic)

User-Defined Types (topic)

User-defined types (UDTs) are structure definitions created using the Type
statement. UDTs are equivalent to C language structures.

Declaring Structures
The Type statement is used to create a structure definition. Type declarations must
appear outside the body of all subroutines and functions within a procedure and
are therefore global to an entire procedure.

Once defined, a UDT can be used to declare variables of that type using the Dim,
Public, or Private statement. The following example defines a rectangle structure:
Type Rect
left As Integer
top As Integer
right As Integer
bottom As Integer
End Type
:
Sub Main()
Dim r As Rect
:
r.left = 10
End Sub

Any fundamental data type can be used as a structure member, including other
user-defined types. Only fixed arrays can be used within structures.

Copying Structures
UDTs of the same type can be assigned to each other, copying the contents. No
other standard operators can be applied to UDTs.
Dim r1 As Rect
Dim r2 As Rect
:
r1 = r2

When copying structures of the same type, all strings in the source UDT are
duplicated and references are placed into the target UDT.

The LSet statement can be used to copy a UDT variable of one type to another:
LSet variable1 = variable2

LSet cannot be used with UDTs containing variable-length strings. The smaller of
the two structures determines how many bytes get copied.

Docbasic User’s Guide 3-489

User-Defined Types (topic) A-Z Reference

Passing Structures
UDTs can be passed both to user-defined routines and to external routines, and
they can be assigned. UDTs are always passed by reference.

Since structures are always passed by reference, the ByVal keyword cannot be used
when defining structure arguments passed to external routines (using Declare).
The ByVal keyword can only be used with fundamental data types such as Integer
and String.

Passing structures to external routines actually passes a far pointer to the data
structure.

Size of Structures
The Len function can be used to determine the number of bytes occupied by a UDT:
Len(udt_variable_name)

Since strings are stored in Docbasic's data space, only a reference (currently, 2
bytes) is stored within a structure. Thus, the Len function may seem to return
incorrect information for structures containing strings.

3-490 Docbasic User’s Guide

A-Z Reference Val (function)

Val (function)

Converts a given string expression to a number.

Syntax
Val(number)

Description
The number parameter can contain any of the following:

Leading minus sign (for nonhex or octal numbers only)

Hexadecimal number in the format &Hhexdigits

Octal number in the format &Ooctaldigits

Floating-point number, which can contain a decimal point and an optional
exponent

Spaces, tabs, and line feeds are ignored.

If number does not contain a number, then 0 is returned.

The Val function continues to read characters from the string up to the first
nonnumeric character.

The Val function always returns a double-precision floating-point value. This

value is forced to the data type of the assigned variable.

Example
This example inputs a number string from an InputBox and converts it to a number
variable.
Sub Main()
a$ = InputBox$("Enter anything containing a number","Enter Number")
b# = Val(a$)
MsgBox "The value is: " & b#
End Sub

The following table shows valid strings and their numeric equivalents:
' "1 2 3"123
' "12.3"12.3
' "&HFFFF"-1
' "&O77"63
' "12.345E-02".12345

Docbasic User’s Guide 3-491

Val (function) A-Z Reference

Platform(s)
All.

See Also
CDbl (function)
Str, Str$ (functions)

3-492 Docbasic User’s Guide

A-Z Reference Variant (data type)

Variant (data type)

A data type used to declare variables that can hold one of many different types of
data.

Syntax
Variant

Description
During a variant's existence, the type of data contained within it can change.
Variants can contain any of the following types of data:

Table 3-79 Variant Data Types

Type of Data Docbasic Data Types

Numeric Integer, Long, Single, Double, Boolean, Date, Currency.

Logical Boolean.

Dates and times Date.

String String.

Object Object.

No valid data A variant with no valid data is considered Null.

Uninitialized An uninitialized variant is considered Empty.

There is no type-declaration character for variants.

The number of significant digits representable by a variant depends on the type of

data contained within the variant.

Variant is the default data type for Docbasic. If a variable is not explicitly declared
with Dim, Public, or Private, and there is no type-declaration character (i.e., #, @, !,
%, or &), then the variable is assumed to be Variant.

Determining the Subtype of a Variant

The following functions are used to query the type of data contained within a
variant:

Docbasic User’s Guide 3-493

Variant (data type) A-Z Reference

Table 3-80 Functions for Determining the Data Type of a Variant

Function Description

VarType Returns a number representing the type of data contained within the
variant.

IsNumeric Returns True if a variant contains numeric data. The following are
considered numeric:

Integer, Long, Single, Double, Date, Boolean,Currency

If a variant contains a string, this function returns True if the string can be
converted to a number.

If a variant contains an Object whose default property is numeric, then

IsNumeric returns True.

IsObject Returns True if a variant contains an object.

IsNull Returns True if a variant contains no valid data.

IsEmpty Returns True if a variant is uninitialized.

IsDate Returns True if a variant contains a date. If the variant contains a string,
then this function returns True if the string can be converted to a date. If
the variant contains an Object, then this function returns True if the
default property of that object can be converted to a date.

Assigning to Variants
Before a Variant has been assigned a value, it is considered empty. Thus,
immediately after declaration, the VarType function will return ebEmpty. An
uninitialized variant is 0 when used in numeric expressions and is a zero-length
string when used within string expressions.

A Variant is Empty only after declaration and before assigning it a value. The only
way for a Variant to become Empty after having received a value is for that variant
to be assigned to another Variant containing Empty, for it to be assigned explicitly
to the constant Empty, or for it to be erased using the Erase statement.

When a variant is assigned a value, it is also assigned that value's type. Thus, in all
subsequent operations involving that variant, the variant will behave like the type
of data it contains.

Operations on Variants
Normally, a Variant behaves just like the data it contains. One exception to this rule
is that, in arithmetic operations, variants are automatically promoted when an
overflow occurs. Consider the following statements:
Dim a As Integer,b As Integer,c As Integer
Dim x As Variant,y As Variant,z As Variant

3-494 Docbasic User’s Guide

A-Z Reference Variant (data type)

a% = 32767
b% = 1
c% = a% + b%'This will overflow.

x = 32767
y = 1
z = x + y 'z becomes a Long because of Integer overflow.

In the above example, the addition involving Integer variables overflows because
the result (32768) overflows the legal range for integers. With Variant variables, on
the other hand, the addition operator recognizes the overflow and automatically
promotes the result to a Long.

Adding Variants
The + operator is defined as performing two functions: when passed strings, it
concatenates them; when passed numbers, it adds the numbers.

With variants, the rules are complicated because the types of the variants are not
known until execution time. If you use +, you may unintentionally perform the
wrong operation.

It is recommended that you use the & operator if you intend to concatenate two
String variants. This guarantees that string concatenation will be performed and
not addition.

Variants That Contain No Data

A Variant can be set to a special value indicating that it contains no valid data by
assigning the Variant to Null:
Dim a As Variant
a = Null

The only way that a Variant becomes Null is if you assign it as shown above.

The Null value can be useful for catching errors since its value propagates through
an expression.

Variant Storage
Variants require 16 bytes of storage internally:

A 2-byte type

A 2-byte extended type for data objects

4 bytes of padding for alignment

An 8-byte value

Docbasic User’s Guide 3-495

Variant (data type) A-Z Reference

Unlike other data types, writing variants to Binary or Random files does not write
16 bytes. With variants, a 2-byte type is written, followed by the data (2 bytes for
Integer and so on).

Disadvantages of Variants
The following are some disadvantages of variants:

Using variants is slower than using the other fundamental data types (i.e.,
Integer, Long, Single, Double, Date, Object, String, Currency, and Boolean).
Each operation involving a Variant requires examination of the variant's
type.

Variants require more storage than other data types (16 bytes as opposed to
8 bytes for a Double, 2 bytes for an Integer, and so on).

Unpredictable behavior. You may write code to expect an Integer variant. At
runtime, the variant may be automatically promoted to a Long variant,
causing your code to break.

Passing Nonvariant Data to Routines Taking Variants

Passing nonvariant data to a routine that is declared to receive a variant by
reference prevents that variant from changing type within that routine. For
example:
Sub Foo(v As Variant)
v = 50 'OK.
v = "Hello, world."'Get a type-mismatch error here!
End Sub

Sub Main()
Dim i As Integer
Foo i 'Pass an integer by reference.
End Sub

In the above example, since an Integer is passed by reference (meaning that the
caller can change the original value of the Integer), the caller must ensure that no
attempt is made to change the variant's type.

Passing Variants to Routines Taking Nonvariants

Variant variables cannot be passed to routines that accept nonvariant data by
reference, as demonstrated in the following example:
Sub Foo(i as Integer)
End Sub

Sub Main()
Dim a As Variant
Foo a 'Compiler gives type-mismatch error here.
End Sub

3-496 Docbasic User’s Guide

A-Z Reference Variant (data type)

Platform(s)
All.

See Also
Boolean (data type)
Currency (data type)
Date (data type)
Double (data type)
Integer (data type)
Long (data type)
Object (data type)
Single (data type)
String (data type)
DefType (statement)
CVar (function)
Empty (constant)
Null (constant)
VarType (function)

Docbasic User’s Guide 3-497

VarType (function) A-Z Reference

VarType (function)

Returns an Integer representing the type of data in variable.

Syntax
VarType(variable)

Description
The variable parameter is the name of any Variant.

The following table shows the different values that can be returned by VarType:

Table 3-81 VarType Return Values

Value Constant Data Type

0 ebEmpty Uninitialized

1 ebNull No valid data

2 ebInteger Integer

3 ebLong Long

4 ebSingle Single

5 ebDouble Double

6 ebCurrency Currency

7 ebDate Date

8 ebString String

9 ebObject Object (OLE automation object)

10 ebError User-defined error

11 ebBoolean Boolean

12 ebVariant Variant (not returned by this function)

13 ebDataObject Non-OLE automation object

3-498 Docbasic User’s Guide

A-Z Reference VarType (function)

Comments
When passed an object, the VarType function returns the type of the default
property of that object. If the object has no default property, then either ebObject or
ebDataObject is returned, depending on the type of variable.

Example
Sub Main()
Dim v As Variant
v = 5& 'Set v to a Long.

If VarType(v) = ebInteger Then

Msgbox "v is an Integer."
ElseIf VarType(v) = ebLong Then
Msgbox "v is a Long."
End If
End Sub

Platform(s)
All.

See Also
Empty (constant)
Null (constant)
Variant (data type)

Docbasic User’s Guide 3-499

Weekday (function) A-Z Reference

Weekday (function)

Returns an Integer value representing the day of the week given by date. Sunday is
1, Monday is 2, and so on.

Syntax
Weekday(date)

Description
The date parameter is any expression representing a valid date.

Example
This example gets a date in an input box and displays the day of the week and its
name for the date entered.
Sub Main()
Dim a$(7)
a$(1) = "Sunday"
a$(2) = "Monday"
a$(3) = "Tuesday"
a$(4) = "Wednesday"
a$(5) = "Thursday"
a$(6) = "Friday"
a$(7) = "Saturday"

Reprompt:
bd = InputBox$("Please enter your birthday.","Enter Birthday")
If Not(IsDate(bd)) Then Goto Reprompt

dt = DateValue(bd)
dw = WeekDay(dt)
Msgbox "You were born on day " & dw & ", which was a " & a$(dw)
End Sub

Platform(s)
All.

See Also
Day (function)
Minute (function)
Second (function)

3-500 Docbasic User’s Guide

A-Z Reference Weekday (function)

Month (function)
Year (function)
Hour (function)
DatePart (function)

Docbasic User’s Guide 3-501

While...Wend (statement) A-Z Reference

While...Wend (statement)

Repeats a statement or group of statements while a condition is True.

Syntax
While condition
[statements]
Wend

Description
The condition is initially and then checked at the top of each iteration through the
loop.

Example
This example executes a While loop until the random number generator returns a
value of 1.
Sub Main()
x% = 0
count% = 0
While x% <> 1 And count% < 500
x% = Rnd(1)
If count% > 1000 Then
Exit Sub
Else
count% = count% + 1
End If
Wend
MsgBox "The loop executed " & count% & " times."
End Sub

Platform(s)
All.

Platform Notes: Windows, Win32

Due to errors in program logic, you can inadvertantly create infinite loops in your
code. Under Windows and Win32, you can break out of infinite loops using
Ctrl+Break.

3-502 Docbasic User’s Guide

A-Z Reference While...Wend (statement)

Platform Notes: UNIX

Due to errors in program logic, you can inadvertantly create infinite loops in your
code. Under UNIX, you can break out of infinite loops using Ctrl+C.

Platform Notes: Macintosh

Due to errors in program logic, you can inadvertantly create infinite loops in your
code. On the Macintosh, you can break out of infinite loops using
Command+Period.

See Also
Do...Loop (statement)
For...Next (statement)

Docbasic User’s Guide 3-503

Width# (statement) A-Z Reference

Width# (statement)

Specifies the line width for sequential files opened in either Output or Append
mode.

Syntax
Width# filenumber,newwidth

Description
The Width# statement requires the following parameters:

filenumber Integer used by Docbasic to refer to the open file—the

number passed to the Open statement.

newwidth Integer between 0 to 255 inclusive specifying the new

width. If newwidth is 0, then no maximum line length is
used.

When a file is initially opened, there is no limit to line length. This command forces
all subsequent output to the specified file to use the specified value as the
maximum line length.

The Width statement affects output in the following manner: if the column position
is greater than 1 and the length of the text to be written to the file causes the column
position to exceed the current line width, then the data is written on the next line.

The Width statement also affects output of the Print command when used with the
Tab and Spc functions.

Example
This statement sets the maximum line width for file number 1 to 80 columns.
Sub Main()
Width #1,80
End Sub

Platform(s)
All.

3-504 Docbasic User’s Guide

A-Z Reference Width# (statement)

See Also
Print (statement)
Print# (statement)
Tab (function)
Spc (function)

Docbasic User’s Guide 3-505

Word$ (function) A-Z Reference

Word$ (function)

Returns a String containing a single word or sequence of words between first and
last.

Syntax
Word$(text$,first[,last])

Description
The Word$ function requires the following parameters:

text$ String from which the sequence of words will be extracted.

first Integer specifing the index of the first word in the sequence
to return. If last is not specified, then only that word is
returned.

last Integer specifying the index of the last word in the

sequence to return. If last is specified, then all words
between first and last will be returned, including all spaces,
tabs, and end-of-lines that occur between those words.

Words are separated by any nonalphanumeric characters such as spaces, tabs, end-
of-lines, and punctuation.

If first is greater than the number of words in text$, then a zero-length string is
returned.

If last is greater than the number of words in text$, then all words from first to the
end of the text are returned.

Example
This example finds the name "Stuart" in a string and then extracts two words from
the string.
Sub Main()
s$ = "My last name is Williams; Stuart is my surname."
c$ = Word$(s$,5,6)
MsgBox "The extracted name is: " & c$
End Sub

3-506 Docbasic User’s Guide

A-Z Reference Word$ (function)

Platform(s)
All.

See Also
Item$ (function)
ItemCount (function)
Line$ (function)
LineCount (function)
WordCount (function)

Docbasic User’s Guide 3-507

WordCount (function) A-Z Reference

WordCount (function)

Returns an Integer representing the number of words in the specified text.

Syntax
WordCount(text$)

Description
Words are separated by spaces, tabs, and end-of-lines.

Example
This example counts the number of words in a particular string.
Sub Main()
s$ = "My last name is Williams; Stuart is my surname."
i% = WordCount(s$)
MsgBox "'" & s$ & "' has " & i% & " words."
End Sub

Platform(s)
All.

See Also
Item$ (function)
ItemCount (function)
Line$ (function)
LineCount (function)
Word$ (function)

3-508 Docbasic User’s Guide

A-Z Reference Write# (statement)

Write# (statement)

Writes a list of expressions to a given sequential file.

Syntax
Write [#]filenumber [,expressionlist]

Description
The file referenced by filenumber must be opened in either Output or Append
mode.

The filenumber parameter is an Integer used by Docbasic to refer to the open file—
the number passed to the Open statement.

The following summarizes how variables of different types are written:

Table 3-82 How Data Types are Written

Data Type Description

Any numeric type Written as text. There is no leading space, and the period is always used as
the decimal separator.

String Written as text, enclosed within quotes.

Empty No data is written.

Null Written as #NULL#.

Boolean Written as #TRUE# or #FALSE#.

Date Written using the universal date format:

#YYYY-MM-DD HH:MM:SS#

user-defined errors Written as #ERROR ErrorNumber#, where ErrorNumber is the value of

the user-defined error. The word ERROR is not translated.

The Write statement outputs variables separated with commas. After writing each
expression in the list, Write outputs an end-of-line.

The Write statement can only be used with files opened in Output or Append
mode.

Docbasic User’s Guide 3-509

Write# (statement) A-Z Reference

Example
This example opens a file for sequential write, then writes ten records into the file
with the values 10...50. Then the file is closed and reopened for read, and the
records are read with the Input statement. The results are displayed in a dialog box.
Sub Main()
Open "test.dat" For Output Access Write As #1
For x = 1 To 10
r% = x * 10
Write #1,x,r%
Next x
Close

Open "test.dat" For Input Access Read As #1

For x = 1 To 10
Input #1,a%,b%
msg = msg & "Record " & a% & ": " & b% & Basic.Eoln$
Next x

MsgBox msg
Close
End Sub

Platform(s)
All.

See Also
Open (statement)
Put (statement)
Print# (statement)

3-510 Docbasic User’s Guide

A-Z Reference WriteIni (statement)

WriteIni (statement)

Writes a new value into an ini file.

Syntax
WriteIni section$,ItemName$,value$[,filename$]

Description
The WriteIni statement requires the following parameters:

section$ String specifying the section that contains the desired

variables, such as "windows." Section names are specified
without the enclosing brackets.

ItemName$ String specifying which item from within the given section
you want to change. If ItemName$ is a zero-length string
(""), then the entire section specified by section$ is deleted.

value$ String specifying the new value for the given item. If value$
is a zero-length string (""), then the item specified by
ItemName$ is deleted from the ini file.

filename$ String specifying the name of the ini file.

Example
This example sets the txt extension to be associated with Notepad.
Sub Main()
WriteIni "Extensions","txt","c:\windows\notepad.exe ^.txt","win.ini"
End Sub

Platform(s)
Windows, Win32.

Platform Notes: Windows, Win32

Under Windows and Win32, if filename$ is not specified, the win.ini file is used.

If the filename$ parameter does not include a path, then this statement looks for ini
files in the Windows directory.

Docbasic User’s Guide 3-511

WriteIni (statement) A-Z Reference

See Also
ReadIni$ (function)
ReadIniSection (statement)

3-512 Docbasic User’s Guide

A-Z Reference Xor (operator)

Xor (operator)

Performs a logical or binary exclusion on two expressions.

Syntax
expression1 Xor expression2

Description
If both expressions are either Boolean, Boolean variants, or Null variants, then a
logical exclusion is performed as follows:

Table 3-83 Effect of Boolean, Boolean Variant, and Null Expressions on the Xor Operator

If the first expression is and the second expression is Then the result is

True True False

True False True

False True True

False False False

If either expression is Null, then Null is returned.

Binary Exclusion

If the two expressions are Integer, then a binary exclusion is performed, returning
an Integer result. All other numeric types (including Empty variants) are
converted to Long, and a binary exclusion is then performed, returning a Long
result.

Binary exclusion forms a new value based on a bit-by-bit comparison of the binary
representations of the two expressions according to the following table:

1 Xor 1 = 0

0 Xor 1 = 1

1 Xor 0 = 0

0 Zor 0 = 0

Example
This example builds a logic table for the XOR function and displays it.

Docbasic User’s Guide 3-513

Xor (operator) A-Z Reference

Sub Main()
For x = -1 To 0
For y = -1 To 0
z = x Xor y
msg = msg & Format(x,"True/False") & " Xor "
msg = msg & Format(y,"True/False") & " = "
msg = msg & Format(z,"True/False") & Basic.Eoln$
Next y
Next x
MsgBox msg
End Sub

Platform(s)
All.

See Also
Operator Precedence (topic)
Or (operator)
Eqv (operator)
Imp (operator); And (operator)

3-514 Docbasic User’s Guide

A-Z Reference Year (function)

Year (function)

Returns the year of the date encoded in the date parameter. The value returned is
between 100 and 9999 inclusive.

Syntax
Year(date)

Description
The date parameter is any expression representing a valid date.

Example
This example returns the current year in a dialog box.
Sub Main()
tdate$ = Date$
tyear! = Year(DateValue(tdate$))
MsgBox "The current year is: " & tyear$
End Sub

Platform(s)
All.

See Also
Day (function)
Minute (function)
Second (function)
Month (function)
Hour (function)
Weekday (function)
DatePart (function)

Docbasic User’s Guide 3-515

Year (function) A-Z Reference

3-516 Docbasic User’s Guide

 A Code Examples
This appendix contains two annotated code examples illustrating the use of
Docbasic. The first example shows how to perform certain actions such as
generating a PDF request and displaying the Attributes dialog box automatically
whenever a user checks in or imports a document. The second example shows how
to distribute files automatically from a centrally maintained docbase.

The final section of this appendix contains a listing of the files without annotations.

Docbasic User’s Guide A-1

Example 1: Checkin handler Code Examples

Example 1: Checkin handler

The code in this example automatically displays the Attributes dialog box
whenever a user checks in a document, and generates a PDF request whenever a
user checks in a document or imports a document. This ensures that users comply
with regulatory requirements that certain information to be on all documents, or a
company policy that requires all documents be stored in a company-wide readable
file format (.PDF).

This example is made up of two files, DEFINES.SCR and HANDLERS.EBS. The file
DEFINES.SCR should be the content of a dm_script object placed in the /
Workspace Customizations/Startup Items folder of a system, group, or user
cabinet. The file HANDLERS.EBS is the content of a dm_procedure object called
"Handlers" placed in /System/Test Docbasic Procedures. This object consists of
procedures written in Docbasic.

DEFINES.SCR File
The file DEFINES.SCR contains the Define method calls that redirect certain
methods to Docbasic procedures. These procedures are specified in
HANDLERS.EBS.

The following code tells Workspace to redirect the Checkindw method to the
Docbasic procedure checkindw_handler. The path to the file HANDLERS.EBS is
hard-coded. The checkindw_handler procedure runs whenever a user checks in a
document or other System Object.
define,c,dcapp,checkindw,*,basic,
'/System/Test Docbasic Procedures/Handlers',checkindw_handler

The following code tells Workspace to redirect the Import method to the Docbasic
procedure import_handler. The import_handler procedure runs whenever a user
imports a file from an external file system to a folder or cabinet.
define,c,dcapp,import,*,basic,
'/System/Test Docbasic Procedures/Handlers',import_handler

HANDLERS.EBS File
The file HANDLERS.EBS contains Docbasic procedures that process the
Checkindw and Import methods. These methods are redirected by the code in
DEFINES.SCR.

Checkindw_handler Procedure

The checkindw_handler procedure ensures that the Attributes dialog box is

always displayed before an object is checked in, and that a PDF request is

A-2 Docbasic User’s Guide

Code Examples Example 1: Checkin handler

automatically generated for most objects so that the user does not have to
specifically request a PDF rendition.

The following code begins the declaration of the checkindw_handler procedure.

The Mthd parameter passes the Checkindw method and its parameters into the
procedure.
Sub checkindw_handler (Mthd As String)

The following code assigns a descriptive name for the procedure to a variable so
that it can be displayed later in the procedure.
appname$ = "Checkin handler procedure"

The following code displays a message signaling the start of checkindw_handler.

msgbox "Starting the checkin handler procedure.",ebInformation,appname$

The following code gets the object ID of the object the user is checking in by
extracting the fourth item from the Mthd argument, which is the redirected
Checkindw method call. The function dmget_arg is declared later in this file.
oid$ = dmget_arg(Mthd, 4)

The following code determines what type of object is being checked in.
otype$ = dmAPIGet("get,c," & oid$ & ",r_object_type")

The following code lists the types of objects for which checkindw_handler will not
generate a PDF request.
notlist$ = "dm_script,dm_query,dm_router,dm_procedure"

The following code displays the Attributes dialog box so that the user can fill in the
attributes for this object before checking it in.
st% = dmAPIExec("attributes,c,dcapp," & oid$)

The following code returns the Checkindw method to Workspace to perform the
check-in.
newoid$ = dmAPIGet(Mthd)

The following code checks to see whether the previous dmAPIGet call returned a
valid object ID, which indicates that the import succeeded. Valid object IDs are 16
characters in length. If the object ID is not valid, the code assumes the user
cancelled the checkin, and checkindw_handler exits.
If Len(newoid$) <> 16 Then
msgbox "User cancelled the checkin.",ebInformation,appname$
End
End If

The following code checks to see whether the object is in notlist$, the list of objects
for which checkindw_handler will not generate a PDF request. If the object is in the
list, checkindw_handler exits.

Docbasic User’s Guide A-3

Example 1: Checkin handler Code Examples

If InStr(notlist$, otype$) > 0 Then

msgbox "Must be in the no PDF list",ebInformation,appname$
End
End If

The following code executes if the object is not in notlist$. The code prompts the
user to confirm whether they want a PDF rendition of the object.
r=msgbox("Would you like a PDF rendition for this document?" _
,ebYesNo or ebDefaultButton1 or ebQuestion,appname$)

The following code generates the PDF request if the user confirms that they would
like a PDF rendition.
if r = ebYes then
stamp$ = dmAPIGet("queue,c," & newoid$ & _
",dm_autorender_win31,no_real_message,5,F,,render_request_pdf")

The following code displays an error message if the return value from the previous
dmAPIGet call indicates that the code was unable to generate the PDF request.
If stamp$ = "" Then
MsgBox "Unable to queue the PDF request", ebInformation, appname$

The following code displays an informational message if the return value from
dmAPIGet indicates that the PDF request was generated.
else
msgbox "Your PDF request has been queued.",ebInformation,appname$
End If
End If

The following code ends the declaration of checkindw_handler.

End Sub

Import_handler Procedure

The import_handler procedure ensures that a PDF request is automatically

generated for most imported files so that the user does not have to specifically
request a PDF rendition.

The following code begins the declaration of the import_handler procedure. The
Mthd parameter passes the Import method and its parameters into the procedure.
Sub import_handler (Mthd As String)

The following code gets the object ID of the object the user is importing by
extracting the fourth item from the Mthd argument, which is the redirected Import
method call. The function dmget_arg is declared later in this file.
otype$ = dmget_arg(Mthd, 4)

The following code lists the types of objects for which import_handler will not
generate a PDF request.

A-4 Docbasic User’s Guide

Code Examples Example 1: Checkin handler

notlist$ = "dm_script,dm_query,dm_router,dm_procedure"

The following code returns the Import method to Workspace to perform its usual
tasks.
newoid$ = dmAPIGet(Mthd)

The following code checks to see whether the previous dmAPIGet call returned a
valid object ID. Valid object IDs are 16 characters in length. If the object ID is not
valid, the code assumes the user cancelled the import, and import_handler exits.
If Len(newoid$) <> 16 Then
End
End If

The following code checks to see whether the object is in notlist$, the list of objects
for which import_handler will not generate a PDF request. If the object is in the list,
import_handler exits.
If InStr(notlist$, otype$) > 0 Then
End
End If

The following code executes if the object is not in notlist$. The code prompts the
user to confirm whether they want a PDF rendition of the object.
r=msgbox("Would you like a PDF rendition for this document?" _
,ebYesNo or ebDefaultButton1 or ebQuestion,appname$)

The following code generates the PDF request if the user confirms that they would
like a PDF rendition.
if r = ebYes then
stamp$ = dmAPIGet("queue,c," & newoid$ & _
",dm_autorender_win31,no_real_message,5,F,,render_request_pdf")

The following code displays an error message if the return value from the previous
dmAPIGet call indicates that the code was unable to generate the PDF request.
If stamp$ = "" Then
MsgBox "Unable to queue the PDF request", ebInformation, appname$

The following code displays an informational message if the return value from
dmAPIGet indicates that the PDF request was generated.
else
msgbox "Your PDF request has been queued.",ebInformation,appname$
End If
End If

The following code ends the declaration of import_handler.

End Sub

Docbasic User’s Guide A-5

Example 1: Checkin handler Code Examples

Dmget_arg Procedure

The dmget_arg procedure returns a specified portion of a method call. It

accomplishes this by treating the method call as a comma-delimited string and
returning the substring beginning at a specified position.

The following code begins the declaration of the dmget_arg procedure. The method
parameter passes the method and its parameters into the procedure. The position
parameter specifies which portion of the method call to return. If position is 1,
dmget_arg will return the method name rather than an argument.
Function dmget_arg (method As String, position As Integer) As String
appname$ = "dmget_arg procedure"

The following code declares counters.

Dim finish as integer
Dim start as integer
Dim i as integer

The following code initializes the return value of the function to an empty string.
dmget_arg = ""

The following code initializes a counter.

start = 1

The following code defines a loop that will step through the method call,
identifying substrings until the counter equals the specified position.
For i = 1 To position
If (i > 1) Then
doevents
start=finish+2
End If
finish = InStr(start, method, ",")-1
If (finish = -1) Then
If i=position Then
dmget_arg=mid$(method, start)
Else
dmget_arg=""
End If
Exit Function
else
End If
next i
dmget_arg = mid$(method, start, finish-start+1)
End Function

A-6 Docbasic User’s Guide

Code Examples Example 2: File distribution

Example 2: File distribution

The code in this example automatically distributes files from a centrally

maintained docbase. This service is useful if you are customizing Workspace with
specialized applications or data files, such as .VRF and .SCR files, which need to be
updated regularly on a local machine. Use the code in this example to easily
distribute changes, such as to custom dialog boxes in a .VRF file.

This example is made up of two files, AUTODOWN.SCR and AUTODOWN.EBS.

The file AUTODOWN.SCR should be the content of a dm_script object placed in
the /Workspace Customizations/Startup Items folder of a system, group, or user
cabinet. The file AUTODOWN.EBS is the content of a dm_procedure object called
"Auto-Down" placed in /System/Docbasic Procedures. This object consists of
procedures written in Docbasic.

AUTODOWN.SCR File
The file AUTODOWN.SCR contains an Execute method call that runs a Docbasic
procedure. This procedure is specified in AUTODOWN.EBS.
execute,c,procedure,'/System/Docbasic Procedures/Auto-Down',main

AUTODOWN.EBS File
The file AUTODOWN.EBS contains a Docbasic procedure that automatically
downloads files from a docbase. This procedure is executed by the code in
AUTODOWN.SCR.

Main Procedure

The following code begins the declaration of the main procedure.

Sub Main(Mthd as string)

The following code assigns a descriptive name for the procedure to a variable so
that it can be displayed later in the procedure.
appname$ = "Auto-Downloader"

The following code declares a new variable that stores the End of Line and New
Line characters.
nl$ = chr$(10) & chr$(13)

The following code uses a query to get the objects in the /System/Auto-Down
folder.
query$ = "select r_object_id from dm_sysobject where _
"query$ = query$ & "folder('/System/Auto-Down')" _
colid$ = dmAPIGet("readquery,c," & query$)

Docbasic User’s Guide A-7

Example 2: File distribution Code Examples

The following code checks the Collection ID to make sure the query parsed
correctly. Valid Collection IDs are two characters long. If the query could not be
parsed, the procedure exits.
if len(colid$) <> 2 then
smsg$ = dmAPIGet("getmessage,c")
msgbox "Unable to query contents of Auto-Down:" + nl$ + _
smsg$,ebInformation,appname$
Exit Sub
end if

The following code begins a loop to download the files.

While dmAPIExec("next,c," & colid$)

The following code updates variables as each file is processed by the loop.
oid$ = dmAPIGet("get,c," & colid$ & ",r_object_id")
testfile$ = dmAPIGet("get,c," & oid$ & ",object_name")
testdate$ = dmAPIGet("get,c," & oid$ & ",r_modify_date")
mymsg = "Testing existence of: " & testfile$

The following code executes if the file was found on the user’s local drive. The
code checks to see whether the user’s local copy of the file is older than the version
found by the query in the docbase. If so, the code prompts the user to indicate
whether to download the newer version from the docbase. The code assumes that
the file is in the user’s current working directory.
If FileExists(testfile$) then
locfiledate# = FileDateTime(testfile$)
if datevalue(testdate$) > locfiledate# then
r = msgbox("Your local copy of " & testfile$ & " is old." & nl$_
& "Would you like to download the latest from the docbase?",_
ebYesNo or ebDefaultButton1 or ebQuestion ,appname$)

The following code downloads the file if the user requests it. The third End If
matches the If Datevalue statement in the previous code segment.
if r = ebYes then
msgsettext "downloading " & testfile$ & " now"
locf$ = dmAPIGet("getfile,c," & oid$ & "," & testfile$)
if len(locf$) = 0 then
msgbox "Error downloading " & testfile$,ebInformation,appname$
end if
end if
end if

The following code executes if the file was not found on the user’s local drive. The
code prompts the user to indicate whether to download the file from the docbase.
else
r = msgbox("You have no local copy of " & testfile$ & nl$ & _
"Would you like to download the latest from the docbase?",ebYesNo _
or ebDefaultButton1 or ebQuestion ,appname$)

A-8 Docbasic User’s Guide

Code Examples Example 2: File distribution

The following code downloads the file if the user requests it. The third End If
matches the If FileExists statement earlier in the code.
if r = ebYes then
locf$ = dmAPIGet("getfile,c," & oid$ & "," & testfile$)
if len(locf$) = 0 then
msgbox "Error downloading " & testfile$,ebInformation,appname$
end if
end if
End If

The following code marks the end of the loop that downloads files.
Wend

The following code closes the query results collection.

st% = dmAPIExec("close,c," & colid$)

The following code ends the declaration of the main procedure.

End Sub

Docbasic User’s Guide A-9

Code File Listings Code Examples

Code File Listings

DEFINES.SCR
define,c,dcapp,checkindw,*,basic,_
'/System/Test Docbasic Procedures/Handlers',checkindw_handler

define,c,dcapp,import,*,basic,_
'/System/Test Docbasic Procedures/Handlers',import_handler

HANDLERS.EBS
Sub checkindw_handler (Mthd As String)
appname$ = "Checkin handler procedure"
msgbox "Start checkin handler procedure",ebInformation,appname$
oid$ = dmget_arg(Mthd, 4)
otype$ = dmAPIGet("get,c," & oid$ & ",r_object_type")
notlist$ = "dm_script,dm_query,dm_router,dm_procedure"
st% = dmAPIExec("attributes,c,dcapp," & oid$)
newoid$ = dmAPIGet(Mthd)

If Len(newoid$) <> 16 Then

msgbox "User canceled checkin",ebInformation,appname$
End
End If

If InStr(notlist$, otype$) > 0 Then

msgbox "Must be in the no PDF list",ebInformation,appname$
End
End If

r=msgbox("Would you like a PDF rendition for this document?" _

,ebYesNo or ebDefaultButton1 or ebQuestion,appname$)
if r = ebYes then
stamp$ = dmAPIGet("queue,c," & newoid$ &_
",dm_autorender_win31,no_real_message,5,F,,render_request_pdf")
If stamp$ = "" Then
MsgBox "Unable to queue the PDF request", ebInformation, appname$
else
msgbox "Your PDF request has been queued.",ebInformation,appname$
End If
End if

End Sub

Sub import_handler (Mthd As String)

appname$ = "Import handler procedure"
otype$ = dmget_arg(Mthd, 4)
notlist$ = "dm_script,dm_query,dm_router,dm_procedure"
newoid$ = dmAPIGet(Mthd)

If Len(newoid$) <> 16 Then

End
End If

A-10 Docbasic User’s Guide

Code Examples Code File Listings

If InStr(notlist$, otype$) > 0 Then

End
End If

r=msgbox("Would you like a PDF rendition for this document?" _

,ebYesNo or ebDefaultButton1 or ebQuestion,appname$)
if r = ebYes then
stamp$ = dmAPIGet("queue,c," & newoid$ &_
",dm_autorender_win31,no_real_message,5,F,,render_request_pdf")
If stamp$ = "" Then
MsgBox "Unable to queue the PDF request", ebInformation, appname$
else
msgbox "Your PDF request has been queued.",ebInformation,appname$
End If
End if

End Sub

Function dmget_arg (method As String, position As Integer) As String

appname$ = "dmget_arg procedure"
Dim finish as integer
Dim start as integer
Dim i as integer
dmget_arg = ""
start = 1
For i = 1 To position
If (i > 1) Then
doevents
start=finish+2
End If
finish = InStr(start, method, ",")-1
If (finish = -1) Then
If i=position Then
dmget_arg=mid$(method, start)
Else
dmget_arg=""
End If
Exit Function
else
End If
next i
dmget_arg = mid$(method, start, finish-start+1)
End Function

Sub dmerror (msg$, getserr%, fatalerr%)

appname$ = "dmerror procedure"
nl$ = Chr$(13) & Chr$(10)
emsg$ = msg$
If getserr% Then
emsg$ = emsg$ & " Documentum Server says: " & nl$ & nl$ &_
dmAPIGet("getmessage,c")
End If
If fatalerr% Then
emsg$ = emsg$ & nl$ & "FATAL: This needs to be fixed first!"+ _
"Call support immediately."

Docbasic User’s Guide A-11

Code File Listings Code Examples

End If
MsgBox emsg$
If fatalerr% Then End
End Sub

AUTODOWN.SCR
execute,c,procedure,'/System/Docbasic Procedures/Auto-Down',main

AUTODOWN.EBS
Sub Main(method as string)
appname$ = "Auto-Downloader"
nl$ = chr$(10) & chr$(13)
query$ = "select r_object_id from dm_sysobject where"
query$ = query$ & "folder('/System/Auto-Down')"
colid$ = dmAPIGet("readquery,c," & query$)
if len(colid$) <> 2 then
smsg$ = dmAPIGet("getmessage,c")
msgbox "Unable to query contents of Auto-Down:" + nl$ +_
smsg$,ebInformation,appname$
Exit Sub
end if

While dmAPIExec("next,c," & colid$)

oid$ = dmAPIGet("get,c," & colid$ & ",r_object_id")
testfile$ = dmAPIGet("get,c," & oid$ & ",object_name")
testdate$ = dmAPIGet("get,c," & oid$ & ",r_modify_date")
mymsg = "Testing existence of: " & testfile$
If FileExists(testfile$) then
locfiledate# = FileDateTime(testfile$)
if datevalue(testdate$) > locfiledate# then
r = msgbox("Your local copy of " & testfile$ & " is old." &_
nl$ & "Would you like to download the latest from the"+ _
" docbase?",ebYesNo or ebDefaultButton1 or ebQuestion _
,appname$)
if r = ebYes then
msgsettext "downloading " & testfile$ & " now"
locf$ = dmAPIGet("getfile,c," & oid$ & "," & testfile$)
if len(locf$) = 0 then
msgbox "Error downloading " & _
testfile$,ebInformation,appname$
end if
end if
end if
else

r = msgbox("You have no local copy of " & testfile$ & nl$ &_
"Would you like to download the latest from the docbase?",_
ebYesNo or ebDefaultButton1 or ebQuestion ,appname$)
if r = ebYes then
locf$ = dmAPIGet("getfile,c," & oid$ & "," & testfile$)
if len(locf$) = 0 then
msgbox "Error downloading " &

A-12 Docbasic User’s Guide

Code Examples Code File Listings

testfile$,ebInformation,appname$
end if
end if
End If
Wend
st% = dmAPIExec("close,c," & colid$)
End Sub

Docbasic User’s Guide A-13

Code File Listings Code Examples

A-14 Docbasic User’s Guide

 B Runtime Error
Messages
This section contains listings of all the runtime errors. It is divided into two
subsections, the first describing errors messages compatible with "standard" Basic
as implemented by Microsoft Visual Basic and the second describing error
messages specific to Docbasic.

A few error messages contain placeholders which get replaced by the runtime
when forming the completed runtime error message. These placeholders appear in
the following list as the italicized word placeholder.

Docbasic User’s Guide B-1

Visual Basic Compatible Error Messages Runtime Error Messages

Visual Basic Compatible Error Messages

Table B-1 Visual Basic Compatible Error Messages

Error Number Error Message

3 Return without GoSub

5 Illegal procedure call

6 Overflow

7 Out of memory

9 Subscript out of range

10 This array is fixed or temporarily locked

11 Division by zero

13 Type mismatch

14 Out of string space

19 No Resume

20 Resume without error

26 Dialog needs End Dialog or push button

28 Out of stack space

35 Sub or Function not defined

48 Error in loading DLL

49 Bad DLL calling convention

51 Internal error

52 Bad file name or number

53 File not found

54 Bad file mode

55 File already open

57 Device I/O error

58 File already exists

59 Bad record length

61 Disk full

62 Input past end of file

63 Bad record number

64 Bad file name

B-2 Docbasic User’s Guide

Runtime Error Messages Visual Basic Compatible Error Messages

Table B-1 Visual Basic Compatible Error Messages

Error Number Error Message

67 Too many files

68 Device unavailable

70 Permission denied

71 Disk not ready

74 Can't rename with different drive

75 Path/File access error

76 Path not found

91 Object variable or With block variable not set

93 Invalid pattern string

94 Invalid use of Null

139 Only one user dialog may be up at any time

140 Dialog control identifier does not match any current control

141 The placeholder statement is not available on this dialog control type

163 This statement can only be used when a user dialog is active

260 No timer available

281 No more DDE channels

282 No foreign application responded to a DDE initiate

283 Multiple applications responded to a DDE initiate

285 Foreign application won't perform DDE method or operation

286 Timeout while waiting for DDE response

287 User pressed Escape key during DDE operation

288 Destination is busy

289 Data not provided in DDE operation

290 Data in wrong format

291 Foreign application quit

292 DDE conversation closed or changed

295 Message queue filled; DDE message lost

298 DDE requires ddeml.dll

429 OLE Automation server can't create object

430 Class doesn't support OLE Automation

431 OLE Automation server cannot load file

432 File name or class name not found during OLE Automation operation

Docbasic User’s Guide B-3

Visual Basic Compatible Error Messages Runtime Error Messages

Table B-1 Visual Basic Compatible Error Messages

Error Number Error Message

433 OLE Automation object does not exist

434 Access to OLE Automation object denied

435 OLE initialization error

436 OLE Automation method returned unsupported type

437 OLE Automation method did not return a value

438 Object doesn't support this property or method placeholder

439 OLE Automation argument type mismatch placeholder

440 OLE Automation error placeholder

443 OLE Automation Object does not have a default value

452 Invalid ordinal

460 Invalid Clipboard format

520 Can't empty clipboard

521 Can't open clipboard

600 Set value not allowed on collections

601 Get value not allowed on collections

B-4 Docbasic User’s Guide

Runtime Error Messages Docbasic-Specific Error Messages

Docbasic-Specific Error Messages

Table B-2 Docbasic-Specific Error Messages

Error Number Error Message

800 Incorrect Windows version

801 Too many dimensions

802 Can't find window

803 Can't find menu item

804 Another queue is being flushed

805 Can't find control

806 Bad channel number

807 Requested data not available

808 Can't create pop-up menu

809 Message box canceled

810 Command failed

816 Queue overflow

821 Can't write to ini file

822 Can't read from ini file

823 Can't copy file onto itself

824 OLE Automation unknown object name

825 Can't redimension a fixed array

826 Can't load and initialize extension

827 Can't find extension

828 Unsupported function or statement

830 OLE Automation Lbound or Ubound on non-Array value

Docbasic User’s Guide B-5

Docbasic-Specific Error Messages Runtime Error Messages

B-6 Docbasic User’s Guide

 C Compiler Error
Messages
The following table contains a list of all the errors generated by the Docbasic
compiler. With some errors, the compiler changes placeholders within the error to
text from the procedure being compiled. These placeholders are represented in this
table by the word placeholder.
Table C-1 Compiler Error Messages

Error number Description

1 Variable Required - Can't assign to this expression

2 Letter range must be in ascending order

3 Redefinition of default type

4 Out of memory, too many variables defined

5 Type-character doesn't match defined type

6 Expression too complex

7 Cannot assign whole array

8 Assignment variable and expression are different types

10 Array type mismatch in parameter

11 Array type expected for parameter

12 Array type unexpected for parameter

13 Integer expression expected for an array index

14 Integer expression expected

15 String expression expected

Docbasic User’s Guide C-1

 Compiler Error Messages

Table C-1 Compiler Error Messages

Error number Description

18 Left of "." must be an object, structure, or dialog

19 Invalid string operator

20 Can't apply operator to array type

21 Operator type mismatch

22 "placeholder" is not a variable

23 "placeholder" is not a array variable or a function

24 Unknown placeholder "placeholder"

25 Out of memory

26 placeholder: Too many parameters encountered

27 placeholder: Missing parameter(s)

28 placeholder: Type mismatch in parameter placeholder

29 Missing label "placeholder"

30 Too many nested statements

31 Encountered new-line in string

32 Overflow in decimal value

33 Overflow in hex value

34 Overflow in octal value

35 Expression is not constant

37 No type-characters allowed on parameters with explicit type

39 Can't pass an array by value

40 "placeholder" is already declared as a parameter

41 Variable name used as label name

42 Duplicate label

43 Not inside a function

44 Not inside a sub

46 Can't assign to function

47 Identifier is already a variable

48 Unknown type

49 Variable is not an array type

50 Can't redimension an array to a different type

51 Identifier is not a string array variable

52 0 expected

C-2 Docbasic User’s Guide

Compiler Error Messages

Table C-1 Compiler Error Messages

Error number Description

55 Integer expression expected for file number

56 placeholder is not a method of the object

57 placeholder is not a property of the object

58 Expecting 0 or 1

59 Boolean expression expected

60 Numeric expression expected

61 Numeric type FOR variable expected

62 For...Next variable mismatch

63 Out of string storage space

64 Out of identifier storage space

65 Internal error 1

66 Maximum line length exceeded

67 Internal error 3

68 Division by zero

69 Overflow in expression

70 Floating-point expression expected

72 Invalid floating-point operator

74 Single character expected

75 Subroutine identifier can't have a type-declaration character

76 Procedure is too large to be compiled

77 Variable type expected

78 Can't evaluate expression

79 Can't assign to user or dialog type variable

80 Maximum string length exceeded

81 Identifier name already in use as another type

84 Operator cannot be used on an object

85 placeholder is not a property or method of the object

86 Type-character not allowed on label

87 Type-character mismatch on routine placeholder

88 Destination name is already a constant

89 Can't assign to constant

90 Error in format of compiler extensions

Docbasic User’s Guide C-3

 Compiler Error Messages

Table C-1 Compiler Error Messages

Error number Description

91 Identifier too long

92 Expecting string or structure expression

93 Can't assign to expression

94 Dialog and Object types are not supported in this context

95 Array expression not supported as parameter

96 Dialogs, objects, and structures expressions are not supported as a

parameter

97 Invalid numeric operator

98 Invalid structure element name following "."

99 Access value can't be used with specified mode

101 Invalid operator for object

102 Can't LSet a type with a variable-length string

103 Syntax error

104 Placeholder is not a method of the object

105 No members defined

106 Duplicate type member

107 Set is for object assignments

108 Type-character mismatch on variable

109 Bad octal number

110 Bad number

111 End-of-procedure encountered in comment

112 Misplaced line continuation

113 Invalid escape sequence

114 Missing End Inline

115 Statement expected

116 ByRef argument mismatch

117 Integer overflow

118 Long overflow

119 Single overflow

120 Double overflow

121 Currency overflow

122 Optional argument must be Variant

C-4 Docbasic User’s Guide

Compiler Error Messages

Table C-1 Compiler Error Messages

Error number Description

123 Parameter must be optional

124 Parameter is not optional

125 Expected: Lib

126 Illegal external function return type

127 Illegal function return type

128 Variable not defined

129 No default property for the object

130 The object does not have an assignable default property

131 Parameters cannot be fixed length strings

132 Invalid length for a fixed length string

133 Return type is different from a prior declaration

134 Private variable too large. Storage space exceeded

135 Public variables too large. Storage space exceeded

Docbasic User’s Guide C-5

 Compiler Error Messages

C-6 Docbasic User’s Guide

 D Language
Elements by
Platform
The following table lists all Docbasic language elements and on which platforms
these language elements are supported.
Table D-1 Language Elements by Platform

Language Element Win Win32 UNIX Mac

&




'




()




*




+




-




/




<




<=




<>




= (assignment)




= (operator)

Docbasic User’s Guide D-1

 Language Elements by Platform

Table D-1 Language Elements by Platform

Language Element Win Win32 UNIX Mac

>




>=




\




^




_




Abs




And




ArrayDims




ArraySort




Asc




Atn




Basic.Capability




Basic.Eoln$




Basic.FreeMemory




Basic.HomeDir$




Basic.OS




Basic.PathSeparator$




Basic.Version$




Beep




Boolean




Call




CBool




CCur




CDate




CDbl




ChDir




ChDrive

 
Choose




Chr, Chr$

D-2 Docbasic User’s Guide

Language Elements by Platform

Table D-1 Language Elements by Platform

Language Element Win Win32 UNIX Mac

CInt




Clipboard$ (function)



Clipboard$ (statement)



Clipboard.Clear



Clipboard.GetFormat



Clipboard.GetText



Clipboard.SetText



CLng




Close




Command, Command$




Const




Cos




CreateObject



CSng




CStr




CurDir, CurDir$




Currency




CVar




CVDate




CVErr




Date




Date, Date$ (functions)




Date, Date$ (statements)




DateAdd




DateDiff




DatePart




DateSerial




DateValue




Day

Docbasic User’s Guide D-3

 Language Elements by Platform

Table D-1 Language Elements by Platform

Language Element Win Win32 UNIX Mac

DDB




DDEExecute

 
DDEInitiate

 
DDEPoke

 
DDERequest, DDERequest$

 
DDESend

 
DDETerminate

 
DDETerminateAll

 
DDETimeOut

 
Declare




DefBool




DefCur




DefDate




DefDbl




DefInt




DefLng




DefObj




DefSng




DefStr




DefVar




Dim




Dir, Dir$




DiskDrives

 
DiskFree

 
Do...Loop




Double




End




Environm Environ$




Eof

D-4 Docbasic User’s Guide

Language Elements by Platform

Table D-1 Language Elements by Platform

Language Element Win Win32 UNIX Mac

Eqv




Erase




Erl




Err (function)




Err (statement)




Error




Error, Error$




Exit Do




Exit For




Exit Function




Exit Sub




Exp




FileAttr




FileCopy




FileDateTime




FileDirs




FileExists




FileLen




FileList




FileParse$




FileType
  
Fix




For...Next




Format, Format$




FreeFile




Function...End




Fv




Get




GetAttr

Docbasic User’s Guide D-5

 Language Elements by Platform

Table D-1 Language Elements by Platform

Language Element Win Win32 UNIX Mac

GetObject



Global




GoSub




Goto




Hex, Hex$




Hour




If...Then...Else




IIf




Imp




Inline




Input#




Input, Input$




InputBox, InputBox$



InStr




Int




Integer




IPmt




IRR




Is




IsDate




IsEmpty




IsError




IsMissing




IsNull




IsNumeric




IsObject




Item$




ItemCount




Kill

D-6 Docbasic User’s Guide

Language Elements by Platform

Table D-1 Language Elements by Platform

Language Element Win Win32 UNIX Mac

LBound




LCase, LCase$




Left, Left$




Len




Let




Like




Line Input #




Line$




LineCount




Loc




Lock




Lof




Log




Long




LSet




LTrim, LTrim$




MacID   

MacScript   

Main




Mci
  
Mid, Mid$




Mid, Mid$




Minute




MIRR




MkDir




Mod




Month




MsgBox (function)



MsgBox (statement)



Docbasic User’s Guide D-7

 Language Elements by Platform

Table D-1 Language Elements by Platform

Language Element Win Win32 UNIX Mac

Name




Not




Nothing




Now




NPer




Npv




Object



Oct. Oct$




OKButton

r

On Error




Open




OpenFilename$



Option Base




Option CStrings




Or




Pmt




PPmt




Print




Print #




Private




Public




Put




Pv




Random




Randomize




Rate




ReadINI$

 
ReadINISection

 

D-8 Docbasic User’s Guide

Language Elements by Platform

Table D-1 Language Elements by Platform

Language Element Win Win32 UNIX Mac

ReDim




REM




Reset




Resume




Return




Right, Right$




RmDir




Rnd




RSet




RTrim, RTrim$




SaveFileName$



Second




Seek




Seek




Select...Case




Set




SetAttr




Sgn




Shell




Sin




Single




Sleep




Sln




Space, Space$




Spc




Sqr




Stop




Str, Str$




StrComp

Docbasic User’s Guide D-9

 Language Elements by Platform

Table D-1 Language Elements by Platform

Language Element Win Win32 UNIX Mac

String




String, String$




Sub...End




Switch




SYD




Tab




Tan




Time, Time$ (functions)




Time, Time$ (statements)




Timer




TimeSerial




TimeValue




Trim, Trim$




Type




UBound




UCase, UCase$




UnLock




Val




Variant




VarType




Weekday




While...Wend




Width#




Word$




WordCount




Write #




Xor




Year

D-10 Docbasic User’s Guide

Language Elements by Platform

Docbasic User’s Guide D-11

 Language Elements by Platform

D-12 Docbasic User’s Guide

 E Docbasic
Limitations
The following list contains important Docbasic limitations:

Line numbers are not supported. Labels can be used in place of line numbers
are targets for the Goto statement.

Strings are limited in length to 32,764 characters. This includes local, public,
and private strings, as well as strings within structures and arrays.

The Visual Basic declaration modifiers Static and Shared are not supported.

The default string space is 8K, which expands automatically up to a
maximum of 1 MB on many platforms. This space contains all strings and
arrays regardless of their scope.

The default stack size for the runtime is 2,048 bytes. This space contains all
local variables (except arrays and variable-length strings) and passed
parameters.

The stack is also used by the runtime for storage of intermediate values, so
the actual available stack space will be slightly less.

Calls made to subroutines or functions in other procedures use the stack of

the caller.

Note: The application vendor can change the above stack limitation to any
value up to 8K.

The data area that holds private variables is limitated to 16K. This data space
contains all private variables except strings and arrays, which are stored in
the string space.

Docbasic User’s Guide E-1

 Docbasic Limitations

The data area that holds public variables is limited to 16K. This data space
contains all public variables except strings and arrays, which are stored in
the string space.

The size of a source procedure is limited to 65534 characters. This limitation
can be avoided by breaking up large procedures into smaller ones.

A compiled procedure consists of p-code, constant data, and symbolic
information, each of which is limited to 64K. These limitations can be
avoided by breaking up large procedures into smaller ones, which is rarely
necessary.

Arrays can have up to 60 dimensions.

Variable names are limited to 80 characters.

Labels are limited to 80 characters.

Each executing procedure contains a table of structures that track calls made
to external routines. Each structure is approximately 88 bytes with an overal
size limited to 64K.

The number of open DDE channels is not fixed; rather, it is limited only by
available memory and system resources.

The number of open files is limited to 255 or the operating system limit,
whichever is less.

The number of characters within a string literal (a string enclosed within
quotation marks) is limited to 1024 characters. (Strings can be concatenated
using the concatenation [&] operator with the normal string limit of 32,764
characters.)

The number of nesting levels (i.e., loops within loops) is limited by compiler
memory.

Each GoSub requires 2 bytes of the Docbasic runtime stack.

Arrays and user-defined types cannot be passed to a method of an OLE
automation object.

Arrays and user-defined types cannot be set as the value of a property of an
OLE automation object.

Arrays and user-defined types cannot be returned from a method or
property of an OLE automation object.

Array indexes must be in the following range:

-32768 <= array-index <=32767

The size of an array cannot exceed 32K. For example, an array of integers,
each of which requires 2 bytes of storage, is limited to the following
maximum number of elements:

max_num_elements = (32767 - overhead) / 2

where overhead is currently approximately 16 bytes.

E-2 Docbasic User’s Guide

 F Docbasic/Visual
Basic Differences
This appendix describes differences between Docbasic 1.0 and Visual Basic 3.0 (VB)
or Visual Basic for Applications 1.0 (VBA). The following topics are covered:

Arrays

Constants

Data Types

Declarations

Declare Statement

Floating Point Numbers

Currency Numbers

Language Element Differences

Natural Language Support

Objects

OLE Automation

Parameter Passing

Strings

Variants

Stack Size

Expression Evaluation

File Searching

Docbasic User’s Guide F-1

 Docbasic/Visual Basic Differences

Arrays
VB and VBA support huge arrays, Docbasic does not.

Constants
VBA supports shared constants (using the Public keyword). In Docbasic, constants
must be repeated within each procedure in which they are used.

VB and VBA do not allow the concatenation of constant elements. For example, the
following procedure compiles in Docbasic but not in VB or VBA:
Const t$ = "Hello" & Chr$(9) & "there."

Sub Main()
Msgbox t$
End Sub

VBA allows a user to redefine global constants at the subroutine/function level

without affecting their global values; Docbasic does not. For example, the
following procedure will compile and execute in VBA but not in Docbasic:
Const t = "Hello"

Sub Main()
Const t$ = "Good Bye"
MsgBox t$ 'Displays Good Bye
End Sub

Data Types
Docbasic and VBA support the Boolean and Date data types, VB does not.

Declarations
In VB and VBA, if a variable is initially declared with a type declaration character,
then that character must appear with every use of that variable. Docbasic relaxes
this by not requiring the type declaration character with every use of that variable.

Both VB and VBA support the Static keyword as a modifier for the Sub and
Function statements. Docbasic supports use of this keyword with these statements
with no effect.

A variable used in a comparison expression that hasn't been declared will be

implicitly declared in VB and VBA. In Docbasic, this will be seen as an unresolved
function:
Sub Main
if a$ = "hello" then beep
End Sub

F-2 Docbasic User’s Guide

Docbasic/Visual Basic Differences

In Docbasic, the above procedure will compile, but gives a Sub or function not
defined error when executed. In VB and VBA, this will automatically declare a
variable called a$ as a String.

Docbasic allows the @ type declaration character to be specified with currency

constants; VB and VBA do not.

Declare Statement
VBA supports shared Declare statements (using the Public keyword). In Docbasic,
these must be declared in every procedure in which they are used.

Docbasic supports a superset of that functionality available in VB—namely, the

additional calling conventions.

Docbasic and VB pass values to external routines in the same manner with the
following exceptions:

Docbasic passes True or False as Boolean values (signed short in C). VB passes
these as Boolean variants.

Variants are passed as internal variant structures in both Docbasic and VB. For all
numeric values, the types are the same. Strings, however, in Docbasic are passes as
a 16-bit internal value, whereas in VB they are passed as a 32-bit pointer to a null-
terminated string.

The variant structure in both systems is a 4-byte type (a 32-bit integer—the same
value as returned by the VarType function), followed by 4 bytes of slop, followed
by the value of the variable, as shown below:

Table F-1 Byte Structure of Variants

Bytes 0-3 Bytes 4-7 Bytes 8-15

VarType Alignment slop Value

Strings within variants are passed within an internal variant structure in both
Docbasic and VB.

Floating Point Numbers

In VB and VBA, floating point numbers are interpreted as doubles unless they are
explicitly accompanied by a type-declaration character. Thus, the following line
assigns a Double in VB and VBA, whereas in Docbasic, it assigns a Single:
a = 0.00001

Docbasic User’s Guide F-3

 Docbasic/Visual Basic Differences

In Docbasic, additional checking is performed to determine if a floating point

number can be accurately represented as a Single. If so, then the number is stored
as a Single, requiring 4 bytes rather than 8.

The implications of this difference can be seen in the following code:

Dim a As Variant,b As Variant

a = 1000
b = .00001
a = a + b

MsgBox a

In VB and VBA, since the variables a and b are assigned Double values, the
addition is performed between two doubles, resulting in the value 1000.00001. In
Docbasic, on the other hand, a and b are assigned Single values, resulting in an
addition between two singles. When these two singles are added, there is a loss of
precision resulting in the value 1000.

In situations such as this, you should explicitly force the types using type-
declaration characters. The above code can be re-written as follows:
Dim a As Variant,b As Variant

a = 1000#
b = .00001#
a = a + b

MsgBox a'Docbasic displays 1000.00001

Currency Numbers
In VB , Double numbers do not convert to Currency numbers the same way. In VB,
for example, the following procedure will fail:
Sub Main
result = CCur("-1.401298E-45")
End Sub

The above fails in VB because the number being converted is known to be a

Double. In Docbasic, any number between the valid range supported by Currency
is convertable to Currency, even if the number is expressed in scientific notation or
is extremely small (approaching zero).

Language Element Differences

The following language elements allow specification of additional parameters for
displaying help in VBA:
MsgBox (statement)
MsgBox (function)

Docbasic and VB do not support these parameters.

F-4 Docbasic User’s Guide

Docbasic/Visual Basic Differences

Docbasic does not support any of the following VBA language elements:

Table F-2 Unsupported VBA Language Elements

Language Element Type

Array Function

ebHiragana Constant

ebKatakana Constant

ebLowerCase Constant

ebNarrow Constant

ebProperCase Constant

ebUpperCase Constant

ebWide Constant

Exit Property Statement

For Each...Next Statement

IsArray Function

LenB Function

LoadPicture Function

On...Gosub Statement

On...Goto Statement

Option Explicit Statement

Option Private Statement

Property Get...End Statement

Property

Property Let...End Statement

Property

Property Set...End Statement

Property

Static Statement

StrConv Function

TypeName Function

TypeOf Function

With...End With Statement

The syntax for MsgBox does not support the context and HelpFile parameters.

Docbasic User’s Guide F-5

 Docbasic/Visual Basic Differences

Natural Language Support

VBA supports multi-byte characters (sometimes referred to as natural language
support); Docbasic and VB do not.

Objects
Docbasic does not support any of VB's objects (except clipboard, screen, and a few
others).

OLE Automation
Docbasic does not support named parameters. Visual Basic does not support
named parameters either; this is a feature of VBA.

Docbasic does not support the VBA bracket syntax used with OLE automation
objects. For example, the following two expressions are equivalent in VBA:
Application.Workbooks(1).Worksheets(“Sheet1”).Range(“A1”)

[A1]

Docbasic does not support the VBA bracket syntax used to resolve the scope of a
method or property:
Dim a As Object
Set a = CreateObject("Word.Basic")
a.[MsgBox] "Hello, world."'<-- Won't work in Docbasic

Parameter Passing
VB and Docbasic do not support optional parameters. This is supported by VBA.

Strings
In Docbasic, variable-length strings within structures require 2 bytes of storage. In
VB and VBA, variable-length strings within structures require 4 bytes of storage.

The implications of this difference can be seen in the following code:

Type Sample
LastName As String
End Type

Sub Main
Dim a As Sample
MsgBox Len(a)
End Sub

In the above code, Visual Basic displays 4, while Docbasic displays 2.

F-6 Docbasic User’s Guide

Docbasic/Visual Basic Differences

In Docbasic, variable-length strings are limited to 32K in length. In VB, variable-

length strings are limited to 64K. In VBA, variable-length strings have no limits on
their lengths. This limitation has implications on the string functions. For example,
the Left function returns a specified number of characters from the left side of a
string. The second parameter represents the number of characters to return—in
VBA, this parameter is a Long whereas, in Docbasic, this parameter is an Integer.
To demonstrate, the following statement will overflow in Docbasic, but not in
VBA:
s$ = Left(s$,300000)

VB and VBA do not accept strings in some functions expecting numbers such as
Int and Fix. Docbasic allows strings as long as they are convertible to numbers.
Dim A As Variant
ABS(19) 'OK
A = "10"
ABS(A) 'OK
ABS("10")'Works in Docbasic, not in VB/VBA

In Docbasic, these functions will accept any data type convertible to a number. If
the data type is a string, Docbasic converts it to a Double.

Fixed-length strings within structures are size-adjusted upwards to an even size.

Thus, structures in Docbasic are always even sized. VB and VBA allow fixed-
length strings within structures to maintain an odd size.

Variants
Passing variants either by value or by reference to external routines (using the
Declare statement) passes either the entire variant structure (ByVal) or a pointer to
a variant structure (ByRef) used internally by Docbasic. This means that passing
variants to externally declared routines can only be done if that routine is aware of
the internal variant structure used by Docbasic. This applies specifically to strings
and OLE automation objects stored within the variant.

In VB and VBA, on the other hand, strings and OLE automation objects within
variants are stored in their native format (i.e., 32-bit pointer to a null-terminated
string or an LPDISPATCH value).

VBA supports variant arrays; Docbasic and VB do not. This includes use of the
Array and IsArray functions.

Docbasic and VBA support error variants; VB does not.

Passing Variants by Reference

In VBA, variants cannot be passed by reference to user-defined routines accepting
non-variant parameters. For example, the following will not work in VBA:
Sub Test(ByRef a As Integer)

Docbasic User’s Guide F-7

 Docbasic/Visual Basic Differences

End Sub

Sub Main
Dim v As Variant
v = 5
Test v '<-- VBA gives error here
End Sub

In Docbasic, the above example works as expected. Docbasic actually performs a

conversion of the Variant v to a temporary Integer value and passes this temporary
value by reference. Upon return from the call to Test, Docbasic convers the
temporary Integer back to a Variant.

Passing Optional Variants to Forward Declared Routines

Docbasic does not catch the following error:
Declare Sub Test(Optional v As Variant)'<-- LINE 1
Sub Main
Test
End Sub
Sub Test(v As Variant)'<-- LINE 5
End Sub

In the above procedure, the Declare statement on line 1 defines a prototype for the
Test function that is incompatible with the actual declaration on line 5.

Stack Size
Docbasic uses a default stack of 2K, expandable to 8K. VB and VBA uses a much
larger stack size. For example, VBA allocates approximately 14K for the stack.

Since the stack for Docbasic is smaller, you may have to be more attentive when
using local variables, especially fixed-length strings and structures, since storage
for all local variables comes from the stack.

Note: Variable-length strings only require 2 bytes of storage on the stack. Wherever
possible, use variable length strings in place of fixed-length strings.

Expression Evaluation
With Boolean expressions (i.e., expression involving And, Or, Xor, Eqv, and Imp),
if one operand is Null and the other argument is numeric, then Null is returned
regardless of the value of the other operand. For example, the following expression
returns Null:
Null And 300000

Despite the fact that the expression returns Null, VBA evaluates the numeric
operand anyway, converting it to a Long. If an overflow occurs during conversion,

F-8 Docbasic User’s Guide

Docbasic/Visual Basic Differences

a trappable runtime error is generated. In Docbasic, the expression returns Null

regardless of the value of the numeric operand. For example, the following
expression will overflow in VBA, but not in Docbasic:
Null And 5E200

File Searching
The filename matching algorithm used by Docbasic is different than that used by
VB. This affects commands that perform directory searching, such as Dir, Kill, and
FileList. The following differences exist:

In VB, an asterisk within the filename matches any characters up to the end of the
filename or to the period, whichever comes first.

In VB, the period is a separator for the filename and the extension. In Docbasic, the
period is treated as a normal filename character.

The following table describes the meaning of some common file specifications.

Table F-3 File Specifications

Specification Meaning in VB Meaning in Docbasic

* All files. All files.

*.* All files. All files that have an extension.

s*e All files that begin with "s". All files that begin with "s" and end
with "e".

s*.* All files that begin with "s". All files that begin "s" and have an
extension.

test. The file "test" with no extension. The file called "test.". Docbasic will
never find this file under Windows.

test.* All files having the root name "test" All files having the root name "test"
with any extension, such as "test", with an extension. The file "test"
"test.txt", and so on. with no extension will not be found.

This filename matching algorithm is the same across all platforms that support
Docbasic.

Docbasic User’s Guide F-9

 Docbasic/Visual Basic Differences

F-10 Docbasic User’s Guide

Index
- (minus sign), subtraction operator 3-10 wildcard used with Like (operator) 3-311
+ (plus sign), addition operator 3-8
, (comma)
used with Print 3-391
Symbols used within user-defined formats 3-239
. (period)
! (exclamation point) used to separate object from property 3-12
activating parts of files 3-258 used with structures 3-12
used within user-defined formats 3-241 used within filenames 3-91
" (quote), embedding within strings 3-319 used within user-defined formats 3-239
# (number sign) / (slash)
as delimiter for date literals 3-319 division operator 3-13
delimiter for date literals 3-103 used within filenames 3-90
delimiter for parsing input 3-273 used within user-defined formats 3-240
used to specify ordinal values 3-141, 3-142, : (colon)
3-143 used within user-defined formats 3-239
used within user-defined formats 3-239 = (equal sign)
wildcard used with Like (operator) 3-311 assignment statement 3-16
#ERROR code# comparison operator 3-15
writing to sequential files 3-509 > (greater than)
#FALSE# comparison operator 3-15
writing to sequential files 3-509 used within user-defined formats 3-241
#NULL# >= (greater than or equal), comparison operator
writing to sequential files 3-509 3-15
#TRUE# ? (question mark)
writing to sequential files 3-509 wildcard used with Like (operator) 3-311
% (percent) @ (at sign)
used within user-defined formats 3-239 used within user-defined formats 3-240
& (ampersand) \ (backslash)
concatenation operator 3-2 integer division operator 3-18
octal/hexadecimal formats 3-319 used with escape characters 3-382
used within user-defined formats 3-240 used within filenames 3-90
& (operator), vs. addition 3-8 used within user-defined formats 3-240
' (apostrophe), used with comments 3-3 ^ (caret), exponentiation operator 3-19
( ) (parentheses) _ (underscore), line-continuation character 3-20
used in expressions 3-4 __stdcall calling convention 3-135
() (parentheses)
used to pass parameters by value 3-4
(semicolon), used with Print 3-391, 3-393
) 3-311, 3-398 Numerics
* (asterisk)
multiplication operator 3-6 0 (digit), used within user-defined formats 3-239

Docbasic User’s Guide Index-1

A operations on 3-28
passing 3-28
Private (statement) 3-396
Abs (function) 3-21 Public (statement) 3-398
absolute value 3-21 setting default lower bound of 3-379
aliases size, changing while running 3-413
used with external subroutines and functions sorting 3-30
3-136 total size of 3-147, 3-396, 3-398
alignment, considerations across platforms 3-89 ArraySort (statement) 3-30
And (operator) 3-23 Asc (function) 3-32
annuities assigning, objects 3-436
future values of 3-250 assignment
interest rates of 3-408 = (statement) 3-16
number of periods for 3-358 Let (statement) 3-310
payments for 3-387 LSet (statement) 3-328
present value of 3-360, 3-404 overflow during 3-16, 3-310
principal payments for 3-389 rounding during 3-212
antilogarithm function (Exp) 3-211 RSet (statement) 3-423
Any (data type) 3-25 Atn (function) 3-33
Append (keyword) 3-372 used to calculate Pi 3-386
AppleScript, executing 3-332
applications
running 3-443
Apply (Server method) 1-10 B
arctangent function (Atn) 3-33
arguments Basic.Capability (method) 3-34, 3-87
parentheses use 3-4 Basic.Eoln$ (property) 3-36
passed to functions 3-247 Basic.FreeMemory (property) 3-37
passed to subroutines 3-463 Basic.HomeDir$ (property) 3-38
to external routines 3-47, 3-134 Basic.OS (property) 3-39, 3-87
ArrayDims (function) 3-26 Basic.PathSeparator$ (property) 3-41
arrays 3-27 Basic.Version$ (property) 3-42
ArrayDims (function) 3-26 Beep (statement) 3-43
declaring 3-27 Binary (keyword) 3-372
as local 3-147 binary data
as private 3-396 reading 3-252
as public 3-398 writing 3-401
Dim (statement) 3-147 binary files
dimensions opening 3-372
getting bounds of 3-28 reading from 3-252
getting lower bound 3-304 writing to 3-401
getting number of 3-26, 3-28 binary operators
getting upper bound 3-483 And (operator) 3-23
LBound (function) 3-304 Eqv (operator) 3-193
maximum number of 3-147 Imp (operator) 3-270
reestablishing 3-413 Not (operator) 3-354
UBound (function) 3-483 Or (operator) 3-384
dynamic 3-27, 3-147, 3-396, 3-398, 3-413 Xor (operator) 3-513
erasing 3-195 Boolean (data type) 3-44
filling with disk names 3-154 converting to 3-51
fixed-sized, declaring 3-27 range of values 3-44

Index-2 Docbasic User’s Guide

 storage requirements 3-44 CInt (function) 3-64
Boolean constants Clipboard
True (constant) 3-480 erasing 3-68
Bourne shell 3-444 getting contents of 3-66, 3-71
breakpoints, in Procedure Editor 2-21 getting type of data in 3-69
removing 2-23 setting contents of 3-67, 3-72
setting 2-21 Clipboard$ (function) 3-66
bugs (error trapping) 3-201, 3-369 Clipboard$ (statement) 3-67
buttons Clipboard.Clear (method) 3-68
on toolbar Clipboard.GetFormat (method) 3-69
in Procedure Editor 2-2 Clipboard.GetText (method) 3-71
by value, forcing parameters 3-247, 3-463 Clipboard.SetText (method) 3-72
ByRef (keyword) 3-46, 3-137, 3-246, 3-247, 3-463 CLng (function) 3-73
byte ordering, with files 3-87 Close (statement) 3-75
byte ordering, with structures 3-88 closing
ByVal (keyword) 3-4, 3-47, 3-134, 3-136, 3-246, all files 3-416
3-247, 3-463 files 3-75
code resources
search rules for 3-142
specifying, on the Macintosh 3-143
C collections
defined 3-366
Call (statement) 3-49 elements, identifying 3-366
calling indexing 3-366
external routines 3-134 methods of 3-367
other routines 3-49 properties of 3-367
calling conventions command line, retrieving 3-76
__stdcall 3-135 Command, Command$ (functions) 3-76
CDecl 3-135 comments 3-77
Pascal 3-135 ' (apostrophe) 3-3
System 3-135 adding to procedures, in Procedure Editor 2-12
under Win32 3-142 Rem (statement) 3-415
capabilities common dialogs
of platform 3-34 file open 3-375
Case Else (statement) 3-434 comparing strings 3-456
case sensitivity, when comparing strings 3-380 comparison operators 3-78
case statement 3-434 table of 3-78
CBool (function) 3-51 used with mixed types 3-78
CCur (function) 3-53 used with numbers 3-79
cd audio, Mci (function) 3-334 used with strings 3-79
CDate, CVDate (functions) 3-54 used with variants 3-79
CDbl (function) 3-56 compatibility mode, opening files in 3-373
CDecl (keyword) 3-134 compiler errors C-1
CDecl calling convention 3-135 concatenation operator (&) 3-2
character conditionals
codes 3-32 Choose (function) 3-61
converting to number 3-32 If...Then...Else (statement) 3-267
ChDir (statement) 3-57 IIf (function) 3-269
ChDrive (statement) 3-59 Switch (function) 3-466
Choose (function) 3-61 conjunction operator (And) 3-23
Chr, Chr$ (functions) 3-62 Const (statement) 3-81

Docbasic User’s Guide Index-3

Constants using RSet (statement) 3-423
list of 3-83 files 3-218
constants text
declaring 3-81 in Procedure Editor 2-11
ebBoolean (constant) 3-167 user-defined types 3-328
ebCurrency (constant) 3-170 Cos (function) 3-84
ebDate (constant) 3-172 cosine 3-84
ebEmpty (constant) 3-173 counters, used with For...Next (statement) 3-235
ebHidden (constant) 3-175 counting
ebInteger (constant) 3-176 items in string 3-300
ebLong (constant) 3-177 lines in string 3-318
ebNone (constant) 3-178 words 3-508
ebNormal (constant) 3-179 CreateObject (function) 3-85
ebNull (constant) 3-180 creating new objects 3-148, 3-353
ebObject (constant) 3-181 cross-platform issues 3-87
ebReadOnly (constant) 3-182 alignment 3-89
ebSingle (constant) 3-183 byte ordering with files 3-87
ebString (constant) 3-184 byte ordering with structures 3-88
ebSystem (constant) 3-185 determining capabilities of platform 3-87
ebSystemModal (constant) 3-186 determining platform 3-34, 3-87
ebVariant (constant) 3-187 end-of-line character 3-89
ebVolume (constant) 3-188 getting end-of-line character 3-36
ebWin16 (constant) 3-39 getting path separator 3-41
Empty (constant) 3-189 getting platform 3-39
folding 3-320 path separators 3-90
giving explicit type to 3-81 portability of compiled code 3-89
naming conventions of 3-81 portability of drive letters 3-91
Nothing (constant) 3-356 relative paths 3-91
Null (constant) 3-362 unsupported language elements 3-89
Pi (constant) 3-386 CSng (function) 3-92
scoping of 3-82 CStr (function) 3-94
True (constant) 3-480 CurDir, CurDir$ (functions) 3-96
control structures 3-190 Currency (data type) 3-98
Do...Loop (statement) 3-162 converting to 3-53
Exit Do (statement) 3-205 range of values 3-98
Exit For (statement) 3-207 storage requirements 3-98
Exit Function (statement) 3-209 cutting text, in Procedure Editor 2-11
Exit Sub (statement) 3-210 CVar (function) 3-99
For...Next (statement) 3-234 CVDate (function) 3-54
Function...End Function (statement) 3-245 CVErr (function) 3-101
GoSub (statement) 3-261, 3-419
Goto (statement) 3-263
If...Then...Else (statement) 3-267
Select...Case (statement) 3-434 D
Sub...End Sub (statement) 3-462
While...Wend (statement) 3-502 data conversion
copying character to number 3-32
data during expression evaluation 3-212
using = (statement) 3-16 number to character 3-62
using Let (statement) 3-310 number to hex string 3-265
using LSet (statement) 3-328 number to octal string 3-368

Index-4 Docbasic User’s Guide

 string to number 3-491 Date, Date$ (functions) 3-105
testing for numbers 3-295 Date, Date$ (statements) 3-106
to Boolean 3-51 date/time functions
to Currency 3-53 Date, Date$ (functions) 3-105
to Date 3-54, 3-115, 3-290, 3-477 Date, Date$ (statements) 3-106
to Double 3-56 DateAdd (function) 3-108
to error 3-101 DateDiff (function) 3-110
to Integer 3-64 DatePart (function) 3-112
to Long 3-73 DateSerial (function) 3-114
to Single 3-92 Day (function) 3-116
to String 3-94, 3-455 FileDateTime (function) 3-220
to Variant 3-99 Hour (function) 3-266
data conversion functions IsDate (function) 3-290
Asc (function) 3-32 Minute (function) 3-341
CBool (function) 3-51 Month (function) 3-347
CCur (function) 3-53 Now (function) 3-357
CDate, CVDate (functions) 3-54 Second (function) 3-429
CDbl (function) 3-56 Time, Time$ (functions) 3-472
Chr, Chr$ (functions) 3-62 Time, Time$ (statements) 3-473
CInt (function) 3-64 Timer (function) 3-475
CLng (function) 3-73 TimeSerial (function) 3-476
CSng (function) 3-92 Weekday (function) 3-500
CStr (function) 3-94 Year (function) 3-515
CVar (function) 3-99 DateAdd (function) 3-108
CVErr (function) 3-101 DateDiff (function) 3-110
Hex, Hex$ (functions) 3-265 DatePart (function) 3-112
Oct, Oct$ (functions) 3-368 dates
Str, Str$ (functions) 3-455 adding 3-108
Val (function) 3-491 converting to 3-114, 3-290
data types current 3-105, 3-357
Any (data type) 3-25 day of month 3-116
Boolean (data type) 3-44 day of week 3-500
changing default 3-144 file creation 3-220
Currency (data type) 3-98 file modification 3-220
Dim (statement) 3-147 month of year 3-347
Double (data type) 3-165 parts of 3-112
Integer (data type) 3-283 setting 3-106
Long (data type) 3-327 subtracting 3-110
Object (data type) 3-363 year 3-515
Private (statement) 3-396 DateSerial (function) 3-114
Public (statement) 3-398 DateValue (function) 3-115
returned from external functions 3-136 Day (function) 3-116
Single (data type) 3-446 DDB (function) 3-117
String (data type) 3-458 DDE
user-defined 3-489 changing timeout 3-132
Variant (data type) 3-493 ending conversation 3-129
Date (data type) executing remote command 3-119
converting to 3-54, 3-115, 3-477 getting text 3-125
range of values 3-103 getting value from another application 3-125
specifying date constants 3-103 initiating conversation 3-121
storage requirements 3-103 sending text 3-123

Docbasic User’s Guide Index-5

 setting data in another application 3-127 sum of years' digits depreciation 3-467
setting value in another application 3-123 dialogs, built-in
Shell (function) 3-443 InputBox, InputBox$ (functions) 3-278
starting conversation 3-121 MsgBox (function) 3-348
terminating conversation 3-129, 3-131 MsgBox (statement) 3-350
DDEExecute (statement) 3-119 Dim (statement) 3-147
DDEInitiate (function) 3-121 Dir, Dir$ (functions) 3-151
DDEPoke (statement) 3-123 directories
DDERequest, DDERequest$ (functions) 3-125 changing 3-57
DDESend (statement) 3-127 containing Docbasic 3-38
DDETerminate (statement) 3-129 creating 3-344
DDETerminateAll (statement) 3-131 getting list of 3-222
DDETimeout (statement) 3-132 getting path separator 3-41
debugger, invoking 3-454 parsing names of 3-229
debugging procedures, in Procedure Editor 2-1, removing 3-421
2-18 retrieving 3-96
breakpoints 2-21 retrieving filenames from 3-151, 3-226
removing 2-23 disjunction operator (Or) 3-384
setting 2-21 disk drives
instruction pointer 2-18 changing 3-59
moving to another line in subroutine 2-19 getting free space of 3-155
procedure calls, tracing 2-19 platform support 3-91
watch variables 2-24 retrieving current directory of 3-96
adding 2-24 retrieving list of 3-154
deleting 2-26 DiskDrives (statement) 3-154
modifying value of 2-27 DiskFree (function) 3-155, 3-156, 3-157, 3-159,
selecting 2-25 3-160
decision making displaying messages 3-348, 3-350
Choose (function) 3-61 breaking text across lines 3-348
If...Then...Else (statement) 3-267 DLLs
IIf (function) 3-269 calling 3-134
Select...Case (statement) 3-434 Declare (statement) 3-134
Switch (function) 3-466 search rules for, under OS/2 3-143
Declare (statement) 3-25, 3-134 search rules for, under Windows 3-141
declaring dmAPIExec 3-156
implicit variables 3-148 dmAPIGet 3-157
object variables 3-148, 3-353, 3-363, 3-365 dmAPISet 3-159
with Dim (statement) 3-147 dmbasic 1-10
with Private (statement) 3-396 arguments 1-11
with Public (statement) 3-398 Do...Loop (statement) 3-162
default data type, changing 3-144 exiting Do loop 3-205
default properties 3-213 DO_METHOD function
Define (Workspace method) 1-3 Docbasic and 1-10
DefType (statement) 3-144 Docbasic
degrees, converting to radians 3-33 free memory of 3-37
deleting text, in Procedure Editor 2-9 home directory of 3-38
delimited files, reading 3-273 overview 1-2
depreciation Server and 1-10
calculated using double-declining balance version of 3-42
method 3-117 Workspace and 1-3
straight-line depreciation 3-449 Double (data type) 3-165

Index-6 Docbasic User’s Guide

 converting to 3-56 error handlers
internal format 3-165 cascading 3-201
range of values 3-165 nesting 3-369
storage requirements 3-165 removing 3-369
double-declining balance method, used to calcu- resetting 3-199, 3-369
late depreciation 3-117 resuming 3-369, 3-417
dynamic arrays 3-27 error messages
compatible with Visual Basic B-2
compiler C-1
Docbasic-specific B-5
E runtime B-1
error trapping 3-201, 3-369
ebBoolean (constant) 3-167 Error, Error$ (functions) 3-203
ebCurrency (constant) 3-170 errors
ebEmpty (constant) 3-173 cascading 3-201
ebHidden (constant) 3-175 Docbasic-specific 3-202
ebInteger (constant) 3-176 Erl (function) 3-197
ebLong (constant) 3-177 Err (function) 3-198
ebNone (constant) 3-178 Err (statement) 3-199
ebNormal (constant) 3-179 Error (statement) 3-200
ebNull (constant) 3-180 Error, Error$ (functions) 3-203
ebObject (constant) 3-181 generating 3-200
ebReadOnly (constant) 3-182 getting error number of 3-198
ebSingle (constant) 3-183 getting line number of 3-197
ebString (constant) 3-184 getting text of 3-203
ebSystem (constant) 3-185 handling 3-201
ebSystemModal (constant) 3-186 On Error (statement) 3-369
ebVariant (constant) 3-187 range of values for 3-199
ebVolume (constant) 3-188 resetting state of 3-199
ebWin16 (constant) 3-39 Resume (statement) 3-417
Else (keyword) 3-267 resuming control after 3-201
ElseIf (keyword) 3-267 setting 3-199
embedded quotation marks 3-319 Stop (statement) 3-454
Empty (constant) 3-189 trapping 3-369
Empty, testing for 3-291 user-defined 3-202
End (statement) 3-190 converting to 3-101
end of file testing for 3-292
checking 3-192 writing to sequential files 3-509
checking for 3-192 Visual Basic compatibility with 3-201
end-of-line, in sequential files 3-275 escape characters, table of 3-382
entry points, Main (statement) 3-333 exclusive or operator (Xor) 3-513
Environ, Environ$ (functions) 3-191 EXECUTE (DQL statement) 1-10
environment variables, getting 3-191 executing procedures
EOF (function) 3-192 in Procedure Editor 2-17
equivalence operator (Eqv) 3-193 executing procedures, in Procedure Editor
Eqv (operator) 3-193 pausing execution of 2-17
Erase (statement) 3-195 stopping execution of 2-17
Erl (function) 3-197 Exit Do (statement) 3-162, 3-205
Err (function) 3-198 Exit For (statement) 3-207, 3-234
Err (statement) 3-199 Exit Function (statement) 3-209
Error (statement) 3-200 Exit Sub (statement) 3-210

Docbasic User’s Guide Index-7

exiting FileDirs (statement) 3-222
from Procedure Editor 2-29 FileExists (function) 3-224
exiting procedures 3-160 FileLen (function) 3-225
Exp (function) 3-211 FileList (statement) 3-226
exponentiation operator (^) 3-19 FileParse$ (function) 3-229
expressions files
evaluation of 3-212 attributes of
propagation of Null through 3-362 ebHidden (constant) 3-175
External (function) 3-214 ebNone (constant) 3-178
external routines ebNormal (constant) 3-179
calling 3-134 ebReadOnly (constant) 3-182
calling conventions of 3-138 ebSystem (constant) 3-185
passing parameters 3-134 ebVolume (constant) 3-188
data formats 3-138 getting 3-256
null pointers 3-138 setting 3-440
strings 3-137 used with Dir, Dir$ (functions) 3-152
using ByVal (keyword) 3-47 used with FileList (statement) 3-227
specified with ordinal numbers 3-141, 3-142, used with GetAttr (function) 3-256
3-143 attributes, used with SetAttr (statement) 3-440
under Macintosh 3-142 checking existence of 3-224
under Win32 3-142 checking for end of 3-192
under Windows 3-141 closing 3-75
closing all 3-416
copying 3-218
deleting 3-302
F end-of-line character 3-89
getting date and time of 3-220
file I/O getting length of 3-225
Close (statement) 3-75 getting list of 3-151, 3-226
EOF (function) 3-192 getting mode of 3-216
Get (statement) 3-252 getting next available file number 3-244
Input# (statement) 3-273 getting position within 3-321, 3-430
Line Input# (statement) 3-313 getting size of 3-325
Loc (function) 3-321 locking regions in 3-323
Lock (statement) 3-323 opening 3-372
Lof (function) 3-325 access capabilities 3-373
Open (statement) 3-372 modes 3-372
Print# (statement) 3-393 setting another process's access rights 3-373
Put (statement) 3-401 setting record length 3-373
Reset (statement) 3-416 truncating to zero length 3-373
Seek (function) 3-430 reading 3-273
Seek (statement) 3-432 reading binary data from 3-252
Spc (function) 3-452 reading lines from 3-313
Unlock (statement) 3-486 renaming 3-351
Width# (statement) 3-504 setting read/write position in 3-432
Write# (statement) 3-509 sharing 3-373
file numbers, finding available 3-244 splitting names of 3-229
file open dialog box 3-375 types of
FileAttr (function) 3-216 FileType (function) 3-231
FileCopy (statement) 3-218 getting 3-231
FileDateTime (function) 3-220 unlocking regions in 3-486

Index-8 Docbasic User’s Guide

 writing binary data to 3-401 defining 3-245
writing to 3-393, 3-509 exiting function 3-209
FileType (function) 3-231 naming conventions of 3-245
financial functions returning values from 3-246
DDB (function) 3-117 future value of annuity, calculating 3-250
Fv (function) 3-250 fuzzy string comparisons 3-311
IPmt (function) 3-284 Fv (function) 3-250
IRR (function) 3-286
MIRR (function) 3-342
NPer (function) 3-358
Npv (function) 3-360 G
Pmt (function) 3-387
PPmt (function) 3-389 generating random numbers 3-406
Pv (function) 3-404 Get (statement) 3-252
Rate (function) 3-408 GetAppInfo (function) 3-255
Sln (function) 3-449 GetAttr (function) 3-256
SYD (function) 3-467 GetSession (function) 3-260
finding global (public) variables 3-398
files 3-151 GoSub (statement) 3-261
strings 3-280 returning from 3-419
Fix (function) 3-233 Goto (statement) 3-263
fixed arrays 3-27
fixed-length strings
conversion between variable-length 3-458
declaring 3-147, 3-396, 3-398 H
passing to external routines 3-137, 3-140
within structures 3-481 handles, getting operating system file handles
floating-point values 3-216
Double (data type) 3-165 help
Single (data type) 3-446 in Procedure Editor 2-31
For...Next (statement) 3-234 Hex, Hex$ (functions) 3-265
exiting For loop 3-207 hexadecimal characters, in strings 3-382
formatting data hexadecimal strings
built-in 3-237 converting to 3-265
built-in formats converting to numbers 3-491
date/time 3-237 home directory 3-38
numeric 3-237 Hour (function) 3-266
in files
Spc (function) 3-452
Width# (statement) 3-504
user-defined formats 3-238 I
date/time 3-240
numeric 3-239 If...Then...Else (statement) 3-267
string 3-240 If...Then...End If (statement), shorthand for (IIf)
forward referencing, with Declare (statement) 3-269
3-25, 3-134 IIf (function) 3-269
FreeFile (function) 3-244 Imp (operator) 3-270
Function...End Function (statement) 3-245 implication operator (Imp) 3-270
Function...End Sub (statement), exiting function implicit variable declaration, with DefType
3-209 (statement) 3-144
functions

Docbasic User’s Guide Index-9

indexing collections 3-366
infinite loops, breaking out of 3-163, 3-164, 3-235,
K
3-502, 3-503
ini files keyboard shortcuts
reading items from 3-410 in Procedure Editor 2-3
reading section names from 3-411 keywords
writing items to 3-511 restrictions for 3-301
Inline (statement) 3-272 Kill (statement) 3-302
Input (keyword) 3-372
Input# (statement) 3-273
InputBox, InputBox$ (functions) 3-278
inserting text, in Procedure Editor 2-7
L
insertion point, moving, in Procedure Editor 2-6
to specified line 2-7 Labels 3-263
with mouse 2-6 labels
instantiation of OLE objects 3-85 in place of line numbers 3-315
InStr (function) 3-280 naming conventions of 3-263
Int (function) 3-282 used with GoSub (statement) 3-261
Integer (data type) 3-283 used with Goto (statement) 3-263
converting to 3-64 LBound (function) 3-304
range of values for 3-283 used with OLE arrays 3-304
storage requirements of 3-283 LCase, LCase$ (functions) 3-306
integer division operator () 3-18 least precise operand 3-378
intercepting (trapping) errors 3-201, 3-369 Left, Left$ (functions) 3-307
interest payments, calculating 3-284 Len (function) 3-308
internal rate of return, calculating 3-286, 3-342 Len (keyword), specifying record length 3-372
IPmt (function) 3-284 Let (statement) 3-310
IRR (function) 3-286 Lib (keyword) 3-134
Is (operator) 3-288 Like (operator) 3-311
IsDate (function) 3-290 line breaks, in MsgBox (statement) 3-348
IsEmpty (function) 3-291 line continuation 3-20
IsError (function) 3-292 in Procedure Editor 2-13
IsMissing (function) 3-248, 3-293, 3-464 Line Input# (statement) 3-313
IsNull (function) 3-294 line numbers 3-315
IsNumeric (function) 3-295 Line$ (function) 3-316
IsObject (function) 3-297 LineCount (function) 3-318
Item$ (function) 3-298 literals 3-319
ItemCount (function) 3-300 Loc (function) 3-321
iterating through collections 3-366 local variables
declaring 3-147
Lock (statement) 3-323
locking file regions 3-323
J Lof (function) 3-325
Log (function) 3-326
jumps logarithm function (Log) 3-326
GoSub (statement) 3-261 logarithms
Goto (statement) 3-263 Exp (function) 3-211
Return (statement) 3-419 Log (function) 3-326
logical constants
True (constant) 3-480
logical negation 3-354

Index-10 Docbasic User’s Guide

logical operators defined 3-365
And (operator) 3-23 invoking 3-366
Eqv (operator) 3-193 with OLE automation 3-363
Imp (operator) 3-270 Mid, Mid$ (functions) 3-337
Not (operator) 3-354 Mid, Mid$ (statements) 3-339
Or (operator) 3-384 Minute (function) 3-341
Xor (operator) 3-513 MIRR (function) 3-342
Long (data type) 3-327 MkDir (statement) 3-344
converting to 3-73 Mod (operator) 3-345
range of values 3-327 modes, for open files 3-216
storage requirements for 3-327 Month (function) 3-347
looping most precise operand 3-378
Do...Loop (statement) 3-162 MsgBox (function) 3-348
exiting Do loop 3-205 MsgBox (statement) 3-350
exiting For loop 3-207 constants used with
For...Next (statement) 3-234 ebSystemModal (constant) 3-186
lowercasing strings 3-306
LSet (statement) 3-328
LTrim, LTrim$ (functions) 3-330
N
Name (statement) 3-351
M naming conventions
of constants 3-81
MacID (function) 3-153, 3-303, 3-331, 3-443 of functions 3-245
Macintosh, MacID (function) 3-331 of labels 3-263
MacScript (statement) 3-332 of subroutines 3-462
Main (statement) 3-333 of variables 3-149
matching strings 3-311 negation
math functions logical 3-354
Abs (function) 3-21 unary minus operator 3-10
Atn (function) 3-33 nesting, For...Next (statement) 3-234
Cos (function) 3-84 net present value, calculating 3-360
Exp (function) 3-211 New (keyword) 3-148, 3-353, 3-436
Fix (function) 3-233 Next (keyword) 3-234
Int (function) 3-282 Not (operator) 3-354
Log (function) 3-326 Nothing (constant) 3-356
Randomize (statement) 3-407 used with Is (operator) 3-288
Rnd (function) 3-422 Now (function) 3-357
Sgn (function) 3-442 NPer (function) 3-358
Sin (function) 3-445 Npv (function) 3-360
Sqr (function) 3-453 Null
Tan (function) 3-471 checking for 3-294
Mci (function) 3-334 propagation of 3-362
memory vs. Empty 3-362
available within Docbasic 3-37 Null (constant) 3-362
total size for arrays 3-147 nulls, embedded within strings 3-458
menus, reference for numbers
in Procedure Editor 2-30 adding 3-8
messages, runtime error B-1 converting from strings 3-491
methods converting to strings 3-455

Docbasic User’s Guide Index-11

 floating-point 3-165, 3-446 converting to 3-368
getting sign of 3-442 converting to numbers 3-491
hexadecimal representation 3-319 OLE automation
IsNumeric (function) 3-295 automatic destruction 3-364
octal representation 3-319 CreateObject (function) 3-85
printing 3-391 creating objects 3-85
reading from binary/random files 3-252 default properties of 3-213
reading from sequential files 3-273 Object (data type) 3-363
testing for 3-295 Set (statement) 3-436
truncating 3-233, 3-282 On Error (statement) 3-369
writing to binary/random files 3-401 Open (statement) 3-372
writing to sequential files 3-393, 3-509 grep (Like 3-311
numeric operators operators
- (operator) 3-10 - (operator) 3-10
(operator) 3-18 (operator) 3-18
* (operator) 3-6 & (operator) 3-2
+ (operator) 3-8 * (operator) 3-6
/ (operator) 3-13 + (operator) 3-8
^ (operator) 3-19 / (operator) 3-13
= (operator) 3-15
> (operator) 3-15
>= (operator) 3-15
O ^ (operator) 3-19
And (operator) 3-23
Object (data type) 3-363 Eqv (operator) 3-193
storage requirements for 3-363 Imp (operator) 3-270
Objects Is (operator) 3-288
Workspace 1-6 Like (operator) 3-311
objects 3-365 Mod (operator) 3-345
accessing methods of 3-366 Not (operator) 3-354
accessing properties of 3-363, 3-365 Or (operator) 3-384
assigning 3-436 precedence of 3-377
assigning values to 3-365 precision of 3-378
automatic destruction 3-363 Xor (operator) 3-513
collections of 3-366 Option Base (statement) 3-147, 3-379, 3-396, 3-398
comparing 3-288, 3-366 Option Compare (statement) 3-380
creating 3-436 effect on InStr (function) 3-280
creating new 3-148, 3-353 effect on Like (operator) 3-311
declaring 3-147, 3-363, 3-365, 3-396 effect on string comparisons 3-79, 3-456
declaring as public 3-398 Option CStrings (statement) 3-382
defined 3-365 Optional (keyword) 3-136, 3-246, 3-462
instantiating 3-363 optional parameters
invoking methods of 3-363 checking for 3-293
OLE, creating 3-85 passed to functions 3-247
predefined, table of 3-367 passed to subroutines 3-463
testing for 3-297 passing to external routines 3-136
testing if uninitialized 3-288 passing to functions 3-246
using dot separator 3-363 passing to subroutines 3-462
Oct, Oct$ (functions) 3-368 Or (operator) 3-384
octal characters, in strings 3-382 ordinal values 3-141, 3-142, 3-143
octal strings Output (keyword) 3-372

Index-12 Docbasic User’s Guide

overflow, in assignment 3-16, 3-310 Preserve (keyword) 3-413
preserving elements while redimensioning ar-
rays 3-413
Print (statement) 3-391
P print zones 3-391, 3-393
Print# (statement) 3-393
pane, in Procedure Editor printing
edit 2-2 to stdout 3-391
separator 2-2 to viewports 3-391
watch 2-2 Private (keyword) 3-245, 3-462
parameters Private (statement) 3-396
passing by reference 3-46 private variables, declaring 3-396
passing by value 3-4, 3-47 Procedure Editor 2-1
to external routines 3-47, 3-134 application window 2-2
parentheses, used in expressions 3-4 comments, adding to procedure 2-12
parsing Debug menu 2-31
filenames 3-229 Edit menu 2-30
strings edit pane 2-2
by item 3-298 exiting from 2-29
by line 3-316 File menu 2-30
by words 3-506 Help menu 2-31
counting items within 3-300 insertion point, moving 2-6
counting lines within 3-318 to specified line 2-7
counting words within 3-508 with mouse 2-6
Pascal calling convention 3-135 instruction pointer 2-18
pasting text moving to another line in subroutine 2-19
in Procedure Editor 2-11 keyboard shortcuts
path separator editing 2-3
getting 3-41 general 2-3
on different platforms 3-90 pane separator 2-2
paths procedures
extracting from filenames 3-229 checking syntax of 2-15
specifying relative 3-91 navigating within 2-6
pausing procedure execution 3-448 pausing execution of 2-17
period (.), used to separate object from property running 2-17
3-12 stopping execution of 2-17
period (.), used with structures 3-12 Run menu 2-31
Pi (constant) 3-386 selection highlight 2-9
platform constants 3-39 statements, continuing on multiple lines 2-13
ebWin16 (constant) 3-39 status bar 2-2
Pmt (function) 3-387 text
portability of compiled code 3-89 copying 2-11
Postprocessing 1-4 cutting 2-11
PPmt (function) 3-389 deleting 2-9
precedence of operators 3-377 inserting 2-7
precision pasting 2-11
loss of 3-16 replacing 2-14
of operators 3-378 searching for 2-13
predefined objects, table of 3-367 selecting 2-8
Preprocessing 1-4 toolbar 2-2
present value, calculating 3-404 undoing editing operations 2-11

Docbasic User’s Guide Index-13

 watch pane 2-2 3-119
procedures renaming files 3-351
exiting 3-160 replacing text, in Procedure Editor 2-14
tracing calls of, in Procedure Editor 2-19 Reset (statement) 3-416
procedures,calling from another procedure object resetting error handler 3-369
3-214 Resume (statement) 3-201, 3-369, 3-417
proceduress, debugging, in Procedure Editor 2-1 Return (statement) 3-419
promotion Right, Right$ (functions) 3-420
automatic 3-378 RmDir (statement) 3-421
properties Rnd (function) 3-422
accessing 3-365 rounding 3-212
defined 3-365 RSet (statement) 3-423
with OLE automation 3-363 RTrim, RTrim$ (functions) 3-425
Public (keyword) 3-245, 3-462 running other programs 3-443
Public (statement) 3-398 runtime errors B-1
public variables, declaring 3-398
Put (statement) 3-401
Pv (function) 3-404
S
scoping
R of constants 3-82
of object variables 3-436
radians, converting to degrees 3-33 searching for text, in Procedure Editor 2-13
Random (function) 3-406 Second (function) 3-429
Random (keyword) 3-372 seed, for random number generator 3-407
random files Seek (function) 3-430
opening 3-372 Seek (statement) 3-432
reading 3-252 Select...Case (statement) 3-434
setting record length 3-373 selecting text, in Procedure Editor 2-8
writing to 3-401 sequential files
random numbers opening 3-372
generating reading 3-273
between 0 and 1 3-422 reading lines from 3-313
within range 3-406 writing to 3-393, 3-509
initializing random number generator 3-407 Server API methods
Randomize (statement) 3-407 calling 1-5
Rate (function) 3-408 Set (statement) 3-436
Read (keyword) 3-372 SetAppInfo (function) 3-438
ReadIni$ (function) 3-410 SetAttr (statement) 3-440
ReadIniSection (statement) 3-411 Sgn (function) 3-442
recursion 3-246, 3-463 Shared (keyword) 3-372
Redim (statement) 3-413 sharing
redimensioning arrays 3-413 files 3-373
Redirecting Workspace methods 1-3 sharing variables 3-399
reference counting 3-363 Shell (function) 3-443
regular expressions, with Like (operator) 3-311 sign, of numbers 3-442
relaxed type checking 3-25 Sin (function) 3-445
Rem (statement) 3-415 sine function (Sin) 3-445
remainder, calculating 3-345 Single (data type) 3-446
remote execution, with DDEExecute (statement) conversion to 3-92

Index-14 Docbasic User’s Guide

 range of values 3-446 concatenation 3-2, 3-8
storage requirements 3-446 vs. addition 3-2, 3-8
Sleep (statement) 3-448 converting from numbers 3-455
Sln (function) 3-449 converting to 3-94
sounds converting to lowercase 3-306
Beep (statement) 3-43 converting to numbers 3-491
Mci (function) 3-334 converting to uppercase 3-485
Space, Space$ (functions) 3-451 copying 3-328, 3-423
Spc (function) 3-392, 3-394, 3-452 counting items within 3-300
special characters 3-62 counting lines within 3-318
escape characters 3-382 counting words within 3-508
Sqr (function) 3-453 escape characters in 3-382
square root function (Sqr) 3-453 finding one within another 3-280
Global (statement) (Public 3-398 fixed-length vs. variable-length 3-458
Static (keyword) 3-245, 3-462 fixed-length, declaring 3-147, 3-396, 3-398
status bar getting leftmost characters from 3-307
in Procedure Editor 2-2 getting length of 3-308
stdout, printing to 3-391 getting rightmost characters from 3-420
Step (keyword) 3-234 getting substrings from 3-337
Stop (statement) 3-454 of same characters 3-460
stopping procedure execution 3-190, 3-454 of spaces 3-451
storage parsing by item 3-298
for fixed-length strings 3-459 printing 3-391
Str, Str$ (functions) 3-455 reading from sequential files 3-273, 3-276, 3-313
straight-line depreciation 3-449 requesting from user 3-278
StrComp (function) 3-456 retrieving items from 3-298
String (data type) 3-458 retrieving lines from 3-316
string functions retrieving words from 3-506
Item$ (function) 3-298 setting substrings in 3-339
LCase, LCase$ (functions) 3-306 String (data type) 3-458
Left, Left$ (functions) 3-307 trimming leading and trailing spaces from
Len (function) 3-308 3-479
Line$ (function) 3-316 trimming leading spaces from 3-330
LTrim, LTrim$ (functions) 3-330 trimming trailing spaces from 3-425
Mid, Mid$ (functions) 3-337 writing to sequential files 3-393, 3-509
Option Compare (statement) 3-380 Sub...End Sub (statement) 3-462
Right, Right$ (functions) 3-420 exiting subroutine 3-210
RTrim, RTrim$ (functions) 3-425 subroutines
Space, Space$ (functions) 3-451 defining 3-462
StrComp (function) 3-456 exiting subroutine 3-210
String, String$ (functions) 3-460 naming conventions of 3-462
Trim, Trim$ (functions) 3-479 substrings
UCase, UCase$ (functions) 3-485 finding 3-280
Word$ (function) 3-506 getting 3-337
string operators getting leftmost characters from 3-307
& (operator) 3-2 getting rightmost characters from 3-420
+ (operator) 3-8 setting 3-339
Like (operator) 3-311 sum of years' digits depreciation 3-467
String, String$ (functions) 3-460 Switch (function) 3-466
strings SYD (function) 3-467
comparing 3-79, 3-311, 3-380, 3-456 syntax, checking, in Procedure Editor 2-15

Docbasic User’s Guide Index-15

System 7.0 3-332 used when converting to number 3-295
System calling convention 3-135 used when declaring literals 3-319
used with Dim (statement) 3-148
used with external subroutines and functions
3-135
T
Tab (function) 3-392, 3-394
Tan (function) 3-471 U
tangent function (Tan) 3-471
time UBound (function) 3-483
forming from components 3-476 UCase, UCase$ (functions) 3-485
getting current time 3-357, 3-472 unary minus operator 3-10
getting specific time 3-476 underflow 3-16
hours 3-266 undo
minutes 3-341 in Procedure Editor 2-11
seconds 3-429 uninitialized objects 3-363, 3-365
seconds since midnight 3-475 Nothing (constant) 3-356
setting current time 3-473 testing for with Is (operator) 3-288
Time, Time$ (functions) 3-472 universal date format
Time, Time$ (statements) 3-473 reading 3-274
Timer (function) 3-475 used with literals 3-103, 3-319
TimeSerial (function) 3-476 writing 3-509
TimeValue (function) 3-477 Unlock (statement) 3-486
toolbar unlocking file regions 3-486
in Procedure Editor 2-2 unsupported language elements 3-89
trigonometric functions uppercasing strings 3-485
Atn (function) 3-33 user-defined errors
Cos (function) 3-84 converting to 3-101
Sin (function) 3-445 generating 3-200
Tan (function) 3-471 testing for 3-292
Trim, Trim$ (functions) 3-479 writing to sequential files 3-509
trimming user-defined types 3-489
leading and trailing spaces from strings 3-479 copying 3-489
leading spaces from strings 3-330 declaring 3-489
trailing spaces from strings 3-425 defining 3-481
True (constant) 3-480 getting size of 3-308, 3-490
truncating numbers 3-233, 3-282 passing 3-490
Type (statement) 3-481
type checking, relaxed, with Declare (statement)
3-25
type coercion 3-212 V
type-declaration characters
effect on interpretation when reading numbers Val (function) 3-491
from sequential files 3-273 variables
for Currency 3-98 assigning objects 3-436
for Double 3-165 declaring
for Integer 3-283 as local 3-147
for Long 3-327 as private 3-396
for Single 3-446 as public 3-398
for String 3-458 with Dim 3-147

Index-16 Docbasic User’s Guide

 with Private (statement) 3-396
with Public (statement) 3-398
W
getting storage size of 3-308
implicit declaration of 3-148 watch variables, in Procedure Editor 2-24
initial values of 3-148, 3-397 adding 2-24
naming conventions of 3-149 deleting 2-26
watch, in Procedure Editor 2-24 modifying value of 2-27
Variant (data type) 3-493 selecting 2-25
variants waveform audio, Mci (function) 3-334
adding 3-9, 3-495 Weekday (function) 3-500
assigning 3-494 While...Wend (statement) 3-502
automatic promotion of 3-378 Width# (statement) 3-504
containing no data 3-362, 3-495 wildcards
converting to 3-99 used with Dir, Dir$ (functions) 3-151
disadvantages 3-496 win.ini file 3-115, 3-243, 3-410, 3-412, 3-477, 3-511
Empty (constant) 3-189 Word$ (function) 3-506
getting length of 3-308 WordCount (function) 3-508
getting types of 3-493, 3-498 word-wrapping, in MsgBox (statement) 3-348
Null (constant) 3-362 Workspace API methods
operations on 3-494 calling 1-5
passing nonvariant data to routines taking Workspace objects 1-6
variants 3-496 Write (keyword) 3-372
passing to routines taking nonvariants 3-496 Write# (statement) 3-509
printing 3-391 WriteIni (statement) 3-511
reading from sequential files 3-273
storage requirements of 3-495
testing for Empty 3-291
testing for Error 3-292
X
testing for Null 3-294
testing for objects 3-297 Xor (operator) 3-513
types of 3-493, 3-498
ebBoolean (constant) 3-167
ebCurrency (constant) 3-170
ebDate (constant) 3-172 Y
ebEmpty (constant) 3-173
ebError (constant) 3-174 Year (function) 3-515
ebInteger (constant) 3-176 yielding 3-448
ebLong (constant) 3-177
ebNull (constant) 3-180
ebObject (constant) 3-181
ebSingle (constant) 3-183
ebString (constant) 3-184
ebVariant (constant) 3-187
Variant (data type) 3-493
writing to sequential files 3-393, 3-509
VarType (function) 3-498
version
of Docbasic 3-42
viewports
printing to 3-391
Visual Basic, error messages B-2

Docbasic User’s Guide Index-17

Index-18 Docbasic User’s Guide