Sie sind auf Seite 1von 648

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.

Chapter 1 Table of Contents Preface Using Docbasic What is Docbasic? 1-2 Benefits of Using

Chapter 1

Table of Contents

Preface

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

 

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

 

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

* (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

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

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

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

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

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

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

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

 

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

Preface Purpose of the Manual This book helps application developers create Docbasic procedures. It presents

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.

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.

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.

1
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

What is Docbasic?

What is Docbasic?

Using 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.

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.

2.

3.

4.

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

Workspace event

method

,*,basic,/ProcCabinet/ProcFile,proc Workspace event method Sub proc(Mthd As String) REM Mthd= “method” Figure 1-1

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.

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

 
Redirected method   (Optional)

(Optional)

    Redirected method   (Optional) Sub Procedure(Mthd As String)   '

Sub Procedure(Mthd As String)

 

'

Pre-processing code

 
 

' use any DocBasic commands

 
 

ret$ = dmAPIGet(method, ret% = dmAPISet(method,

)

)

 

'execute Workspace methods

 

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

Passing the Method

Summary of Procedure Code to Override a 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:

Postprocessing

dmAPIExec(Mthd)

To perform postprocessing, a procedure follows these steps:

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.

Using Docbasic with Workspace

Using Docbasic

The following illustration summarizes how Workspace handles methods you call from Docbasic procedures. Sub
The following illustration summarizes how Workspace handles methods you call
from Docbasic procedures.
Sub Procedure(Mthd As String)
)
'execute Workspace methods
Procedure
ret$ = dmAPIGet(method,
ret% = dmAPISet(method,
ret% = dmAPIExec(method,
)
)
End Sub
Workspace
Server API
API method
method
Workspace
Action
code
Client
Library

Figure 1-3

How Workspace Handles Method Calls from Procedures

Server

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.)

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.

3.

4.

Creation of dialog box

Creation of dialog box

Creation of dialog box Modal method

Modal method

2. 3. 4. Creation of dialog box Modal method Sub HandleModal(Mthd As String)   ret$ =

Sub HandleModal(Mthd As String)

 

ret$ = dmAPIGet(getdata, ret% = dmAPISet(setdata, ret% = dmAPIExec(Mthd)

)

'retrieves object attribute values

)

'modifies object attributes

' returns Modal method to Workspace

End Sub

 
 

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")

Using Docbasic with Workspace

Obtaining the Values of Objects

Using Docbasic

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.

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

Using Docbasic with the Server

Using Docbasic with the Server

Using Docbasic

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.

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.

Using Docbasic with the Server

Table 1-1

Dmbasic arguments

Using Docbasic

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:

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

Using Docbasic with the Server

Using Docbasic

2
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

Procedure Editor Basics

Procedure Editor Basics

Editing and Debugging Docbasic Procedures

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.

Editing and Debugging Docbasic Procedures

Toolbar Tools

Table 2-1

Toolbar Buttons

Procedure Editor Basics

Button Face

Tool

Function

StartRuns a procedure.

Runs a procedure.

EndFace Tool Function Start Runs a procedure. Toggle Breakpoint Add Watch Calls Single Step Procedure Step

Toggle BreakpointFace Tool Function Start Runs a procedure. End Add Watch Calls Single Step Procedure Step Keyboard

Add WatchStart Runs a procedure. End Toggle Breakpoint Calls Single Step Procedure Step Keyboard Shortcuts Stops

CallsStart Runs a procedure. End Toggle Breakpoint Add Watch Single Step Procedure Step Keyboard Shortcuts Stops

Single StepRuns a procedure. End Toggle Breakpoint Add Watch Calls Procedure Step Keyboard Shortcuts Stops execution of

Procedure Stepprocedure. End Toggle Breakpoint Add Watch Calls Single Step Keyboard Shortcuts Stops execution of a procedure.

Keyboard Shortcuts

Stops execution of a procedure.

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

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.

Displays the list of procedures called by the currently executing Docbasic procedure. Available only during break mode.

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.

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.

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.

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.

Editing and Debugging Docbasic Procedures

Procedure Editor Basics

Table 2-4

Editing Shortcuts

Key(s)

Function

Shift + any navigating shortcut

Selects all text between the initial location of the insertion point and the 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.

Editing Your Procedures

Editing Your Procedures

Editing and Debugging Docbasic 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.

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

your procedure to which you want to move the insertion point 3. Click OK or press

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

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

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.

Editing Your Procedures

To delete text

Editing and Debugging Docbasic Procedures

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.

Editing and Debugging Docbasic Procedures

To cut a selection

Editing Your Procedures

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

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.

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.

Editing Your Procedures

Editing and Debugging Docbasic Procedures

Procedure Editor displays the Find dialog box.

Procedures Procedure Editor displays the Find dialog box. 3. In the Find What field, type the

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.

Editing and Debugging Docbasic Procedures

Editing Your Procedures

Procedure Editor displays the Replace dialog box.

Procedures Procedure Editor displays the Replace dialog box. 3. In the Find What field, type the

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.

Editing Your Procedures

2. Click OK or press Enter.

Editing and Debugging Docbasic Procedures

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.

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.

Debugging a Procedure

Debugging a Procedure

Editing and Debugging Docbasic Procedures

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).

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.

in the course of arriving at the present subroutine. 2. From the Calls dialog box, select

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.

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.

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.

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.

Editing and Debugging Docbasic Procedures

Removing Breakpoints

Setting and 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.

Using Watch Variables

Using Watch Variables

Editing and Debugging Docbasic Procedures

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 structures called company

age

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.

Editing and Debugging Docbasic Procedures

Using Watch Variables

Procedure Editor displays the Add Watch dialog box.

Procedure Editor displays the Add Watch dialog box. 2. Use the controls in the Context 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