CA-Clipper for DOS Version 5.3 Programming and Utilities Guide

7/22/2019 CA-Clipper for DOS Version 5.3 Programming and Utilities Guide

http://slidepdf.com/reader/full/ca-clipper-for-dos-version-53-programming-and-utilities-guide 1/716

CA ClippefFor DOS

Ve rsion 5.3

Programming and Utilities Guide

June 1995

(AOMPUTERftSSOCI TESSoftware superior by design F



© Copyright 1995 Comp uter Associates International, Inc.,One Com puter Associates Plaza, Islandia, NY 11788-7000All rights reserved.

Printed in the United States of AmericaComputer Associates International, Inc.Publisher

No part of this documentation m ay be cop ied, photocopied, reproduced, translated, microfilmed,or otherwise duplicated on any m edium w ithout written consent of Computer AssociatesInternational, Inc.

Use of the software programs described herein and this documentation is subject to the ComputerAssociates License Agreement enclosed in the software pa ckage.All product names referenced herein are trademarks of their respective companies.



Contents

C h a p t e r : IntroductionIn This Guid e 1-1Part 1: Basic Con cepts 1-2Part 2: Progra mm ing 1-2

Part 3: Utili t ies 1-3

Chapter 2 : Basic ConceptsIn This Cha pter 2- 1The S t ruc ture of a CA-Cl ipper Program 2- 2

A Typica l CΑ-C l ipper Program 2- 3The Ma in Procedure Defini t ion 2 -4Funct ion and Procedu re Cal ls 2 -5Variable Declarat ion 2 -6Funct ion and Procedu re Defini t ions 2 -7Preprocessor Direct ives 2 -8Commen t s 2 -8Cont inua t ion 2-9Reserved W ords 2- 10

Funct ions and Procedures 2- 10Defining Funct ions and Proced ures 2- 11Cal l ing Funct ions and Procedures 2- 13Pass ing Parameters 2- 14Pass ing by Value 2- 16Pass ing by Reference 2- 17Pass ing Arrays and Objec ts as Argum ents 2- 18Argum ent Checking 2- 19

Pro gram min g a n d Util it ies Gu ide iii



Pass ing Argum ents f rom the DO S Com ma nd Line 2-2 0Return ing Values f rom Funct ions 2-2 0Recurs ion 2-21

Con trol Structures 2- 22Looping St ruc tures 2-2 2

FOR. . .NEXT 2-23D O W H I L E .. .E N D D O 2 - 2 3EXIT and LO OP 2-2 4

Decis ion-Making St ruc tures 2-2 5IF. . .ENDIF 2-25DO CASE. . .ENDCA SE 2 -26

Error Ha ndling Structures 2- 26Variables 2-27

Lexica lly Scoped Versus Dyna mica l ly Scoped Var iab les 2-2 7Lifet ime and Visibi l i ty of Variables 2- 28Declar ing Variables 2- 29The Scope of a Declarat ion 2- 30Referr ing to Variables 2- 31Am biguou s Var iab le References 2-3 2

Avoid ing Am biguou s Var iab le References 2-3 2Qu alifying Variable References 2- 33

Creat ion and Ini t ia lizat ion 2- 33Local Variables 2- 34Stat ic Variables 2- 35Private Variables 2- 36Public Variables 2- 37Field Variables 2- 38

Expressions 2-39Data Types 2-4 0

Character 2-40

Memo 2 -42Date 2-43Numer ic 2-45Logical 2-46NIL 2-47

iv CA-Clipper



Operators 2-48Terminology 2-48Error Han dling 2- 50Str ing Operators 2- 50Date Operators 2- 51Mathe matical Operators 2- 51Relat ional Ope rators 2- 52Logical Ope rators 2- 53Ass ignment Opera tors 2-5 4

Simple Ass ignment 2-5 5Inl ine Assign men t 2- 56Com pound Ass ignments 2- 57

Increment and Dec reme nt Ope rators 2- 58Special Ope rators 2- 60Operator Preceden ce 2- 61

Precedence of Catego ries 2- 62Precedence within a Catego ry 2- 63Preincremen t and Predec reme nt 2- 63Mathemat ica l 2-64Relat ional 2-64Logical 2-64Ass ignment 2-65Post increment and Postdecrem ent 2- 65Parentheses 2-65

The Macro Opera tor 2-6 6Text Subst i tut ion 2- 67Comp i le and Run 2- 68Rela tionship to Com ma nds 2-6 9

Using wi th Com man d Keyw ords 2-6 9Using wi th Com man d Argum ents 2-6 9Using with Lists 2- 71

Macro s and Arrays 2- 71Macros and Code Blocks 2- 72Using wi th Database Com man d Condi t ions 2- 73Invoking Procedu res and Funct ions 2- 73External References 2- 74Nested Ma cro Defini t ions 2- 74

Prog ram ming a n d Utilit ies G uid e ν



Arrays 2-75Creat ing Array s 2-7 5Add ress ing Array Elements 2-76Assigning Values to Array Elemen ts 2-7 7M ult idimension al Arrays 2-7 9Literal Array s 2-8 0Arrays as Function Arg um ents and Return Values 2-8 1Traversing an Array 2-8 2

FOR. . .NEXT 2-82AEVAL() 2 -82

Emp ty Arrays 2-83Determ ining the Size of an Array 2-8 4

Com par ing Arrays 2-84Chan ging the Size of an Array 2-8 5Insert ing and Delet ing Array Elem ents 2-8 6Copy ing Eleme nts and Duplicat ing Arrays 2-8 6Sort ing an Array 2-8 7Searching an Array 2-8 8

Cod e Blocks 2-8 9Defining a Cod e Block 2-8 9Executing a Cod e Block 2-9 0

Scope of Variables W ithin a Cod e Block 2-9 0Using Cod e Blocks 2-9 2Evaluat ion of M acros in Co de Blocks 2-9 3Storing and Com pil ing Cod e Blocks at Run time 2-9 5

Objects and M essages 2-9 6Classes 2-96Instances 2-97Instance Variables 2-9 8Sending Messages 2-98

Accessing Exported Instance Variables 2-9 9The Database Sys tem 2-10 0

Wo rk Areas 2-101Access ing W ork Areas 2-101W ork Area Attr ibutes 2-1 04

vi CA-Clipper



Database Fi les 2- 10 5M emo Fi les 2-1 05Database Fi le Attr ibutes 2- 10 6Database Operat ions 2- 10 6Record Scoping 2-1 07The Record Process ing Pr imi t ive—D BEVA L() 2-1 09

Index Fi les 2- 10 9Crea t ing 2-110Opening 2-110Order ing 2-111Searching 2-111Updat ing 2-112Clos ing 2-112

The Inpu t /Ou tpu t Sys tem 2-1 13Text Mo de 2-1 13Graphic M ode 2-1 13Console Operat ions 2- 11 5Full-Screen Operat ions 2- 11 6Control l ing Screen Color 2- 11 7Control l ing Outpu t Dest inat ion 2- 11 7

Direct ing Ou tput to the Printer 2- 11 7Direct ing Ou tput to a Fi le 2- 11 9

The Keyboard Sys tem 2-1 20Chan ging the Keybo ard Buffer Size 2- 12 0Putt ing Characters in the Keyb oard Buffer 2-1 21Reading Characters from the Keyb oard Buffer 2-1 21Control l ing Predefined Keys 2- 12 2Reassigning Key Defini t ions 2- 12 3Clearing the Keyb oard Buffer 2- 12 3

The Low -Level Fi le System 2- 12 4Open ing a Fi le 2- 12 4Reading from a Fi le 2- 12 5Writ ing to a Fi le 2- 12 5Ma nipulat ing the Fi le Pointer 2- 12 6Closing a Fi le 2- 12 6Error Detect ion 2- 12 7

Prog ram ming a nd Utilit ies G uid e vii



C ha pt er 3: The Runtime EnvironmentIn This Chap ter 3- 1Sett ing the W orkstat ion Env ironm ent 3- 2

Files and Buffers 3 -3Changing the DO S Environment S ize 3-4Specifying the Location of Executab le Fi les 3- 4

Tem porary Fi les 3- 5Specifying the Location ofC O M M A N D . C O M 3-5Configuring the Serial Port 3- 6

Sett ing the Ap plicat ion Env ironm ent 3- 7Appl ica t ion Com ma nd Line 3-9

The CLIPPE R Environm ent Var iable 3-9Sav ing /Res to r ing EM M Page F ram e—B AD CA CH E 3-10Preven ting Ex tended Curso r Use— CG AC UR S 3 -10Speci fy ing Num ber of Dyn amic Over lay Fi le Han dles— DY NF 3-1 0Conf igu r ing Expanded Mem ory— Ε 3-11Specifying the Nu m ber of Fi les— F 3-1 2Displaying M em ory Conf igura t ion Deta il s a t S tar tup— INFO 3-1 2Prevent ing Detec t ion of Id le Tim e— NO IDLE 3-1 3Speci fy ing Ma xim um Swa p Fi le S ize— SW APK 3-1 4

Speci fy ing Swap Fi le Loca t ion— SW AP PΑ ΤΗ : 3-1 4Speci fy ing Tem porary Fi le Locat ion — TEM PPA TH 3-1 4Excluding Avai lab le M em ory— X 3-1 5The BLIN KER Environm ent Var iable 3-1 5

Con t ro l li ng Am oun t o f EMS M em ory— /CEn nn ,nn 3 -16Con t ro l li ng Am oun t o f XM S Me mo ry— /CXn nn ,nn 3 -16Contro ll ing Opera t ing Size of Bl inker Over lay Po ol— /OO nn n 3-1 6Contro ll ing Al loca tion of Over lay Po ol— /O Pc 3-1 7Contro ll ing Al loca tion of Over lay Po ol— /O U c 3-1 7

Sett ing the Netw ork Env ironm ent 3- 17Netw ork Hardw are Requi rements 3-1 7Assigning Rights 3- 18Set ting Up Netw ork Devices 3-1 9

The App licat ion Batch File 3-2 0

viii CA-Clipper

http://command.com/

http://command.com/



Chapter 4 : Network ProgrammingIn This Chap ter 4- 1LAN Requi rements for CA-Cl ipper 4- 3Using Shared Mo de 4- 3

W hen to Obtain Exclusive Use 4 -4Other Fi le Op en Ope rat ions 4 -4Retrying After an Op en Fai lure 4 -6

Locking 4-7File Locking 4- 9Record Locking 4 -9Automat ic Locking 4- 10Unlocking 4-11

Resolving a Fai lure 4 -1 2Over lays on a Network 4- 13Upd ate Visibi li ty 4- 14

The Ini tia tor 4- 14The Operat ing System and Other Processes 4- 14The Physical Disk 4- 15Abnorm al Terminat ion 4- 16

Netw ork Print ing 4- 16Sett ing Up the Netw ork Printer 4- 1 7Program Des ign Cons idera t ions 4- 17Printing to a File 4 -1 8

Pro gra m m ing a n d Utilities G uid e ix



Ch apter 5 : Programm ing in G raph ic M o d eIn This Cha pter 5- 1Overview of Graphic Mo de 5-2

Prog ram min g Similar i t ies 5- 2Program ming Diffe rences 5-3

The Text M ode Technique 5-3The Graphic M ode Technique 5-4

Invoking Graphic Mo de 5-5Using Graphic Mo de 5-6

Shad ow ing Restr ict ions 5- 7Enha ncing an Ap plicat ion 5- 8

Tips and Techniques 5-9Push Buttons 5- 9Bitma ps and Icons 5- 9X /Y and Ro w /C o lu m n Coord inat e s 5 -9

Com pil ing and Linking : 5- 10Man aging Bi tmap and Font Resources 5-1 1

RES2BML.EXE 5 -11B M L 2 R E S . C O M 5-12B M L D I R . C O M 5-12

Using Bitmap and Font Library Fi les 5- 13Troubleshoot ing 5-14

Com mon P rob lems 5 -14Sof tware Com pat ib i li ty 5-1 6Hardw are Com pat ib i li ty 5-1 7Me mo ry Shor tage 5-1 8

χ CA-Clipper

http://bml2res.com/

http://bmldir.com/

http://bmldir.com/

http://bml2res.com/



Chapter 6 : Introduction to TBrowse

Prog ram ming a n d Utilit ies G uid e xi

In This Chap ter 6- 1TBrow se Overv iew 6-2Basic Brow se Operat ions 6- 3

Creat ing TBrow se Objects 6- 3Main Loop 6-4

Stabi l izat ion 6-5Han dling Keystrokes 6- 6

Optim izat ion of the Brow se 6- 7Calculated Fields, Picture Clause s, and Cu stom Hea ders 6- 7Qu icker Respon se Tim e 6- 8M ult i -User Issues 6- 9Reposi t ioning the Record Pointer 6- 10Us ing TBrow sexa rgo and TBC olum nxargo 6 -12

Brow sing with Get 6- 13Determining W hether the Record Has Mo ved 6-1 6

Adding Color 6-1 8TBrowse:colorSpec 6-18TBColumn:defColor 6-19TBColumn:colorBlock 6-20Control l ing the Highligh t 6- 22TBrowse:colorRect() 6-23

Control l ing the Scope 6- 24View ing a Specif ic Key Valu e 6- 26Brow sing Search Resul ts 6- 30



Chapter 7 : Introduction to the Get SystemIn This Chap ter 7-1

The Get Class 7-2Creat ing Get Objects 7-2Ge tb lock 7 -3Sett ing and Retr ieving Value s 7-4Ge txa rgo 7 -5Get Class Protocol 7-6

The Get System 7-7The Read Layer 7-8Extending the Read Layer 7-9

Nested Reads 7-9Using GET ACT IVE() 7-10

Changing Gets Through SET KEY s 7-10Imp roving Help Routines 7-1 2

Us ing Code B locks fo r W H EN /V A LI D 7 -14Dy nam ic Pictures 7-1 4

Proce ssing the Entire GetL ist 7-1 6Creat ing a Ne w Read Layer 7-1 7

Basic Gu idel ines 7-1 7

Impo rtant Imp lemen tat ion Rules 7-18Implem entat ion Steps 7-19REA D VAL ID 7 -19Gets W ith M essages 7-22

The Reader Layer 7-2 5Creat ing Ne w Read er Layers 7-2 6

Basic Gu idel ines 7-26Impo rtant Imp lemen tat ion Rules 7-27Incremen tal Date Get 7-2 8

The Get Funct ion Layer 7-31Creat ing Ne w Get Funct ion Layers 7-32

xii CA-Clipper





C h a p te r 9 : Error H an dlin g StrategiesIn This Chap ter 9- 1Overview of Exception Ha ndling Conc epts 9- 2

Error Scoping 9- 4Raising Errors 9- 6Han dling Errors 9-8

CA-Cl ipper Except ion Mech anisms 9-1 0The SEQ UEN CE Cons t ruc t 9-11The Posted Error Block 9- 16SEQ UEN CE vs . Er ror Block 9-1 9

Error Objects 9- 21A Mod el Examp le 9-2 3The "Syste m Erro r" Line-U p: Error.ch 9-2 4Carrying Error-Processing Protocols 9-2 5

A Basel ine Strategy 9- 28A Com prehens ive Exam ple 9-3 0Wh at Belongs in REC OV ER? 9-32

Netw ork Processing 9- 37

C h a p t e r 1 0 : C A - C l ip p e r C o m p i le r -C U P P E R . E X EIn This Chapter 10 -1Invoking the CA -Clipper Com piler 10 -2Us ing CLIPPER CM D 10-3Com pi le r Opt ions 10-4Th e Com piler Script Fi le 10 -9The Com piler Return Cod e 10 -9Ho w the CA-C lipper Preprocessor W orks · 10 -10Ho w CA-Cl ipper Com pi les 10-1 2

The Com pile and Link Batch Fi le 10- 13Hea der Fi les 10 -14Outp ut Fi les 10 -15

Object Files 10 -1 5Tem porary Fi les 10- 15Preprocessed Ou tput List ing 10 -16

Chan ging the Size of the Environ men t 10- 16

xiv CA-Clipper



Ch apter 11 : CA-C l ippe r Pro tec ted M o d eLinker-EXOSPACE.EXEIn This Chap ter 11 -1Overview of CA-Cl ipper /Exo spa ce 11- 2Invoking CA -Cl ipper /E xospa ce 11- 4The CA -Cl ipper /Ex ospace Return Code 11- 7The Com pile and Link Batch File 11 -7Output F i les H - 8

Executable Fi les (.EXE) . . 11 -8Map Files (.MAP) 11 -9

Tem porary Fi les 11 -9How CA -Cl ipper /E xospac e Searches for F i les 11-1 0

Library Files (.LIB) 11-10Object Files (.OBJ) 11-11Script Files (.LNK) 11-11

Linker Com man d Reference 11-1 2Com patibi l ity with Othe r Linkers 11 -13

.RTLink Com patibi l i ty 11- 13Blinker Com patibi l ity 11 -14

EXOSPA CE CLIPPER 501 11 -15E X O S PA C E E N V I R O N M E N T C L I P P E R 11 - 1 6E X O S PA C E E N V I R O N M E N T O V E R R I D E 11 - 1 7E X O S PA C E E X E C U TA B L E C L I P P E R 11 - 1 8E X O S PA C E E X E C U TA B L E N O D E L E T E 11 - 2 0E X O S PA C E PA C K A G E 11 - 2 1E X O S PA C E P R O C E D U R E D E P T H 11 - 2 3F I L E H - 2 4LIBRARY 11-25MAP 11-26MODULE. . .FROM 11-27NODEFLIB 11-28OUTPUT 11-29STACK 11-30

Prog ram ming a n d Utilities Gu ide xv



Troubleshoot ing 11-31If the App licat ion Doe s No t Run 11- 31

Ho w Does I t Fai l? 11-3 3Software Com patibi l i ty 11-3 5

M emo ry Shor tage 11-38Extended M em ory Not Avai lab le 11-3 8Using the High M em ory Area 11-38Bad Mem ory 11 -39

Problems W hen Runn ing Und er DPM I 11-40Problem s in Third -Party Librar ies 11- 41Envi ronm ent Com pat ib il i ty I ssues 11-4 2

PC /A T Compa t ib i li ty 11 -42

Ex tended Mem ory 11 -43DO S Vers ions 11-47

C ha pter 12 : C A -C lipp er Real M o d e Linker—BLINKER.EXEIn This Ch apter 12 -1Ov erview of Blinker 12- 2

Upg rade Offer 12-3Bl inker Com ma nd Reference 12-4

# (comm ent ) 12-4/ / (com men t) 12- 5@ (nested script) 12 -5B E G I N A R E A 1 2 - 6B L I N K E R C A C H E E M S 1 2 - 7B L I N K E R C A C H E X M S 1 2 - 8BLINK ER CLIPPER PAG E 12 -9

B L I N K E R E N V I R O N M E N T C L I P P E R 1 2 - 9B L I N K E R E N V I R O N M E N T N A M E 1 2 - 1 0B L I N K E R E N V I R O N M E N T O V E R R I D E 1 2 - 11B L I N K E R E X E C U TA B L E C L I P P E R 1 2 - 1 2B L I N K E R E X E C U TA B L E N O D E L E T E 1 2 - 1 4BLINK ER LINK EM S 12 -14

xvi CA-Clipper



BLINKER LINK PAGEFRAM E 12-15BLINKER LINK XMS 12-15BLINKER MESSAGE DUPLICATES 1 2 - 1 6BLINKER MESSAGE NOBLINK 12-17BLINKER MESSAGE NOW ARN ING 12-18BLINKER MESSAGE WINK 12-18BLINKER OVERLAY OPSIZE 12 -19BLINKER OVERLAY PAGEFRAME 12-20BLINKER OVERLAY TH RESHOLD 12-21BLINKER OVERLAY UM B 12-22BLINKER PROCEDUR E DEPTH 12-23DEFINE 1 2 - 2 4DEFLIB 1 2 - 2 5E C H O 1 2 - 2 5E N D A R E A 12-26EXTDICTIONARY 12-26FILE 12 -27LIBRARY 12-28M A P 1 2 - 2 9MIXCASE 12-29

M O D U L E 12-30M U R P H Y 1 2 - 3 2N O B E L L 12-32NODEFLIB 12 -33NOEXTDICTIONARY 12-33N O TA B L E O F C O N T E N T S 12-34O U T P U T 12-34R E A D O N LY 12-35S E A R C H 12-35

SECTION INTO 12-36STACK 12-37U P P E R C A S E 12-38VERBOSE 12-38WORKFILE 1 2 - 3 9

Blinker Func tion Reference 12 -40BLIVERNUM 1 2 ^ 0

Prog ram ming a n d Utilit ies Gu ide xvii



C ha pte r 13 : C A -C lipp er Debugger— CLD.LIBIn This Chap ter 13-1Star t ing the Deb ugger 13- 4

Prepar ing Your Program s for Debug ging 13-4Programm ing Cons idera t ions 13-4Com pi l ing Your Source Code 13-6

Invoking the Deb ugger 13- 7From DO S 13-7Linking the Deb ugge r 13- 9Cont ro l ling Execut ion of Ap pl ica t ion — /D or / d 13-9Permit t ing Concurrent Viewing of Applicat ion

and Debug Sc ree ns— /S o r / s 13 -10Set ting sc reen l ines — /4[3] 13-10Set ting sc reen l ines — /5[0] 13-10From W indow s 13-11Invoking wi th A l t+D 13-11Using ALT D() 13-12

How the Deb ugger Searches for Fi les 13- 13Us ing a Script File 13 -14Gett ing Help 13-1 6Leaving the Deb ugge r 13- 16

The Debugger Disp lay 13-17The Debugger M enus 13-17

The M enu Bar 13-17Me nu Opera t ions 13-19Menu Com mand s 13 -21

The Funct ion Keys 13- 22The Debugger W indow s 13-23

W indow Opera t ions 13-24The Code Wind ow 13 -29The Com mand Window 13 -31The Watch Windo w 13 -34The Mon i tor W indow 13-37The Cal l s tack W indow 13-39The Help W indow 13-41The View Sets W indow 13-42

xvii i CA-Clipper



The View W orkareas W indow 13 -43The Se t Colors W indow 13 -44

Dia log Boxes 13- 45Debugging a Program 13 -46

Execut ing Program Code 13 -47Mo des of Execut ion 13 -47Finding Program Errors 13 -50Viewing Program Outpu t 13 -52

Inspect ing Data and Expression s 13 -5 3Using Watchpo in ts and Tracepoin ts 13 -53Crea t ing New Var iab les 13 -56

Inspect ing Program Cod e 13 -57Using Breakpoin ts 13 -57Na vigat ing the Call Stack 13 -6 0Viewing Fi les 13 -61

Access ing DO S 13 -62Menu Com mand Refe rence 13 -6 3

? |?? 13-64BP 13 -66

Cal l s tack 13-68

Dele te 13-69Fi le DO S 13 -71File Exit 13 -7 1Fi le Open 13 -72Fi le Resume 13 -73He lp 13 -74List 13-76Locate Case 13 -77Locate Find 13 -7 8

Locate Goto 13 -79Locate Next 13 -80Locate Previous 13 -81Moni tor Al l 13 -82Mo ni tor Loca l 13 -83Mon i tor Pr iva te 13 -84Mon i tor Publ ic 13 -85

Pro gram m ing a n d Utilit ies G uid e xix



x j r c . 13 -86Monitor SortΛ / Γ c , 13-87Monitor Static

13 -88Opt ions Cod eblock

13-90Options Color

13-91Opt ions Exchange

j . 13 -9 2Options Line

13-93Opt ions Menu

r 13 -94Opt ions MonoD A 13 -95Options Path

13—96Options Preprocessed

13-97Options Restore

c 13 -98Options SaveOptions Swap

T U 13 -100Options Tab

13-101Point Breakpoint

13 -102Point Delete„ . A T · f 13 -103Point Tracepomt

13-104Point Watchpointο A · 1 3 ~ 1 0 5

Run Anim ateΌ n 13 -106Run Go„ K T . 13-1 07Run NextD Ό f . 13-1 08Run Restart0 c A 13 -109Run Speed

Ζ 13 -HORun Step

τ 13-111R n T 1 3 -1 1 2n Tr c 1 3 -1 1 2wΤ. 1 3 -1 1 4w Γ l . v 1 3 - 11 5w C llst ck. c 1 3 - 11 6w S ts 1 3 -1 1 7w W rk r sΓ A T · 1 3 -1 1 8n d w Ic n zA 7. 1 3 -1 1 9nd w M v 1 3 -1 1 9nd w N xtr ι τ · π 1 3 - 1 2 0nd w Pr v

xx CA-Clipper



Window Size .W indow Tile .

Window Zoom

13-12013-12113-122

Chap te r 14 : P rogram M ain tena nce -RM AK E.EX EIn This Ch apte r I4

Invoking RM AK E 14The RM AK E Envi ronment Var iab le 14

RM AKE Opt ions 14 -4How RM AKE Works 14 -6How RM AK E Searches for F i les 14 -8

M ake Fi les 14 -8Target and Dep enden cy Fi les 14 -8

The Mak e Fi le 14- 10Using Quota t ion Marks 14- 11Line Continu at ion 14 -11Comment s 14 -12Dependency Rules - 14 -12

Mak epath Exam ples 14- 13Inference Rules 14 -1 5Sett ing Environ men t Variables 14 -1 7Direct ives 14-19Macros 14-22

User-Def ined Macros 14- 23Predef ined Macros 14 -25

A Com ple te Mak e Fi le 14 -27

Ch apter 1 5 : ProgramE di tor-PE.EXEIn This Chap ter 15 -1Invoking the Program Editor 15 -2Naviga t ion and Edit ing 15 -3Leaving the Progra m Editor 15 -5The PE System Architecture 15 -5

Prog ram min g a n d Utilit ies G uid e xxi



Chapter 16 : Database Ut i l i ty -DBU.EXEIn This Chap ter 16- 1Invoking the Datab ase Uti l i ty 16 -2The Ma in DBU Screen 16-3

The Me nu Bar 16-3The M essage and Prom pt Area 16- 5Dialog Boxes 16 -5

Buttons 16-6Fill-in Fields 16 -7Scrolling Lists 16 -7Closing a Dialog Box 16 -8

Windows 16 -8Wo rk Areas 16-9Files 16-10Indexes 16-10Fields 16-11Nav igat ion on the M ain Screen 16- 12

Leaving DBU 16-13The DBU Men us 16-1 3

Fl Help 16-15

F2 Open 16-16Database 16-16Index 16-17View 16-17

F3 Create 16- 18Database 16-18Index 16-23

F4 Save 16- 24View 16-24

Struct 16-24F5 Brow se 16 -25

Database 16-25View 16-26

xxii CA-Clipper



F6 Uti l ity 16 -2 8Copy 16 -28Append 16-30Replace 16-30Pack 16-31Zap 16 -32Run 16-32

F 7 M o v e 1 6 - 3 3Seek 16-33Goto 16-34Locate 16-34

Skip 16-35F8 Set 16 -3 5Relat ion 16-36Fil ter 16-39Fields 16-40

The DBU Sys tem Archi tecture 16- 41

Chapter 17 : Report and Label Utility—RLEXEIn This Chap ter 17 -1Loading the Report and Label Uti l i ty 17 -2Creat ing and M odifying Repo rts 17 -2

Creat ing or M odifying a Repo rt 17 -2Def in ing Repor t Colum ns 17 -3Delet ing a Colu mn 17 -6Inser ting a New Colum n 17- 6Locat ing a Colum n 17- 6Defining Report Op tions 17 -7Def in ing Groups 17 -9Saving the Report Defini t ion 17 -1 1Print ing a Report 17 -1 1Report ing from Related W ork Areas 17 -1 2

Pro gra m m ing a n d Utilities G ui de xxiii



Creat ing and M odifyin g Labels 17 -13Creat ing or M odify ing a Label 17 -13The Label Editor Screen 17- 14

Defining the Label Dim ension s and Form att ing 17- 15Standard Label Form ats 17- 16Defining the Label Contents 17- 16

Blank Lines 17 -17Saving the Label Design 17- 18Print ing the Labels 17 -19

Leaving RL 17-19The RL System Architecture 17- 20

C h a p t e r 18 : O n lin e D o c u m e n t a t i o n - N G . E X EIn This Chap ter 18 -1Load ing the Instant Access Engine 18 -2

Using Mem ory-Res ident Mo de 18- 2Using Pass Throug h M ode 18- 3Accessing the Instant Access Engin e 18 -3

H ow the Instant Access Engine Searches for Fi les 18 -4Using the Access W indow 18-5

The M enu Bar 18-5Select ing M enu s and M enu I tems 18 -6Siz ing and Mo ving the Access W indow 18-6Gett ing Help 18 -7

Viewing a Docum enta t ion Database 18-8The Short Entry List 18 -9Searching a Short Entry List 18 -10Expanding an Ent ry— M oving Do wn a Level 18-10

See Also References 18 -11Mo ving Up a Level 18-1 2Selec t ing a New Docum enta t ion Database 18-13

Instant Access Engine Nav igat ion Keys 18- 14

xxiv CA-Clipper



Configuring the Instant Access Engine 18 -15Toggling Color 18 -1 6Toggl ing Auto Lookup 18- 16Chang ing the Hot Key 18 -17Saving the New Configu rat ion 18 -17

Leaving the Instant Access Engine 18 -18Exit ing the Instant Access Engine 18 -18Uninstal l ing the Instant Access Engine 18 -18

A p p en d ix A : CLIPPER.BML

Index

Prog ram ming a n d Utilit ies G uid e xxv





Chapter 1

Introduction

In This G u id e

This is the Programming and Utilities Guide for CA -Clipp er. I tcontains conceptual information on programming and creat ing

applicat ions using the CA-Clipper development system, as wellas usage information for each utili ty in the package.

Further information on many of the topics covered in this guidecan be found in the Reference Guide. In add ition, you will findmuch of the utili t ies portion of the Programming and UtilitiesGuide packaged in other forms to make access more convenient .

For onl ine information accessible while operat ing your programeditor or any other development utili ty, use The Guide toCA-Glipper Utilities da tabase ( see 'On l ine D ocum enta t ion—N G .E XE " chapter of this guide for docu men tat ion) . For a br iefsummary of the utili t ies, use the Quick Reference Guide.

N o t e : The Reference Guide, V olume 2 includes a glossary, w hichis a com prehen sive dict ionary of terms used throughou t theCA -Clipp er docum entat ion. Each glossary entry consis ts of theitem name, the identity of one or more categories to which theitem belongs, and a short definition.

Prog ram ming an d Utilit ies G uid e 1-1



Part 1: Basic Co nc ep ts

Part 1: Basic C o n c ep ts

This sect ion bui lds on the "Language Reference" chapter of theReference Guide by focusing on various aspects of theprogramming language and explaining how some of thelangua ge com pon ents f it together. Althou gh not as exhaust iveas the "La ng ua ge R eferen ce," this chapter gives you a d ifferentview of the langua ge, based o n systems and other logicalgroupings, that may help you bet ter understand how to useCA-Clipper to accomplish your programming tasks.

Part 2: Programming

This section is divided into several chapters, each of which givesyou specific details on a particular aspect of the CA-Clippersystem that ma y require further progra mm ing. I t containsconceptual information on programming and creat ingapplicat ions using the fol lowing subsystems: TBrowse, The GETSystem , and Error Hand ling, as well as chapters on "Th eRunt ime Envi ronment ," "Network Programming," and"Progra mm ing in Graphic M od e." Fur ther re ferenceinformation can also be found in the "Language Reference"

chapter of the Reference Guide.

1-2 CA-Clipper



Part 3: Utilities

Part 3: Utilities

This sect ion documents each ut i l i ty supplied with theCA -Clipp er pack age in a separate chapter. The com pletecommand l ine syntax as well as al l opt ions are completelyspecified for each utili ty. In addition, usage information,including navigation and selection, is provided for themenu-driven ut i l i t ies .

The following utili t ies are covered:

• C A - C l ip p e r C o m p i l e r - C L I P P E R . E X E

• CA-Cl ippe r L inke r—BLINK ER.EXE

• CA-Cl ippe r Debugge r— CLD .LIB

• P rog ram Main t enance— RM AKE.EXE

• Program Edi tor— PE.EXE

• Database Ut i l i ty—D BU. EXE

• Repor t and Label U t i l i t y -R L .E XE

• The Guide to CA-C l ipper— NG .EXE

The symbols and convent ions used to docum ent the com ma ndline syntax and options for these utili t ies are the same as thoseused in the Reference Guide. For insta nce, squ are brack ets ([ ])del imit opt ional i tems, angle brackets (< >) del imit user-suppliedi tems, and required keyw ords are shown in uppercase let ters. I fyou are unfam il iar with the conven tions, refer to theintroduct ion of the Reference Guide for further details.

Programming and Util i t ies Guide 1 - 3





Chapter 2

Basic Concepts

In This C h a p te r

The "La ngua ge Refere nce" chapter of the Reference Guideintroduced you to programming in CA-Clipper by defining al l of

the components (for example, commands, funct ions, andoperators) that go together to make up the programminglanguage. This chapter bui lds on the "Language Reference"material by focusing on various aspects of the programminglanguage and explaining how some of the language componentsf it together. Althou gh not as exhaust ive as the "L ang uag eRefe renc e," this chapter gives you a different view of thelangu age, based on sy stems and other logical groupings, thatmay help you bet ter understand how to use CA-Clipper toaccomplish your programming tasks.

This chapter provides an overview of the CA-Clipper languageconstru cts and its m ajor system s. The followin g topics arecovered:

• Structure of a CA -Clipp er Prog ram

• Funct ions and Proced ures

• Con trol Structures

• Variables

• Expressions

• Data Typ es

• Operators

• The Macro Opera tor

Prog ram m ing a n d Utilit ies G uid e 2-1



The Structure of α CA -Clippe r Progra m

• Arrays

• Co de Blocks

• Objects and M essage s

• Database , Input /O utp ut , Keybo ard , and Low-leve l F i leSys tems

The Structure of α CA-Clipper Program

A CA-Clipper program is a col lect ion of s tatements that adhereto the rules defined by the CA -Clipp er language. A pro gramstatement can take many different forms including:

• Co mm and invoca t ion

• Funct ion call ( for exam ple, l ibrary, pseu do, or user-defined)

• Proce dure cal l

• Prepro cessor direct ive

• Co ntrol s t ructure or declarat ion s tatement

• Ass ignm ent s ta tement

• Comment

A program is stored in a text file with a (.prg) exten sion. Ingenera l , wh ite space (for exam ple, blanks, tabs) is ignored by thecompiler, a l lowing you to format your programs for readabil i ty.However, the compiler interprets the carr iage return / l inefeedpair as the end of a statement (see the Continuation section forexceptions) .

2 -2 CA-Cl ipper



The Structure of α CA -Clippe r Prog ram

A Typical CA -Clipper Program

The fol lowing example program, ListBox.prg, is used throughoutthe discussion in this section to il lustrate the various componentsof a CA-Clipper program and to give you an idea of what atypical program looks l ike:

/* ListBox.prgDisplay a menu and process a menu choiceCompile with /Μ, /N, or /W

* /

// Manifest constant definitions#define S_ADD " Add"#define S_EDIT " Edit"#define S_REPORT " Report"

#define S_QUIT " Quit"// Filewide variable declarations go here

PROCEDURE Main()

// Local variable declarationsLOCAL cChoice

// Continuous loop redisplays ListBox after each// function returnDO WHILE .T.

// Function call to create ListBox with// default option of QuitcChoice := CreateListBox(S_QUIT)

// Case structure to make function call// based on return value of CreateListBox()DO CASE

// Functions called in the CASE structure are// defined in a separate .prg file, whic h you// must create, compile, and link with this// applicationCASE cChoice = S_ADD

AddRecs()CASE cChoice = S_EDIT

EditRecs()CASE cChoice = S_REP0RTReports()

OTHERWISEEXIT // Break out of continuous loop

ENDCASEENDDORETURN

Prog ram min g a n d Utilit ies G uid e 2-3



The Structure of α CA-C lipper Program

FUNCTION CreateListBox(cChoice)CLEAR@ 1, 31, 6, 45 GET cChoice LISTBOX {S_ADD, ;

S_EDIT, ;S_REPORT, ;

S_QUIT}SET MESSAGE TO 23 CENTERREADCLEARRETURN cChoice

The Main Procedure Definition

The m ain progra m fi le in any CA-Clipper ap plicat ion usual lyhas a main procedure (or function) definition located at the topof the progra m (.prg) file. In our example, the main proceduredefinition begins with the following statement:

PROCEDURE Main()

This s tatement m arks the beginning of the procedure and gives i ta nam e. After the application is com piled and link ed, it is thisprocedure that serves as a startup routine when the applicationis exec uted . In fact, if you r application is desig ned with a mainprocedure, you must compile with the /N option or, f rom theWorkbench, uncheck Create Default Procedure in the CompilerOptions dialog box to prevent the compiler from generating astartup procedure of its own.

Like other procedure and function definitions, the mainproced ure consists of s tatemen ts , com ma nds, and function cal lsthat perform a particular task. Typically, variable declarationsare placed at the top of the procedure.

2-4 CA-Clipper



The Structure of α CA -Clipp er Prog ram

Following the variable declarat ions is the main proced ure b ody ,wh ich usually consists of one or m ore function calls. De pen din gon the nature of the application, you can place the function calls

in a control structure as in ListBox.prg:DO WHILE .T.

cChoice := CreateListBox(S_QUIT)

DO CASECASE cChoice = S_ADD

AddRecs()CASE cChoice = S_EDIT

EditRecs()CASE cChoice = S_REP0RT

Reports()OTHERWISE

EXITENDCASEENDDO

Final ly, the end of the main proc edure can be mark ed w ith aRE TU RN statement . The RE TU RN statement is not a requiredpart of any procedure definition but is included for readability.If no RETURN statement is present , the next PROCEDURE orFUNCTION statement (or the end of file) is used to indicate theend of the previous definition.

Function an d Procedure Calls

Within a routine, calls to other routines are made using theroutine nam e. For funct ions, the nam e must be fol lowed by i tsargu m ents enclose d in par enth eses. A function call is anexpression w hose data type is determ ined by i ts return va lue.Therefore, a function call can be part of another expression.Function calls are the same regardless of how the function isdefined. For exam ple, cal ls to the s tandard CA -Clipper l ibrary

functions are identical to your own user-defined function calls.

The following line of code from ListBox.prg illustrates a functioncall as part of another statement:

cChoice := CreateListBox(S_QUIT)




The Structure of α CA -Clipp er Progra m

Proced ures, on the other hand , always return NIL. Thu s, a callto a proced ure is norm ally ma de as a separate p rogramstatement. A procedure can, how ever, accept parameters .Param eters are passed to a proced ure using the same syntax as a

function (for example, a parameter list enclosed in parentheses).

Thus, in ListBox.prg, AddRecs, EditRecs, and Reports could bedefined as functions or procedures without affecting the callingconvention.

Variable Declaration

In CA-Clipp er, dyna mic va riables can be created and ini tial ized

withou t formal declaration statemen ts . The default scope of anundeclared dynamic variable is private to the routine in whichthe variable is first initialized. In addition, CA-C lippe r is aweak-typed language, which means that the data type of avariable is never declared—only the scope, or visibility.

Lexical ly scoped variables must be declared. In ListBox.prg,there is one declaration statement that sets up a local variable toreceive the value of a menu choice:

LOCAL cChoice

This s tateme nt declares the variable cChoice as a local variable.Except in one case (that is, the PUBLIC statement), variabledeclara tions assign N IL to the variable as its initial value . Aninitial value can be assigned to a variable using the inlineassignment:

LOCAL cChoice := S_QUIT

W here y ou place a variable declarat ion in a progra m file helpsdetermine its scope. For instance, STATIC declarations, that aremade before the first procedure or function definition, have afilewide scope (that is, are visible to all routines in the file),whereas those made within a routine definition are local to thatroutine . See the Va riables section in this chap ter for moreinformation on variable declaration and scoping.

2-6 CA-Clipper




Function and Procedure Definitions

Function and procedure definitions are also part of a typical

pro gra m . In ListBox .prg, there is only one function definitionwhich is shown below:

FUNCTION CreateListBox(cChoice)CLEAR@ 1, 31, 6, 45 GET cChoice LISTBOX {S_ADD, ;

S_EDIT, ;S_REPORT, ;S_QUIT}

SET MESSAGE TO 2 3 CENTERREADCLEARRETURN cChoice

This definition is typical, consisting of the declared functionnam e with a param eter l is t in paren theses, fol lowed b y thefunction body, and ending with a return statement that passes avalue to the calling routine. All function definition s must re turna value in CA-Clipper.

The definition of a procedure is like that of a function except forthese differences: the keyword PROCEDURE precedes theprocedure name and parameters , and a return value isunnecessary since procedures automatical ly return NIL.

Norm ally, routines defined within a program file are only u sedby other routines in that file. More generic routines are usuallystored in a separate file, often called a procedure or function file,so they can be shared by m any prog ram s. For exam ple, inListBox.prg the funct ions AddRecsQ, EditRecs() , and ReportsQare cal led but not defined in the prog ram . Instead, you sho uldcreate these functions and place them in a separate program file,which y ou should then comp ile and link with ListBox.prg.

Pro gram min g a n d Utilit ies G uid e 2-7



The Structure of α CA -Clipp er Progra m

Preprocessor Directives

In addition to statements, preprocessor directives can be part of aCA -Clipper pro gram . These direct ives are instructions to the

com piler rather than statemen ts that are com piled. Preprocessordirect ives alway s begin w ith a hash sy mb ol (#) .

In ListBox.prg, there are several manifest constant definitions atthe beginning of the file. These directives assign constant valuesto identifier names that can be used in statements throughout theprogram. Whenever the compiler encounters the identif iername, it substitutes the associated value:

#define S_ADD " Add"#define S_EDIT " Edit"#define S_REP0RT " Report"#define S_QUIT » Quit"

Comments

You can formulate program comments in several ways,depen ding on the effect that you want . For long comm ents thatspan several lines, use the /*.. .*/ to delimit the comment block.All text following the slash-asterisk (/*), including carriagereturns, is ignored by the compiler until an asterisk-slash (V) is

encou ntered to indicate the end of the com men t block. Thefollowing example illustrates:

/* ListBox.prgDisplay a menu and process a menu choice

*/

For single-line comm ents, use the double-slash ( / / ) to introducethe com m ent. All text fol lowing this comm ent sym bol until thenext carr iage return/ l inefeed is t reated as a comment to beignor ed by the com piler. In our exa m ple, there are severalcom me nts form ulated in this way throug hout the code, one ofwhich fol lows:

// Continuous loop redisplays ListBox after each// function return

You can also use the asterisk (*) symbol for single-line comments,as in dBASE programs.

2-8 CA-Clipper




Co m m ents need not be in a block or on a line by them selves.The do uble-slash can also be used to place a com m ent at the endof another statement line as in the following example:

EXIT // Break out of continu ous loop

You can also use the double-ampersand (&&) for inl inecomments. With both inl ine comment symbols, the compilerignores all text that follows the symbol until the next carriagereturn / l inefeed.

Continuation

Since the CA-Clipper compiler interprets the carr iagereturn/ l inefeed pair as marking the end of a program statement ,i t migh t appe ar that each statement mu st be on a s ingle line an d,furtherm ore, that no m ore than one statem ent can be on a l ine.Ho we ver, you can u se the semicolon ( ;) character to specifymult i l ine s tatements and mult is tatement l ines.

To continue a statement on more than one line (that is, form amultiline statement), place a semicolon at the end of the first l inebefore the carr iage return / l ine feed , and put the remaind er of the

statemen t on a new l ine. W hen the comp iler encoun ters asemicolon fol lowed by a carr iage return/ l inefeed, i t continuesreading the s tatemen t on the next l ine. The fol lowing @.. .GETLISTBOX command uses semicolons to put each l is t box i tem ona new line:

@ 1, 31, 6, 45 GET cChoice LISTBOX {S_ADD, ;S_EDIT, ;S_REPORT, ;S_QUIT}

You can repeat this me thod of line continuat ion several t imes to

break a single statement into several lines. Using this feature,you can format very long expressions to make them morereadable.

Prog ram ming a n d Utilit ies G uid e 2-9



Functions and Procedures

To form a mult is tatement l ine, s imply place a semicolon, w ithouta carr iage retu rn/ l in efee d, betw een the s tatements . W hen thecompiler encounters such a semicolon, it knows to read the nextstatem ent from the same line. For exam ple, the case structure inListBox.prg could have been coded as fol lows:DO CASECASE cChoice = S_ADD; AddRecs()CASE cChoice = S_EDIT ; EditRecs()CASE cChoice = S_REPORT ; Reports()OTHERWISE ; EXITENDCASE

Reserved Words

In CA-Clipper there are several words that are reserved forinterna l use by C A-C lippe r itself. Thes e are listed in the"Reserved Word" appendix of the Error Messages and AppendicesGuide. Reserv ed word s cannot be used as identif ier nam es inpro gra m statem ents. In add ition to these reserved word s, it isillegal for an identifier to start with an underscore.

Functions a n d Procedu res

Functions and proced ures are the basic building blocks ofCA -Clipper program s. Every program is mad e of one or moreproced ures an d /o r funct ions. These building blocks consist of agrou p of statem ents that per form a single task or action. The yare similar to functions in C, Pascal, or other programminglanguages.

The visibility of function and procedure names falls into twoclasses. Func tions and procedures visible anyw here in a

program are referred to as public and are declared withFU NC TION or PRO CE DU RE s ta tements . Funct ions andprocedures that are visible only within the current program(.prg) file are referred to as static and are declared with STATICFU NC TION or STATIC PRO CE DU RE s tatements . S tat icfunctions and procedures are said to have filewide scope.

2-10 CA-Clipper




Static functions and procedures are quite useful for a number ofreaso ns. First, they limit visibility of a function or p roc edu re,thereb y restricting access to the functio n or pro ced ure . Bec aus eof this , subsystem s defined w ithin a s ingle program (.prg) filecan provide an access protocol with a series of public functionsor procedure s, and conceal the implemen tat ion detai ls of thesubsystem within s tat ic funct ions and procedures.

Second, since the static function or procedure references areresolved at compile t ime, they preem pt public funct ions an dprocedures which are resolved at link time. This assures thatwithin a program file, a reference to a function or procedurealways executes the static routine if there is a public routine of

the same name.

Defining Functions and Procedures

Func tion and proc edure defini t ions are quite s imilar withslightly different requirements for return values.

Functions Func tions can be defined anyw here in a prog ram (.prg) file, butdefinition s cann ot be nes ted . A func tion definition has the

fol lowing basic form :[STATIC] FUNCTION <identifier>[{<parameter list>)]

[<variable declarations>]

. <executable statements>

RETURN <exp>

A function definition consists of a function declaration statementwith an option al list of dec lared param eters . Follow ing thefunction declaration are a series of optional variable declarations ta tements such as LO CA L, STA TIC, FIELD , or M EM VA R. Asme ntione d before, a funct ion m ust return a value, therefore aRETURN statement with a return value must be specif iedsom ew here in the bod y of the funct ion. A function d efini tionbegins with the FUNCTION declarat ion statement and ends withthe next FUN CTIO N or PR OC ED UR E s ta tement or end of f ile .

Prog ram ming a n d Utilities Gu ide 2-11




If the funct ion declarat ion begin s with the STATIC keyw ord, thefunction is visible only to procedures and functions declaredwithin the same program (.prg) file.

The following is a typical example of a function definition:FUNCTION AmPm(cTime)

IF VAL(cTime) < 12cTime += " am"

ELSEIF VAL(cTime) = 12cTime += " pm"

ELSEcTime := STR(VAL(cTime) - 12, 2) + ;

SUBSTR(cTime, 3) + " pm"END IFRETURN cTime

Procedures Proc edu res are identical to function s with the excep tion that noreturn value is required an d, therefore, no RE TU RN statement isrequired. Like functions, proced ures can be defined anyw here ina program (.prg) file, but definition s cannot be neste d. Thefollowing is the general form of a procedure definition:

[STATIC] PROCEDURE <identifier>[{<parameter list>)][<variable declarations>]

. <executable statements>

[RETURN]

A procedure defini t ion begins with a PROCEDURE declarat ions ta tement and ends wi th the next FUNCTION or PROCEDUREstatement, or end of file.

If the procedure declarat ion begins with the STATIC keyword,the procedure is visible only to procedures and functionsdeclared within the same program (.prg) file.

2-12 CA-Clipper




Calling Functions and Procedures

Although funct ions and procedures are qui te s imilar they can becal led in different w ays.

Functions All funct ions are cal led in the sam e w ay, regardless of wh etherthey are defined in your application or in a library that you arelinking . Yo u can specify fun ctions either in exp ression s or asstatements .

For example, the following are all legitimate function calls:

// Expression? "This is the " + Ordina l(DATE ()) + "day"Report( ) // Statementresult := Repor t("Qua rterly ") // Expressio n

W hen a funct ion is cal led, i t mu st alway s be specified includingthe open and close parentheses. I f argu men ts are to be passed tocal led funct ions, they are specif ied betw een the parentheses andsepara ted by comm as . For example :

? Maj orFunc("One", "Two", "Three")

Procedures A proce dure can be cal led using funct ion-cal l ing syntax byspecifying the procedu re cal l as a s tatement . Here , you cal l theprocedure as you would a funct ion, specif ied as a s tatement:

<procedure>([<argument list>])

The second way i s us ing the DO . . .W ITH co mm and. This m ethodis not recommended since i t passes arguments by reference as adefault.

Unlike a funct ion, however, a procedure cannot be cal led as partof an expression. This is becau se procedu res cannot returnvalues as funct ions can and, therefore, cannot be evaluatedwithin the context of an ex pression.





Passing Param eters

When you invoke a procedure or funct ion, you can pass valuesand referen ces to it . This facility allows you to create black b oxroutines that can operate on data without any direct knowledgeof the calling routine. The following discussion defines thevarious aspects of passing parameters in CA-Clipper.

Argument s and Pass ing data from a calling routin e to an invo ked routineParameters invo lves two pers pec tives, one for the calling side and one for

the receivin g side. O n the calling side, the valu es andreferences passed are referred to as arguments or actualparameters .

For example, the fol lowing funct ion cal l passes two arguments ,a constant an d a variable:

LOCAL nLineLength := 8 0? Center("This is a string", nLineLength)

On the receiving side, the specified variables are referred to asparameters or forma l param eters . For exam ple, here the variablesare specified to receive the string to center as well as the linelength:

FUNCTION Center(cString, nLen)RETURN PADC(cString, nL en, " ")

The specified receiving variables are place holders for values andreferences obtained from the cal l ing rout ine. When a procedureor function is called, the values and references specified asargum ents of the rout ine 's invo cat ion are assigned to thecorresponding receiving parameter in the invoked rout ine.

In CA-Clipper, there are two ways to specify parameters ,dep endin g on the s torage class of the param eter you w ant to use.Param eters specif ied as a part of the procedure or funct iondeclarat ion are declared parameters and are the sam e as localvaria bles. Th ey are visible only w ithin the called routine an dhave the same lifetime as the routine. Parameters specified asarguments of the PARAMETERS statement are created as pr ivatevariables and hide any private or public variables or arrays ofthe same name inheri ted from higher- level procedures andfunct ions.

2-14 CA-Clipper




N o t e : In CA -Clip per, you cannot mix declared param eters anda PAR AM ETE RS s ta tement wi th in the same procedure orfunctio n definition . Attem pting this gene rates a fatal com pilererror.

In CA -Clip per, param eters are received in the order passed andthe number of arguments does not have to match the number ofparam eters specif ied. Arg um ents can be skipped within the l is tof arguments or left off the end when a routine is invoked.Received parameters without corresponding arguments areini t ia l ized to NIL . For exam ple, the fol lowing funct ion cal l skipsthree arguments (two from within the list and one left off theend) , thereby ini t ia l iz ing them to NIL valu es:

? TestProc("Hello",, ,"There")

FUNCTION TestProc(parml, parm2, parm3, parm4, parmS)? parml, parm2, parm3, parm4, parm5// Result: Hello NIL NIL There NILRETURN NIL

When a rout ine is cal led, the PCOUNT() funct ion is updatedwith the position of the last argument specified within the list ofarguments . This includes skipped arguments , but not argumentsleft off the end of the list . In the exa m ple ab ove , PCO UN TQreturns 4.





Passing by V alu e

Passing an argument by value means the argument is evaluatedand its valu e is cop ied to the receiving param eter. Cha nges to areceived parameter are local to the called routine and lost whenthe rout ine termina tes . In CA-Clip per, a l l variables , expressions,and array elements are passed by value as a default if thefunction-calling syntax is used. This includes variablescontaining references to arrays, objects , and co de blocks.

As an exa mp le, the fol lowin g cod e passes a database f ield and alocal variable to a proc edure b y valu e:

LOCAL nNumber := 10USE Customer NEWSaylt(Customer->Name, nNumber)? nNumber // Resul t: 10RETURN

PROCEDURE Saylt(fieldValue, nValue)? fieldValue, ++nValue // Result: Smith 11RETURN

The im portanc e of pass-by-valu e is that the cal led rout ine cann otchange the caller 's data by changing the value of the receivedparam eter. This increases mo dulari ty by relegat ing theresponsibility to the calling routine to determine whether it

allows its data to be changed by a called routine.

2-16 CA-Clipper




Passing by Reference

Passing an argu men t by reference mean s that a reference to thevalue of the argument is passed instead of a copy of the value.The receiving parameter then refers to the same location inm em ory as the argum ent . I f the cal led rout ine changes the valueof the receiving param eter, it a lso changes the argumen t passedfrom the calling routine.

Variables other than field variables and array elements can bepassed by reference i f prefaced by the pass-by-reference operato r(@) and the function or procedure is called using the function-cal l ing syntax. For example:

LOCAL nNumber := 10USE Customer NEWSaylt(Customer->Name, @nNumber)? nNumber // Resul t: 11RETURN

PROCEDURE Saylt(fieldValue, nValue)? fieldValue , ++nValue // Resu lt: Smith 11RETURN

In this exam ple, the change to the nVahte parameter in the cal ledroutine is reflected in the nNumber argument after Saylt() is

called.

As you can see, passing a rgum ents by reference can be qui tedangerous i f parameters are inadvertent ly assigned new valuesin the called routine . Beca use of this, pas sing by refere nceshould only be used in special cases such as returning a modifiedvalue from a proced ure or funct ion. A good exam ple of this isthe FREAD() funct ion which takes a buffer variable passed byreference, f il ls the variable with characters read fro m a b inaryfile, and returns the num ber o f bytes read.

No te that argum ents passed to rout ines cal led with theDO .. .WITH statement are passed by reference as a defaul t . No tealso that other dialects commonly pass arguments by referenceas a defaul t . In CA -Clipp er, this pract ice is st rongly discou ragedand therefore use of the DO statem ent is not recom me nde d. AllDO invocat ions should be replaced with funct ion-cal l ing syntax,and variables passed by reference should be prefaced with thepass-by-reference operator (@).





Passing Arrays an d Ob jects as Argum ents

W hen u sing funct ion-cal l ing syn tax, variables containingreferences to arrays and objects are passed by value as arevariables containing values of any other data type. This m ayseem confusing since it reveals that passing references involves alevel of indirectio n. But whe n a variab le contain ing a referenceis passed to a routine, a copy of the reference is passed instead ofthe actual reference.

If, as an example, an array is passed to a routine by value andthe called routine changes the value of one of the array elements,the change is reflected in the array after the return, since thechange was made to the actual array via the copied reference to

it . If , ho w eve r, a referen ce to a ne w arra y is assign ed to avariable passed by valu e, the new reference is discarded upo nreturn to the caller, and the array reference contained in theoriginal variable is unaffected.

Conversely, if the variable containing a reference to an array orobject is passed by reference by precedin g the argum ent variablewith the pass-by-reference operator (@), any changes to thereference are reflected in the calling routine upon return.

For example:

// Change the value of an array elementa := {1, 2, 3}ChangeElement(a)? a[l] // Resul t: 10

// Change an array; does not worka := {1, 2, 3}ChangeArray(a)? a[l] // Result : 1

// Change an array by passing by referenceChangeArray(@a)? a[l] // Result: 4

FUNCTION ChangeElement(aArray)aArray[l] := 10RETURN NIL

FUNCTION ChangeArray(aArray)aArr ay := {4, 5, 6}RETURN NIL

2-18 CA-Clipper



Functions an d Procedures

Argument Checking

In CA-Clipper, there is no argument checking, and therefore thenumber of parameters does not have to match the number ofargum ents passed . Arg um ents can be skipped or lef t off the endof the argument list . A parameter not receiving a value orrefere nce is initialized to N IL. If arg um ents are specified ,PCOUNTQ returns the posi t ion of the last argument passed.

Since arguments can be skipped, PCOUNT() is not a lways anaccurate gauge of wh at argum ents have been specif ied. Toascertain this information, com pare the param eter in quest ion toNIL . If i t is equ al, you can either supp ly a defa ult value or

generate an argument error. The fol lowing exampledemonstrates this concept :

FUNCTION TestParms(parml, parm2, parm3)IF parm2 = NIL

? "Parameter was not passed"parm2 := "default value"

END IF

. <statements>

RETURN NIL

In addition to the NIL test, VALTYPEQ can be used to test for aparam eter receiving a value as wel l as the proper d ata type:

FUNCTION TestParms(cParml, nParm2)IF VALT YPE (nParm2 ) = 11 N"

? "Parameter was not passed or invalid type"END IF

. <statements>

RETURN NIL

N o t e : Rem em ber to use VA LT YP E() instead of TYP E() to testthe data type of declared param eters . A TYP E() appl ied to adec la red parameter a lways re turns "U."

Pro gram min g a n d Uti li ties G uid e 2-19




Passing Argum ents from the DOS Co m m a n d Line

Arguments can be passed direct ly from the DOS command l ineto a pro gram 's main procedu re. Param eters are specif ied ei ther

in a PARAMETERS statement or declared as a par t on the mainproce dur e 's declarat ion. Re m em ber, if you declare the ma inprocedure, you must compile with the /N opt ion or, f rom theWorkbench, uncheck Create Defaul t Procedure in the CompilerOptions dialog box.

Arg um ents pass ed are al l received as character s tr ings. Specifymult iple arguments by separat ing each argument with a space.If an argument contains an embedded space, i t must be enclosedin quo tation m arks in ord er to be passe d as one string. For

example, the fol lowing DOS command l ine passes twoarguments when invoking PROG.EXE:

PROG "CA-CLIPPER COMPILER" 5

The main procedure receiving parameters f rom the DOScommand l ine should test the number of passed parameters withPCOUNT() to assure that cr i t ical parameters have been specif ied.

Returning Values from Functions

As de fined, a funct ion m ust return a value. To do this , i t mu stconta in a RE TU RN s ta tement wi th an a rgument . A R ETU RNstatemen t perform s tw o act ions: f i rs t , i t terminates processing ofthe current routine by transferring control to the calling routine;and second, if the current routine is a function, i t returns anyvalue specif ied as the argument of the RETURN statement to thecalling routine . Th e return value can be a cons tant or anexpression. For exam ple:

RETURN ("Today is " + DTOC(DATE()))

In CA-C lipper, a funct ion can return a value of any data typeincluding arrays , objects , code blocks, and NIL. For example, thefollowing function returns an array to a calling routine:

FUNCTION NumArrayNew()LOCAL aNumArray : = AFILL(ARRA Y(10), 1, 1)RETURN aNumArray

2-20 CA-Clipper




RETURN statements can occur anywhere in a funct iondefini t ion, a llowing processing to be terminated befo re thefunct ion defini t ion ends. For exam ple, the fol lowing codefragment terminates processing if a condition is true (.T.) andcon tinue s if the cond ition is false (.F.):

FUNCTION OpenFile(cDbf)USE (cDbf)IF NETERR()

RETURN .F.ELSE

. <statements>

RETURN .T.

Note that RETURN is limited by the fact that i t can return onlyone value. M ore than one value can be returned if argu men tsare passed by reference, although this is not a preferred solution.An aggregate data structure can be defined as an arraycontaining o ther arrays, and arrays, as men tioned above, can bepassed throughout a program as a s ingle value.

If the function's return value is not used, i t is discarded, as is thecase when you specify a function as a statement.

Recursion

A procedure or function is recursive if i t contains an invocationof itself. This can be either direct or indirect wh en a fun ctioncalls another function that again calls the original function.

For exam ple, the fol lowing exam ple is a funct ion that usesrecur sion to calcu late the factorial of a specified num ber. Afactorial is the product of all positive integers from one to aspecif ied number:

FUNCTION Factorial(nFactorial)IF nFactorial = 0

RETURN 1ELSE

RETURN nFactorial * Factorial(nFactorial - 1)END IF

Th e factorial of 3 is, therefo re, 1 * 2 * 3 w hich is 6.

Prog ram m ing a nd Utilit ies G uid e 2-21



Control Structures

C on trol S tructures

CA-Clipper supports several control structures that let you

change the sequential f low of progra m execution. Thesestructures allow you to execute code based on logical conditionsand to repeatedly execute code an y num ber of t imes.

In CA-Clipper, all control structures can be nested inside of allother control structures as long as they are nested properly.Control s t ructures have a beginning and ending statement , and anested s tructure must fal l betw een the beginning and endingstatem ents of the structure in whic h it is nested . This sectionsummarizes all of the control structures in the CA-Clipperlangu age, giving examples and suggested uses for each.

Tip: There are also control structures to determine whichstatem ents in a pro gram to com pile. Thes e are thepreprocessor directives #ifdef. . .#endif and #ifndef.. .#endif.Refer to the Reference Guide for more information on these.

Looping Structures

Looping structures are designed for executing a section of codemo re than once. For exam ple, you m ay want to print a reportfour times. Of course, you could s imply code four RE PO RTFORM commands in sequence, but this would be messy andwo uld not solve the problem if the num ber of reports w asvariable.

2-22 CA-Clipper



Co ntrol Structures

FOR...NEXT

The FOR.. .NEXT control s t ructure, or FOR loop, repeats a sect ionof code a particular number of times. To solve the printingproblem, you could do this :

FOR i := 1 TO 4REPORT FORM Accounts TO PRINTER

NEXT

FO R...N EX T is typical of all CA -Clip per control structures . Itconsists of a statement that defines the conditions of the structureand marks i ts beginning, fol lowed by one or more executablestatements that represent the body of the structure and, finally, astatement to end the structure.

FO R.. .NEX T sets up a loop by ini t ia l iz ing a coun ter variable to anumeric value. The counter is incremented (or decremented)each time through the loop after the body statements areper form ed until it reach es a specified valu e. By default, as in thepreviou s exam ple, the increme nt value is one, but the inc reme ntcan also be specif ied with the FOR statem ent 's STEP clause.Furthermore, a l l of the FOR parameters can be numericexpressions al low ing for a variable num ber of loop i terat ions.FOR.. .NEXT is commonly used to process arrays on an element

by element basis .

DO WHILE.. .ENDDO

Another type of loop is one that is based on a condition ratherthan on a part icular num ber of repet i t ions. For exam ple,suppose you wanted to perform a complex process using recordsin a database f i le with a part icular custom er n um ber.

W ithout a condit ional loopin g structure, i t wo uld be v erydifficult , if not impossible, to solve this problem.

Prog ram min g a nd Utilit ies G uid e 2-23



Control Structures

The DO WHILE.. .ENDDO control s t ructure (also cal led a DOWHILE loop) processes a section of code as long as a specifiedcon dition is true (.T.). To solve the datab ase prob lem , you co ulddo the fol lowing :

USE Accounts INDEX AccountsSEEK 3456DO WHILE Accounts->AcctNum = 3456

. <processing statements>

SKIPENDDO

This exam ple i l lustrates a typical use of DO W HIL E to processdata base file recor ds. N ote that SKIP is used as part of the loopbod y to advance the pointer to the next record. In a DO W HIL Eloop , the loop body must contain some statement that alters theloop condition; otherwise, the loop will execute forever.

EXIT a n d LOOP

EXIT and L OO P are special s tatements that can only be usedinside a DO W H ILE or FOR loo p. EXIT transfers control out ofthe loop, and LOOP transfers control to the beginning of theloop . Th ese stateme nts are used as part of a cond itional co ntrol

s tructure to control looping behav ior und er u nusualcircumstances.

DO WHILE .T.IF EOF()

EXITELSEIF DELETED()

SKIPLOOP

ELSE<processing statements>

END IFENDDO

2-24 CA-Clipper



Control Structures

Decision-Making Structures

Decision-making structures al low you to execute one or moreprog ram statements based on a condit ion. For exam ple, youmay want to execute a different funct ion based on a menuchoice. CA-Clipper has two such structures, IF. . .ENDIF and DOCASE.. .ENDCASE, but they are ident ical in funct ional i ty.

IF...ENDIF

The IF.. .ENDIF control structure executes a section of code if aspecified condition is true (.T.). The structure can also specify

alternative code to execute if the condition is false (.F.).

The fol low ing exam ple i l lustrates IF. . .EN DIF in a funct ion thattests for an empty array:

FUNCTION ZeroArray(aEntity)IF VALTYP E(aEnt ity) = "A" .AND. EMPTY( aEntity)

RETURN .T.END IFRETURN .F.

The next example uses IF. . .ENDIF to process a menu choice:

IF nChoice = 1F u n d ()ELSEIF nChoice = 2

Func2()ELSEIF nChoice = 3

Func3()ELSE

QUITEND IF

ELSEIF specifies an alternative condition to test if the previouscondit ion w as not met , a l lowing m ult iple levels of control . I treplaces nested IF. . .END IF structures. ELS E is an al ternat ivepath to execute if none of the other conditions in the structure ismet .




Control Structures

DO CASE.. .ENDCASE

D O C AS E an d IF are equivalent s t ructures with s l ight ly differentsyntax representat ions. For exam ple, the fol lowing DO C ASE

code segm ent is funct ional ly equ ivalent to the previous IFexample :

DO CASECASE nChoice = 1

F u n d ( )CASE nChoice = 2

Func2()CASE nChoice = 3

Func3()OTHERWISE

QUITENDCASE

Neither decision-making structure has advantages over theother. W hich o ne you use is purely a matter of personalpreference.

Error Handling Structures

BEGIN SEQUENCE.. .END is a special ized control s t ructure oftenused for runtime error and exception handling, as il lustratedbelow:.

DO WHILE .T.BEGIN SEQUENCE

. <operation that may fail>

RECOVERIF PrintRecover()

LOOP // Repeat SEQUENCE blockEND IF

ENDEXIT // Escape from the operation

ENDDO

2-26 CA-Clipper



Variables

Variab les

Variables are place holders for values and references that have adefined l i fet ime and visibi l i ty, and a given nam e. W hen avariable name is referenced, the value it contains is returned.

In CA-Clipp er, variables are organized into storage classes thatdetermine how the variable is stored, how long it l ives, andwh ere in a prog ram i ts nam e can be used. Each storage class hasa statement that either declares the variable names or creates thevariable at runtime .

Lexically Sco ped Versus Dynam ically Sco pe d Variables

Public, private, and field variables have what is referred to asdynamic scope. Dyn amical ly scoped variables, including nam es,are created and maintained com pletely at runtime . Noth ing isresolved at compile time, and there is automatic inheritance ofvariables by cal led procedure s and functions. These classes ofvariables are characteristic of interpreted systems and exist inCA -Clipper in order to be code com patible with interpreteddialects.

In CA-Clipper, two classes of variables have what is called lexicalscope. Th ese classes of variab les are resolve d com pletely atcom pile t ime and have r igidly defined scoping rules, asdescribed below.

• Dy nam ically scop ed variables violate the principle ofmod ulari ty s ince to und erstand the operat ion of a routine,you must understand the operation of all the routines thatcall i t . Each routine is a modularly constructed program thatshould be understood in the context of its own definition,and the program (.prg) file in which it is located.




Variables

• Lexica lly scop ed variables are mo re efficient and m uch fasterthan dy nam ical ly scoped variables s ince they are resolvedcompletely at compile t ime. Dynamical ly scoped variables,by con trast , mu st be resolved each t ime they are referencedin a program.

W e highly recom me nd the use of lexical ly scoped variables andtheir substitution for all uses of dynamically scoped variables.

Lifetime an d Visibility of V ariable s

During execution, a variable, even though declared at compiletime or referred to in an executable statement, does not actually

exist until some portion of the computer 's internal memory isallocated to contain its valu e. This is kn ow n as creating (orinstantiating) the variab le. S om e variab les are createdautomatically, while others must be explicitly created.

Lifetime On ce creat ed, a variab le con tinues to exist (and posses ses avalue, if one has been assigned) until i ts memory is released.Som e variables are released autom atical ly, while others must beexplicitly release d. Som e variab les are nev er released . Theduratio n of a variab le's life is referred to as its lifetime.

Visibility Visibility refers to the conditions un der wh ich a variable isaccessible to the prog ram d uring execution. Som e variables,even though they have been created and assigned a value, maynot be visible under certain conditions.

During execution, a s ingle variable nam e can be associatedsimultaneously with several different variables, some or all ofwh ich ma y be visible. Declarat ions can be used to ensure thatoccurrences of a particular name in the source code refer to thedesired v ariable.

The visibility and lifetime of each variable class are describedlater in this chapter under the sections entitled Local Variables,Static Variables, Private Variables, and Public Variables.

2-28 CA-Clipper



Variables

Declaring Variables

Variable declarat ions are not executable s tatements . Instead,

they declare, at comp ile t ime, the nam es of prog ram variables an dinform the compiler of assumptions that can be made aboutthem.

Although the declarat ions are not themselves executable, theassum ptions they prod uce affect the object code generated by thecompiler for references to the variables declared.

You can declare variables by naming them in STATIC, LOCAL,MEMVAR, and FIELD declarat ion statements . They can also be

declared by naming them as declared parameters (that is, l istingthem in parentheses) in PROCEDURE or FUNCTIONstatements, or in code block definitions.

Declarations are optional for some kinds of variables (private,public and field variables) and mandatory for others (static andlocal variables, and declared param eters) .

Compile with the /W option or, f rom the Workbench, checkEnable Warnings in the Compiler Options dialog box to enablecompile- t ime checking for undeclared variables.

All declarat ion statements m ust occur before e xecutablestatements .

Prog ram min g a n d Utilities G uid e 2-29



Variables

The Sco pe of a Declaration

A declarat ion 's scope determines the parts of the program towhich the declaration applies. Declaration scope is determined

lexically. Tha t is, declara tions ap ply only to the compilation ofcertain sections of source code . (Note that the scope of adeclaration is not necessarily the same as either the visibility orthe lifetime of the variable it declares.)

For the purpose of determining declaration scope, source code isviewed as a series of discrete lexical units: files, proc edu res an dcode blocks.

• A file is all of the source cod e w ithin a sing le disk file

submit ted for compilat ion.

N o t e : Cod e included via the #include preprocessor d irectiveis considered part of the file containing the #includedirective.

• A proced ure is al l source code from a PR OC ED UR E orFUNCTION s ta tement unt i l the next PROCEDURE orFUNCTION statement, or until the end of the file.

• A cod e bloc k is all sourc e cod e within the block d elimitersthat define the code block.

Som e units can be nested inside of others; proced ures occurwithin f i les , for example, and cod e blocks occur withinprocedures or other code blocks.

A declaration's scope is the lexical unit in which it occurs andany nested un its. For exam ple, a declaration that occurs within aproced ure d efini tion applies to that procedu re and any blockswithin it . A declaration that occurs within a code block (a blockparam eter) , applies to that code block and any cod e blocksnested within it .

2-30 CA-Clipper



Variables

STA TIC, FIELD, and M EM VA R declara t ions can also appearoutside of any proced ure or code block by specifying thembefore any PROCEDURE or FUNCTION s ta tements in the

sourc e file. In this case , the declaration applies to the entiresource file. Variables declared this way are said to have filewidescop e. No te that to dec lare variab les with filewide scope , youmust compile with the /N option or, f rom the Workbench,uncheck Create Default Procedure in the Compiler Optionsdialog box.

A declaration in an inner unit can declare a variable with thesam e nam e as one dec lared in an outer unit. In this case, theinner declarat ion supersed es the outer, but only within the innerunit. For instanc e, a declara tion w hich app lies to an entire filecan be superseded b y a declarat ion in one of the p rocedu reswithin that file. The superseding declaration affects only theprocedure in which i t occurred.

Referring to Variables

In the prog ram source cod e, variables are referred to by nam e.When the compiler sees an occurrence of a particular name, itgenerates object code to assign or retrieve the value of thevariable with that name.




Variables

Ambiguous Variable References

During execution, i t is possible for a single name to be associatedsimu ltaneou sly w ith several different variables , some or all of

wh ich m ay be vis ible . In the absence of a declarat ion or anexplicit qualifying alias, i t can be impossible for the compiler totell which variable a part icular nam e wil l actual ly refer to w henthe pro gram is execu ted. The occurrence o f such a nam e isknown as an ambiguous variable reference.

When the compiler encounters an ambiguous variable reference,it generates special object code (lookup code) which , whenexecuted, checks to see if a variable exists with the specifiedna m e. If the na m e exists, i t chec ks wh at kind of variab le it is and

w heth er it is visible. Th e order in w hich the vario us p ossibilit iesare checked depends on how the variable was referred to.

Av o i d i n g A m b i g u o u s Va r i a b l e R e f e r e n c e s

Avoiding ambiguous variable references at compile t ime al lowsthe compiler to generate more efficient object code. It alsoincreases the dependabil i ty of the program, s ince ambiguousreferences behave different ly at runt ime depending on a varietyof circumstances.

Declara t ions can be used to ensu re that occurrences of aparticular name in the source code refer to the desired variable.Alternat ively, references to variables can be explici t ly qualified bypreceding them with the al ias operator.

To generate warnings of ambiguous variable references, compilewith the /W option or, f rom the Workbench, check EnableWarnings in the Compiler Options dialog box.

2-32 CA-Clipper



Variables

Qua l i fy ing Va r i ab le Refe renc es

The alias operator (->) can be used to explicitly qualify a variable

reference. The fol lowing combinat ions are legal :<alias>-xname>

Refers to a field in the work area designated by <alias>. Aruntime error occurs i f <name> is not a field in the desig nate dwork area.

FIELD- ><name>

Refer s to a field in the curre ntly selected wo rk area. A ru ntim eerror occurs if <name> is no t a field in the curren tly selec tedwork area.MEMVAR - ><name>

Refers to ei ther a PR IVA TE v ariable ( i f one exists) or a P UB LICvaria ble. Th e referen ce can be an attem pt to assign a val ue, inw hich case a PRIV AT E variable is created at the currentactivatio n level. O the rw ise, if the referen ce attemp ts to retrieve avariable that does not exist, a runtime error occurs.

Creation and Initialization

Yo u can create variables and supply ini t ia l values in the sa mestatement . The fol lowing statemen ts allow ini t ia l izers:

• STATIC

• L O C A L

• PRIVATE

• PUBLIC

N o t e : The FIELD and M EM VA R s ta tements do not a llowinitializers since they do not specify the creation of variables.

If you specify no initializer, a variable is given an initial value ofNIL , except for public variables , which are given an init ia l valu eof false (.F.).




Variables

Initializers for static variables must be compile-time constantexpre ssion s. Tha t is, the expres sions mu st consist entirely ofconstants and simple operators (no variables or function calls).These are com puted at com pile t ime and are assigned to the

static variables before the beginning of execution.

Initializers for other variables can be any valid CA-Clipperexpre ssion. The se are com put ed just prior to the creation of thevariables, and assigned to the variables immed iately af terward .Note that this allows a private variable to be initialized to thevalue held by an existing private or public variable with thesame name.

The following examples illustrate variable initialization with

various s tatements:STATIC lFirstT ime := .T.LOCAL i := 0, j := 1, nMax := MAXROW()PRIVATE cSt ring := "This is a string"PUBLIC lFinishedY et // Defaults to .F.

Local Variables

Local variables must be declared explicitly at compile time withthe LOCAL statement , as shown in the example below:

FUNCTION SomeFunc()LOCAL nVar := 10, aArray[10][10]

. <statements>

NextFunc()RETURN .T.

In the above exam ple, the variable nVar has been declared asLO CA L and defined as having a value of 10. W hen the funct ionNextFunc() is executed, nVar still exists but cannot be accessed.As soon as execution of SomeFunc() is completed, nVar isdestroyed . An y variable with the same name in the cal l ingprogram is unaffected.

2-34 CA-Clipper



Variables

Local variables are created autom atical ly each t ime theproced ure in wh ich they w ere declared is act ivated. Theycontinue to exist and retain their values until the end of the

activation (that is, until the procedure returns control to the codewh ich invoked i t ) . I f a proced ure is invoked recursively (forexample, calls i tself), each recursive activation creates a new setof local variables.

The visibility of a local variable is identical to the scope of itsdeclar ation. Th at is, the variab le is visible anyw here in thesou rce code to w hic h its declara tion app lies. If a pro ced ure isinvoked recursively, only the locals created for the most recentactivation are visible.

Static Variables

Static variables work much like local variables, but retain theirvalues througho ut execution. Stat ic variables mu st be declaredexplici t ly at com pile t ime with the STAT IC statement .

Their scope depend s on where they are declared. I f they aredeclared w ithin the body of a funct ion or proced ure, their scopeis limited to that rou tine. If they are decla red ou tside of any

routine, their scope is f i lewide. Rem em ber that to declarevariables with f i lewide scope, you must compile with the /Noption or, f rom the Workbench, uncheck Create Defaul tProcedure in the Compiler Options dialog box.

In this exam ple, the variable myVar is declared as STATIC andinitialized to a value of 10:

FUNCTION SomeFunc()STATIC myVar := 10

. <statements>





Variables

When the funct ion NextFunc() is executed, myVar still exists butcanno t be accessed. Unlike variables declared as LO CA L orP R I VAT E , myVar con tinue s to exist and retain its current va luewhen execution of SomeFunc() completes; however, i t can be

accessed only by subsequent executions of SomeFunc() .

The initialization of static variables (in this example to a value of10) occurs only once, at application startup. This prevents staticvariables from being initialized each time the declaring routine isinvo ked . Static variab les continu e to exist and retain their valuethrough out the execution of the application. They cannot bereleased.

Private Variab les

De claratio ns are optio nal for priva te variab les. If desired , theycan be declared explici t ly at compile t ime with the MEMVARstatement.

Private variables are created dy nam ical ly at runt im e with thePRIVA TE and PA RA M ETE RS sta tements. Addi t iona l ly,assigning a value to a previou sly uncreated variableautom atical ly creates a pr ivate variable. On ce created, a pr ivatevariable continues to exist and retain its value until terminationof the procedure activation in which it was created (that is, untilthe procedure which created it returns to the invokingpro ced ure ). At that t im e, it is auto m atically released. Privatevariables can also be explici t ly released using the RE LEA SEstatement.

It is possible to create a new private variable with the same nameas an exist ing private variable. Ho we ver, the new (duplicate)variable can only be created at a lower activation level than anyexist ing private variable with the same nam e. The new p rivate

hides any existing privates or publics (see Public Variables below)with the same name.

2-36 CA-Clipper



Variables

Once created, a private variable is visible to the entire programuntil i t is released (either explicitly or automatically, see above)or hidden by the creation of a new private variable with the

sam e na m e. In the latter case , the existing private b eco m esinaccessible until the new private is released.

In simpler terms, a private variable is visible within the creatingprocedure and any procedures cal led by the creat ing procedure,unless such a cal led proced ure creates i ts own private variablewith the same name.

For example:

FUNCTION SomeFunc()PRIVATE myVar := 10

. <statements>


In this exam ple, the variable myVar is created as a priva tevariable and ini t ia l ized with a value of 10. W hen the funct ionNextFunc() i s executed , myVar still exists and, unlik e a localvariable, can be accessed by NextFunc() . When SomeFunc()te rmina tes , myVar is released and any previous myVar defini t ion

becomes accessible .

Public Variables

Dec laratio ns are optio nal for pub lic varia bles. If desire d, theycan be declared explici t ly at compile t ime with the MEMVARstatement .

You can create public variables dynamical ly at runt ime with thePU BLIC statement . The y continue to exist and retain theirvalues until the end of execution unless they are explicitlyreleased with the RELEASE statement .

It is possible to create a private variable with the same name asan existing public variable. You ca nnot , how ever, create a publicvariable with the sam e nam e as an exist ing private variable.




Variables

Once created, a public variable is visible to the entire programuntil i t is explicitly released or hidden by the creation of a privatevariable with the sam e name. Then the new private variablehides the existing public variable of the same name, and the

public variable beco m es inaccessible unt i l the new private isreleased. For example:

FUNCTION SomeFunc()PUBLIC myVar := 10

. <statements>


In this example, myVar is create d as a pub lic varia ble andini t ia lized with a value of 10. W hen the funct ion Nex tFunc()

executed , myVar s t il l exis ts and can be accessed. Unlike L OC ALand PRIVATE var iab les , myVar stil l exists w hen execu tion ofSom eFunc() i s comple ted .

Declar ing a variable PUBLIC when the variable does not alreadyexist creates a new logical variable with an initial value of false(.F.).

Field Variab les

Declarations are optional for field variables. You can declarethem explici t ly at compile t ime with the FIELD statement .

Field variables are really just synonyms for database fields of thesam e name . Thu s, they typical ly exist and possess values evenbefore the program begins execution, and they continue to existaf ter the pro gram terminates . A f ield variable 's value depen dson which record of the associated database is the current record.

Once a database file is opened, the corresponding field variablesare visible to the entire prog ram . The y remain visible until thedatabase file is closed.

2-38 CA-Clipper



Expressions

Field variables are initialized with empty values when recordsare appended to the database file.

W hen a variable is declared as a FIELD , all subsequ entunqu alif ied references to that variable cause the progra m to lookfor a database field in the current work area (or to a specifiedwork area if the IN clause is used) with that name.

N o t e : Avoid issuing compiler direct ive ALIASing statementswithin executable code.

ExpressionsIn CA-Clipper, all data items are identified by type for thepu rpose of formin g expressions. The most basic data i tems ( thatis, var iables , constan ts , and fun ct ions) are assigned data typesdep endin g on how the i tem is created. For exam ple, the datatype of a field variable is determined by its database filestructure, the data type of a constant valu e depe nds on h ow i t isformed,, and the data type of a function is defined by its returnvalue.

These basic data items are the simplest expressions in theCA-C l ipper language . M ore comp l ica ted expressions a re formedby comb ining the basic i tems with operators . This sect iondefines al l of the val id CA -Clipp er data types and o perators thatyou will use to form expressions, as well as any special rules youneed to know.

Pro gram m ing a n d Utilit ies G uide 2-39



Data Types

Data Types

The data types supported in the CA-Clipper language are:

• Array• Character

• Cod e Block

• Numer ic

• Date

• Logical

• Memo

• NIL

In CA-Clipper, an array structure is a separate data type, andthere are distinct operations for arrays that are invalid for otherdata types. Co de block s are also a data type, but the opera tionsthat you can perform using them is limited. Separate sect ions inthis chapter discuss Arrays and Code Blocks.

This section discusses each of the simple data types, providingyou w ith the fol lowing inform ation: wh en to use the data type;how to form its constants, or li terals; what limitations apply; andwhat operat ions are avai lable.

Character

The character data type identifies data items you want toma nipu late as f ixed length s tr ings. The CA-C lipper character setis defined as the entire printable ASCII character set (that is,CHR(32) through CHR(126)) , the extended ASCII graphicscharacter set ( that is , CH R(12 8) throu gh CH R(25 5)) , and the nul lcharacter, CHR(O).

Valid character strings consist of zero or more characters in thedefined character set with a maximum of 65,535 characters perstring (that is, 64 KB minus one character used as a nullterminator) .

2 -40 CA-Cl ipper



Data Types

Chara cter s t r ing l i terals , or constants , are formed by enclosing aval id s tr ing of characters within a designated pair of del im iters .In the CA-Clipper language, the fol lowing del imiter pairs are

designated:• two single quo tes (for exam ple, 'one to open and one to

close')

• two double quotes (for exam ple, "one to open and one toclose")

• left and right squ are brac kets (for exa m ple , [left to op en andright to close])

N o t e : To exp ress a null string, use only the delim iter pair with

no in te rvening charac ters—including spaces . For exam ple ,""and [] both represent a null string.

Since all designated delimiter characters are part of the validcharacter set , the del imiter characters them selves can be part o f acha racter string. To includ e any of these characters in a chara cterstring literal, you must use an alternate character for thedelimiter.

For exam ple, the fol lowing str ing:

• I do not w an t to go.

could be expressed as:

• "I do not w an t to go."

Similarly, the string:

• She said , "I hav e no idea."

can be represented with:

• 'She said , "I ha ve no idea. '"

This constraint should no t be too l imit ing s ince you have threepairs of del imiters from which to choose.

Pro gram m ing a n d Utilit ies G uid e 2-41



Data Types

N o t e : Th e m em o data type discussed later in this sectionrepresents variable length character data. It is a true variablelength data type that can only exist in the form of a databasefield. An y opera tion that is valid for chara cter strings is also

valid for memo fields, and vice versa.

Cha racter s tr ings are com pared according to the ASC II col latingsequenc e. M em o fields can also be com pared to characterstr ings. W hen SE T EX AC T is OF F two character s tr ings arecompared according to the fol lowing rules; assume two characterstrings A and Β where the expression to test is (A = B):

• If Β is nu ll, retu rn true (.T.).

• If LE N(B ) is grea ter than LE N (A ), return false (.F.).

• Co m pa re all cha racte rs in Β with A. If all chara cters in Βequa l A, return tru e (.T.); otherw ise return false (.F.).

With SET EXACT ON, two str ings must match exact ly, except fortrai ling blank s. For comp lete detai ls on SET E XA CT , see theReference Guide, Volume 2.

M e m o

The m em o data type is used to represent variable lengthcha racter da ta. It is a true variable length data type that can o nlyexist in the form of a databa se field. A me m o field uses tencharacters in the database record, space that is used to store apointer to the actual data, which is stored in a separate (.dbt) file.

The contents of a memo (.dbt) file are handled in blocks of 512bytes. Each m em o field in the database (.dbf) file contains theblock num ber in ASCII w hich identif ies the m em o field datalocation. If the m em o field contains no data there is no n um berin the database (.dbf) file. When the user writes to a memo field,the next available block is used and its number is stored in theblock number f ield.

In CA-Clipper, when you change a memo field with less than 512by tes, the existing bloc k is used until i t is filled. On ce full, theblock is discarded and copied to a new location.

2-42 CA-Clipper



Data Types

Besides the fact that the length can vary in a memo field fromone record to another, memo f ields are ident ical to characterf ields. The character set is ident ical , the 65,535 ma xim umcharacter l imitat ion s tands, and comparisons are performed inthe same way.

Since it can apply only to a field, there is no literal representationfor the memo data type. However, you can assign characterstr ing l i terals to memo f ields with REPLACE.

Date

The date data type is used to identify data items that representcalendar dates . In CA-Clipper, you can manipulate dates inseveral w ay s, such as f inding the nu mb er of days between twodates and determining what the date wil l be ten days from now.The date character set is defined as the digits from zero to nineand a separator character specif ied by SET DATE.

You can use SET EPOCH to change the defaul t centuryassum ption. See the entry for this com ma nd in the ' 'Lang uag eRefere nce" chapter of the Reference Guide for more information.

Form dates by s tr inging together digi ts and separators in theorder that is defined by the current SET D AT E value. By defa ul t ,SET D ATE is AM ER ICA N and da tes a re of the formmm/dd/[cc]yy:

m mm represents the month and must be a value between 1 and12

• dd represents the day which must fal l between 1 and 31

• cc, i f specif ied, represents the century and mu st be betw een 0

and 29• yy represents the year which must fal l between 0 and 99; and

/ is the separator

Programming and Util i t ies Guide 2 -43



Data Types

CA-Clipper supports al l val id dates in the range 01/01/0100 to12 /3 1/ 29 99 as well as a null , or blank, date. You can specify thecen tury as part of a literal date regard less of the status of SETCENTURY; however, you wil l not be able to enter non-twentiethcentury dates in @...GET variables, nor will you be able todisplay the century, unless SET CENTURY is ON.

Dates do not have a straightforward literal representation likecharacter s trings and numb ers. Instead, you must use theCT OD () funct ion to convert a character s tr ing constant expressedin date form into an actual date value. To do this, you form thedate according to the rules described above and enclose it in oneof the character string delimiter pairs. Then, you use thecharacter date as the CTOD() argument as illustrated in the

examples below:CTOD("1/15/89")CTOD('03/5/63')CTOD( [09/28/1693] )CTOD("01/01/0100 " )

CT OD () check s its arg um ent to be sure it is a valid date. Forexample , 11/31/95 and 02/29/97 would not be va l id da tesbecause November has only 30 days, and 1997 is not a leap year.CTODQ converts an invalid date to a null date.

N o t e : To expre ss a blan k, or null date, use a null string as theargument for CTOD() (for example, CTOD("")) .

Dates are com pared acco rding to their chronological order. An ynon-blan k date alway s com pares as greater than a blank date.Less than an d /o r equali ty comp arisons of a non-blank date to ablank date always returns false (.F.).

2-44 CA-Clipper



Data Types

Numeric

The numeric data type is used to identify data items that youwant to manipulate mathematical ly (for example, performaddit ion, mu lt ipl icat ion, and other ma them atical funct ions) . TheCA -Clipper num eric character set is defined as the digits fromzero to nine, the period to represent a decimal point, and theplus and minus to indicate the sign of the number.

W ith the exception of f ields, CA -Clippe r s tores num eric valuesusing the IEEE standard double precision floating point format,making the range of numbers from 10Λ-308 to 10Λ308. Numer icprecision is guaranteed up to 16 significant digits, and

formatting a numeric value for display is guaranteed up to alength of 32 (that is, 30 digits, a sign, and a decim al poin t). Th ismeans that numbers longer than 32 bytes may be displayed asasterisks, and digits other than the 16 most significant ones aredisplayed as zeros.

When a value is stored in a numeric field of a database (.dbf) file,it is converted from IEEE format to a displayable representation.When a numeric field is retrieved from a file, i t is converted backto IEE E format before any ope ration s are perfo rm ed on it . Since

the displayable form at of a num eric value is guaranteed up to alength of 32 bytes, this is the largest recommended numeric fieldlength.

Form numeric literals by stringing together one or more of thefollowing:

• A single leading plus or m inu s sign

• On e or m ore digits to repres ent the wh ole portion of thenumber

• A single dec ima l poin t• On e or m ore digits to repre sent the fractional part of the

number




Data Types

Some val id numeric constants are shown below:

• 1234

• 1234.5678

• -1234

• +1234.5678

• -.5678

N o t e : Un like cha racter strings, li teral num eric values are notdel imited. If you enclose a num ber— or any other s tr ing ofcharac ters—in del imiters , it beco me s a character s tr ing.

Numbers are compared according to their actual numeric value.No te that the = operator and the = = operator behave identicallywhen comparing numbers, they both check for equali ty to themaximum precision al lowed by the IEEE 8-byte f loat ing pointformat.

Numeric operat ions, including comparisons, are completelyunaffected by any SET comm and . If num eric operat ions orcom parison s app ear to prod uce un expected resul ts , i t isproba bly becau se of the automatic display formatt ing of f loat ingpoint values. The display form att ing is affected by the SETFIXED and SET DEC IMA LS comm ands .

Logical

The logical data type identifies data items that are Boolean innatu re. Typ ical logical data item s are those with value s of trueor false, yes or no, or on or off. In CA-C lipp er, the logicalcharacter set consists of the letters y, Y, t, Τ, η, N, f, and F.

Tho ugh only two logical values are possible, in CA -Clipper thereare several way s to repre sent these two value s. To form a literallogical value, enclose one of the characters in the defined logicalcharacter set betw een tw o periods. The periods are del imitersfor logical values just as quote marks are for character strings.

2 -46 CA-Clipper



Data Types

The literal values .y., .Y., .t., and .T. represent true. The literalvalues . η., .N., i . , and .F. represe nt false. Th e prefe rred literalrepresentations are .T. and .F.

For the purpose of comparing logical values, false (.F.) is alwaysless than true (.T.).

NIL is a data type that allows you to manipulate uninitializedvariab les withou t genera ting a run time error. It is a data typ ewith only one possible value, the NIL value.

The literal representation for NIL is the string of characters" N I L " without del imiters . When referenced by a displaycom m and or funct ion, this is how NIL values display. No te alsothat NIL is a reserved w ord in C A-C lipper.

For the purpose of comparison, NIL is the only value that isequa l to NI L. All other values are greater than NIL .

There are several declarat ion statemen ts that autom atical ly

assign a NIL value to variables and array elem ents . Thesestatements are listed in the following table and discussed below:

O p e r a t i o n Descr ip t ion

DE CLA RE Ass ign NIL to a r ray e lements

L O C A L Assign NIL to local variables and arrayelements

PA R A M E T E R S Assign NIL to missing parameters

PRIVATE Assign NIL to private variables and arrayelements

STA TIC Assign NIL to s tatic variables and arrayelements




Operators

All variables , with the exception of PUBLIC and FIELDvariables , are init ia l ized to NIL w hen declared or createdw itho ut an initializer. PU BL IC variables are initialized to false( .F.) when created, and FIELD variables cannot contain NILvalues at all . When you create an array with a declarationstatement , including PU BL IC, al l e lements are ini tia l ized to N IL.

When you invoke a funct ion or procedure, i f you omit anargument ei ther by leaving an empty spot next to a comma or byleaving an a rgum ent off the end, a NIL value is passed for thatargum ent . No te, how ever, that the funct ion or procedu re cannotdist inguish betw een a NIL valu e that is passed explici tly (forexam ple, an expression in the argum ent l ist that evaluates toNIL) and one that is passed as the result of omitting an

argument .

Operators

Alon g w ith funct ions, constants , and variables , operators are thebasic bui lding block s of expression s. An op erator is l ike afunction in that i t performs a specific operation and returns avalu e. This section gives a gene ral discussion of ope rators, and

categorizes and describes all of the operators available in theCA-Cl ipper language .

Terminology

The fol lowing paragraphs discuss, br ief ly, several terms usedregarding operators in order to help you understand theremaining material in this section.

Over load i ing In CA -Clipp er, the m eaning of cer tain operators chang es,depen ding on the data type of the operan d(s) . For examp le, theminus operator (-) can be used to concatenate character strings aswell as subtract numeric or date values. Using the same sym bol,or operator, for different operations is called overloading.

2-48 CA-Clipper



Operators

All operators in CA-Clipper require ei ther one or twoarguments , cal led operands. Tho se requir ing a s ingle operandare called unary operators, and those requir ing two operan ds arecalled binary operators.

Binary operators use infix notat ion which means that theoperator is placed between i ts operands. Unary operators useprefix or postfix notat ion where the operator is placed ei therbefore or af ter the operand, depending on the operator and howyou want to use it .

An ex am ple of a un ary prefix op erator is the logical negation ( )

operator:lTrue := .Τ.? lTrue // Resul t: .F.

The post increment operator (++) is an example of a unary postf ixoperator. This operator increments i ts operan d by a value ofone:

nCount := 1nConnt++ // Result: nCount is now 2

The multiplication operator (*) is an example of a binaryoperator which demonstrates inf ix notat ion:

? 12 * 12 // Resul t: 144

P r e c e d e n c e Precedence rules determ ine the order in wh ich different operato rsare evalua ted within an expression. These rules define thehierarchy of all of the operators within an expression.Parentheses can be used to overr ide the defaul t and heirarchicalorders and to make complicated expressions more readable.

Unary and BinaryOperators




Operators

Error Handling

Op erators are used to form expressions and m ust , therefore,adhere to certain rules. For exam ple, you cannot use a unaryoperator that allows only prefix notation as a postfix operatorand , except in a few well-defined circum stances, you cannot useany binary operator on operand s with different data types. Allof the rules that apply to operator usage are described in thissection, and using any operator incorrectly results in a runtimeerror.

String Op erators

The following table lists each string operator and the calculationthat i t perform s. These operators are binary, requir ing tw ocharacter and/or memo type operands, and return a charactervalue:

S y m b o l O p e r a t i o n

+ Concatena te

Concatenate without intervening spaces

The minus (-)concatenation operator moves the trailing spaces ofthe first op eran d to the end of the resulting string, so that thereare no intervening spa ces betw een the two original s t r ings. Theplus (+) con catenat ion o perator leaves spaces intact .

2-50 CA-Clipper



Operators

Date Operators

The + and - mathematical operators discussed in the next sect ioncan be used to add or subtract a number of days from a datevalu e. Th e result of such an opera tion is a date that is a nu m be rof days before (subtraction) or after (addition) the date value.The order of the operands in the case of subtraction iss ignif icant—the d ate value must come f irst . This is an exc eptionto the rule against operat ions using m ixed d ata types.

In the precedence rules defined at the end of this section, thistype of mixed operat ion is considered to be mathematical ratherthan date.

You can also subtract one date from another using thema them atical subtract ion operator. The resul t of this type ofoperat ion is a numeric value that represents the number of daysbetw een the two dates . Subtract ion of one date from anothe r isthe only true date operator.

Ma them atical Operators

The fol lowing table l is ts each mathematical operator and thecalculat ion i t perform s. As a general rule , these ope ratorsrequire numeric type operands (see Date Operators above forexceptions) and return a numeric value. Except where noted inthe table, the ma them atical operators are binary. The u naryoperat ions u se pref ix n otat ion:


+ Addit ion or unary posi t ive

Subtract ion or unary negat ive* Mult ipl icat ion

/ Division

Modulus ( integer remainder of divis ion)

** or Λ Exponentiat ion




Operators

Relational Ope rators

Below is a list of relational op erators and their purpo se. All ofthem are binary operators requiring either two operands of thesame data type or at least one NIL operand.

The result of a relational operator is a logical value:


< Less than

> Greater than

= Equal

Exactly equal for character; equivalencefor arrays and objects; equal for other datatypes

< > , #, or = No t equal

< = Less than or equal

> = Greater than or equal

$ Is co nta ine d in the set or is a sub set of

SET EX AC T affects both the $ and the = operator w hencom paring str ings. I f SET EX AC T is ON , both s tr ings must beidentical in content and length (except trailing spaces) in orderfor these operations to return true (.T.).

The = = operator com pares s tr ings ( that is , character and m em otypes) for exact equality in length and content, including trailingspac es. For array s, i t check s that both a rrays refer to the sam earea of m em ory . For all other data types, the == o perator isequivalent to the = operator.

2-52 CA-Clipper



Operators

Logical O perators

The following table lists the logical operators:


.AND . Logical and

.OR. Logical or

.NO T. or Logical negate

All of the logical operators requ ire logical operands an d, excep tfor nega te, they are binary . .NOT . and are unary pref ixop erato rs. Th e result of a logical operatio n is alw ays a logicalvalue.

The quick way to define these operators is to tell when theyreturn true: .AND. returns true if both operands are true; .OR.returns true if either operand is true, and .NOT. returns true if i tsoperand is false. Truth tables defining all of the logical operatorsare shown below:

.AND. J . .F.

J . .T. .F.

.F. .F. .F.

.OR. J . .F.

J . X .T.

.F. .T. .F.

.NOT. J . .F.

.F. .T.




Operators

Assignment Operators

CA-Clipper has several operators that assign values to variablesand these are summarized in the table below:


= Assign

:= Inline assign

+= Inline add (or concatenate) and assign

-= Inline subtrac t (or con caten ate) and assign

Inline multiply and assign

/= Inline divide and assignΛ — Inl ine exponentiate and assign

/ o — Inl ine modulus and assign

All assignment operators are binary and require a s ingle variableas the fi rs t opera nd. The second o perand can be any val idexpre ssion, including N IL, provided that the data type is sui tablefor the ope ration. For the co m po un d opera tors (that is, all exce pt= and :=), the variable used as the first operand must exist andmust be the same data type as the second operand, except forsome date and numeric operat ions. These exceptions aredescribed af ter the fol lowing table which summarizes theassignment operators by data type:

O p e r a t o r Va l id Da ta Types

All

:= All

+= Charac ter, Date , Memo, Numer ic

-= Charac ter, Date , M em o, Num er ic* _ Numer ic

/ = Numer ic

**= or Λ = Numer ic

= Numer ic

2-54 CA-Clipper



Operators

In addition to these data types, -= and += allow a dateexpression as the f irs t operan d and a num eric expression as thesecond op erand . The resul t is a nu m ber of days added orsubtracted from the date and the new value assigned.

The assignment operators in CA-Clipper always assume that theassigned variable is a M EM VA R unless i t is expl ici t ly declared asa differen t storage class or explicitly qu alified with an alias. Th e"field f i rs t" rule does not apply wh en assigning.

N o t e : W ith respect to the stora ge class of varia bles, there is nodifference betw een := and =. (The only difference betw een :=and = is that := can be used as part of an expression since it is not

confused with an equal i ty test . ) Any assignment operatorassum es ME M VA R if the variable reference is am biguo us. I f anattempt is being made to assign to a field, the field variable mustbe ei ther declared with the FIELD statement or referenced withan alias—either the assigned alias or the FIELD-> alias.

Simple Ass ignment

The simp le assignm ent op erator (=) assigns a value to a variable.It is identical in operation to the STORE command that initializesa s ingle variable and m ust be specif ied as a prog ram statemen t .If used within an expression it is interpreted as the equalityoperator. For exam ple:

nValue =2 5nNewValue = SQRT(nValue) ** 5nOldValue = nValue

are al l val id s imple assignm ent s tatemen ts . The f i rs t op eran d, aswith al l other assignmen t s tatem ents , can be a database f ield asw ell as any oth er variable. The result is that the field is repla ced

with the new value.

For exam ple, the fol lowin g tw o l ines of code perform exact ly thesam e funct ion of replacing the current value in the Cast Age fieldwith the numeric value 20:

FIELD->CustAge = 20REPLACE CustAge WITH 2 0




Operators

Inl ine Assignment

You can use the assignment operator ( :=) interchangeably withthe s imple assignment operator. For example:

nValue := 2 5nNewV alue := SQRT(nVal ue) ** 5nOldVal ue := nValue

duplicates the previous example.

This operator, however, is an inline operator which means i t canbe used in any command or funct ion whose syntax al lows theuse of an exp ression . Th e data type of an inline assig nm entoperation is the same as the data type of the second operand.

Several examples of inl ine assignment fol low:

LOCAL nValue := 10IF (dDate := (DATE() - 1000)) = CTOD("12/20/79")? SQRT(nValue := (nValue ** 2))cTransNo := cSortNo := (Custld + DTOC(DATE()) )

This last example demonstrates mult iple assignments using theinl ine assignment operator as you would use the STOREcom m and . W hen := is used in this wa y, the assignmen ts areexecuted from right to left .

This feature is particularly useful when you need to store thesame value to many different fields, possibly in differentdatabase files:

CustFil e->CustI d := TransFil e->Trans No := ;(Custld + DTOC(DATE())



Opera to r s

C o m p o u n d A s s i g n m e n t s

The compound assignment operators perform an operat ionbetween the two operands then assign the result to the firstoperand. These operators are summarized and defined in thefollowing table:

O p e r a t o r E x a m p l e Definit ion

+= a += b a := (a + b)

-= a - = b a := (a - b)

a * = b a := (a * b)

/= a / = b a := (a / b)0/ _/ o — a % = b a := (a % b)

Λ — a A = b a := (a Λ b )

Note that the definitions for these operators use the inlineassignm ent operator. This m eans that al l of the com pou ndope rators can be used as inline ope rators . Th e data type forthese operat ions is determined by the second operand using the

definitions in the table abo ve. If the assignm ent ope ration isformed correctly, this should be the data type of the firstoperand in the original compound assignment s tatement .

N o t e : I t is not advisable to use com pou nd a ssignmen t op eratorswi th REPL AC E or UPD AT E s ince the WITH c lause provides theassignment funct ion as part of the command syntax.




Operators

Increment an d De creme nt O perators

The increment (++) and decrement (--) operators aresummarized in the table below:


++ Prefix or postf ix increm ent

Prefix or postf ix d ecremen t

Both are unary o perators yo u can use with ei ther a num eric or adate opera nd. Unlike other operators w hich can operate onmore complicated expressions, the operand here must be a

single , non field varia ble. Th e resultin g data type is the sam e asthat of the operand.

The ++ opera tor increments, or increa ses the valu e of, i ts ope randby one, and the — operator decrements, or decre ases the valu e of,i ts opera nd by one. Thu s, both operators perform an o perat ionon, as well as an assignment to , the operan d. The fol lowingshows how these operators might be defined in terms of addit ion(and subtract ion) and assignment operators:

• value++ is equ ivalen t to value := value + 1

m value-- is equivalent to value := value -1

Both operators can be specified as prefix or postfix: the prefixform changes the value of the operand before the assignment ismade, whereas the postf ix form changes the value af terwards.In other w ord s, the postf ix form delays the assignmen t port ion ofthe operation until the rest of the expression is evaluated, andthe pref ix form gives the assignmen t preceden ce over al l otheroperat ions in the exp ression.

The fol low ing cod e i l lustrates the preincrement o perator in anassignm ent s tatement . Since the increm ent occurs before theassignment takes place, both variables have the same value:

nValue := 1nNewValue := ++nValue? nNewValue // Result: 2? nValue // Result: 2

2-58 CA-Clipper



Operators

The next example demonstrates the postdecrement operator.Becau se the assignme nt takes place before the original variable isdecremented, the two values are not the same:

nValue := 1nNewValue := nValue--? nNewValue // Result: 1? nValue // Result: 0

The next example further il lustrates the difference in the prefixand postf ix form s of these op erators:

nValue := 10? nValue++ * nValue // Result: 110? nValue // Result: 11

Here, the postincrement operator is used to increase the firstoperan d of the mult ipl icat ion operat ion by on e, mak ing i ts value11; how ever, the assignmen t of this new value to the nValuevariable will not take place until the entire expression iseva luate d. Th us , i ts valu e is still 10 w hen the m ultiplic ationope ration o ccu rs, and the result of 11 * 10 is 110. Finally , wh ennValue is que ried again after the exp ression is eva luate d, thepost increm ent assign men t is ref lected in i ts new value, 11.

In this last example, the predecrement operator is used todecrease the f irs t operan d of the mu lt ipl icat ion by o ne, m akingits valu e 9.

Add it ional ly, the assignm ent of this new value to the nValuevariable takes place before the rest of the expression is evaluated.Thu s, the new valu e is used to perform the m ult ipl icat ionoperation, and the result of 9 * 9 is 81:

nValue := 10? --nValue * nValue // Resul t: 81? nValue // Result: 9




Operators

Special Operators

The following table lists all other symbols that have specialmeaning in the CA-Clipper language. These are special

operators that of ten appear in ex pressions:


0 Function or grouping

[ ] Array elemen t

{ } Co nstan t array definition

-> Alias identifier

& Compile and execute

@ Pass by referenc e

Parentheses are used in expressions either to group certainoperations in order to force a particular evaluation order or toindicate a funct ion cal l. W hen specifying the grouping o perator,the item that falls within the parentheses must be a validexpression. Subex pressions can be further group ed. Forfunct ion cal ls , a val id funct ion na m e mu st precede the lef t

parenth esis , and the funct ion arg um ents , if any, mu st becontained within the parentheses.

The subscript operator ([]) is used to reference a single arrayelemen t . The nam e of a previou sly declared array mu st precedethe lef t bracket and the array elem ent index m ust app ear as anumeric expression within the brackets .

Parentheses

Subscript

2-60 CA-Clipper



Opera to r s

Curly Braces Curly braces (()) are used to create and reference a li teral array.The array elements must be within the braces and separated bycommas .

Alias Identifier

M a c r o

Pass-by-Reference

Curly braces are also used to create code blocks. The code blockargum ents are further del imited w ithin the curly braces withvertical bars ( I I ) , and the expressions defining the code blockare separated by comm as. Tho ugh the vert ical bars are requireddel imiters , they need not contain an a rgum ent .

The alias identifier (->) is used to make an explicit reference to afield or varia ble. If the na m e of an alias prec edes the ope rato r, itcan be followed either by a field name from that database file orany other expression enclosed in parenthe ses. Add it ional ly, thekeywords FIELD and MEMVAR can precede the opera torfollowed by a valid field or variable identifier.

The m acro sym bol (&) is the com pile-and-ru n o perator. I t is aunary pref ix operator whose only val id operand is a charactervariab le. This operato r is discu ssed in full detail und er Th eMacro Operator later in this chapter.

The pass-by -reference operator (@) is val id only in the arg um entlists of function or procedure calls using the function-calling

syntax. I t is a unary pref ix operator wh ose operan d can be anyvariable name . I t wo rks by forcing the argum ent to be passed b yreference rather than by value to the function or procedure.

Operator Precedence

When evaluat ing expressions with two or more operat ions thatare not explici tly group ed tog ether with paren theses,CA-Clipper uses an established set of rules to determine the

order in wh ich the various operat ions are evaluated. Theserules, called precedence rules, define the hierarchy of all of theoperators discussed so far in this section.

N o t e : All function calls and other special operators in anexpression are evaluated before an y other operato rs .

Prog ram m ing a n d Utilit ies G uide 2-61



Operators

P r e c e d e n c e o f C a t e g o r i e s

For the most part, expressions in CA-Clipper are operations thatma nipu late a s ingle data type. For examp le, an expression m ight

concatenate several character strings or perform a series ofmathematical operat ions on several numbers. There are,how ever, expressions in wh ich the evaluat ion of several differenttypes of operat ions is necessary. For examp le, a com plex logicalexpression can involve several related operations, on differentdata types, that are connected with logical operators as shown inthis example:

cStringl $ cString2 .AND. nVall++ > nVal2 * 10

W hen m ore than one type of operator appea rs in an expression,

all of the subexpressions are evaluated for each precedence levelbefo re subexp ressio ns at the nex t level are evalu ated . Exce pt formultiple inline assignments, all operations at each level areperformed in order from left to right; multiple inline assignmentsare performed from right to left .

The heirarchical o rder of precedence for the operators , bycategory, is as follows:

1. Preincrem ent and Predecrem ent

2. Mathemat ica l

3. Relat ional

4. Logical

5. Ass ignment

6. Post increm ent and Postdecrem ent

The nonassignment port ion of the compound assignmentoperators (for example, the multiplication portion of *=) exists atlevel 2, and the assignment portion exists at level 5.

2 -62 CA-Cl ipper



Opera to r s

P r e c e d e n c e w i th in a C a t e g o r y

W ithin each category, the individual operators also have an

establ ished preced ence, which is cr i t ical—esp ecial ly inmathematical operat ions.

Take the fol lowing two expressions:

• 5 * 1 0 + 6 / 2

• 6 / 2 + 5 * 1 0

Algebraical ly, these are equivalent expressions. Though wordeddifferently, the result of both expressions is 53. If CA-Clipperdid not establish an order of precedence for evaluatingmathematical operators , you could not evaluate this expressioncorrect ly without using parentheses.

Without precedence among operators , a l l mathematicaloperators would be performed in order from left to right, and thetwo forms of the expression shown above would be evaluated asfollows: the first would multiply 5 * 10, add the resulting 50 to 6,and divide the resulting 56 by 2 to obtain 28; the second woulddivide 6 by 2, add the resulting 3 to 5, and multiply the resulting8 by 10 to obtain 8 0. Ne ither result is correct, and the two res ults

are not the same.

To save you from hav ing to use parentheses in com plicatedexpressions and to ensure that equivalent expressions give thesame resul t , CA -Clipp er uses an establ ished order for evalu at ingoperations in each category.

P r e i nc r e m e n t a n d P r e d e c r e m e n t

As mentioned earlier, the prefix and postfix forms of theincrement and decrement operators are considered as separatecategories becau se they have dis t inct preced ence levels . Thiscategory refers to the prefix form of the increment anddecrement operators .

Both operato rs in this categ ory ( ++ and - ) ex ist at the sam eprecedence level and are performed in order from left to right.




Operators

M a t h e m a t i c a l

When more than one mathematical operator appears in anexpressio n, al l of the subexp ressions are evaluated for each

preced ence level before subexp ressions at the next level areevalu ated. All operat ions at each level are perform ed in orderfrom lef t to r ight . The order of preced ence for the mathem aticaloperators is as follows:

1. Un ary posi t ive and negat ive (+, - )

2. Exp one ntiatio n (**, Λ )

3. M ult ipl icat ion, divis ion, and mo dulu s (*, / , %)

4. Ad dit ion and subtract ion (+, - )

Relat ional

All of the relational operators exist at the same precedence leveland are performed in order from left to right.

Logical

Like the mathe matical operators , the logical operators also hav e

an establ ished order of preced ence. W hen m ore than one logicaloperator ap pears in an expre ssion, al l of the subexpressions areevaluated for each precedence level before subexpressions at thenex t level are eva lua ted. All operatio ns at each level areperform ed in order from lef t to r ight . The order of preceden cefor the logical operators is as follows:

1. Un ary nega te ( .NOT.)

2. Logical and ( .AND.)

3. Logical or (.OR.)

2-64 CA-Cl ipper



Operators

Ass ignment

All of the assignment operators exist at the same precedence

level and are perfo rm ed in order from right to left . For thecompound operators , the nonassignment port ion (for example,addition or concatenation) of the operation is performed first ,fol lowed immediately by the assignment .

N o t e : The incremen t and decrem ent assignm ent operat ionsexist at their own level of precedence, and are not part ofassignment category.

Pos t incremen t a nd P os tdec reme n t

Both op erators in this catego ry ( ++ and —) exist at the sa m eprecedence level and are performed in order from left to right.

Parentheses

You can override the order of precedence for expressionevaluat ion using parentheses. W hen parentheses are present inan expression, all subexpressions within parentheses are

evaluated first using the precedence rules described in thissection, if nece ssary . If the pare nthese s are neste d, theevaluation is done starting with the innermost pair andproceeding outward.

Note that a l though the CA-Clipper language provides a specif icorder of precedence for evaluating expressions, i t is betterprogramming pract ice to explici t ly group operat ions forreadability and to be certain that what executes meets yourexpectat ions.

Prog ram m ing an d Utilit ies G uide 2-65



The Macro Operator

The Macro Operator

The macro operator (&) in CA-Clipper is a special operator thatallows runtime compilation of expressions and text substitution

within strings. When ever the macro operator (&) is encountered,the operand is submitted to a special runtime compiler referredto as the macro compiler that can cornpile expressions, but notstatements or commands.

You can specify a macro using a variable containing a characterstring or an express ion that returns a character st ring. If acharacter variable is used to specify a macro, it is referred to as amacro variable and specified as follows :

8c<macroVar>.

The period (.) is the macro terminator and indicates the end ofthe macro variable. The macro terminator is optional unless youneed it to distinguish the macro variable from the adjacent text inthe statement.

You can also apply the macro operator (&) to an expression,referred to as a macro expression if the expression evaluates to acharacter value and is enclosed in parentheses:

{<macroExp>)

In this instance, the expression is evaluated first, and the macrooperation is performed on the resulting character value. Thisallows the contents of fields and array elements to be compiledand run.

The macro operator (&) can perform text substitution or runtimecompilation of an expression, depending on how it is specified.

2 66 CA Clippe r



The Ma cro Op era to r

Text Substitution

Whenever a reference to a pr ivate or public macro variable is

encountered embedded within a character s t r ing, the contents ofthe macro variable a re subst i tuted for the variable referen ce:

cMacro := "there"? "Hello kcMacro . " // Resul t: Hello there

When you use the macro operator for text substitution in thismanner, the operand must be a public or pr ivate variable whosedata type is character, and the ma cro operator mu st imm ediatelypre ced e the variable. If you fail to follow the se guidelin es, themacro variable wil l not be expanded properly.

For example, a t tempting to use the macro operator on a localvariable results in a compiler error:

cMacro := "there"? "Hello kcMacro. " // Compiler error

Enclosing the macro variable in parentheses, on the other hand,causes the macro variable to be treated as li teral text:

cMacro := "there"? "Hello &(cMacro)" // Result: Hello &(cMacro)

Text subst i tut ion is not l imited to ma cro variables , how eve r. Yo ucan use macro expressions for this purpose as i l lustrated below:

ABCXYZ := "TEST"cMacrol := "ABC"cMacro2 := "ΧΥΖ"

? &(cMacrol + cMacro2) // Resul t: TEST

Keep in mind, though, that you stil l cannot substitute thecontents of a declared (that is, lexically scoped) variable, becausedeclared variable nam es are not know n at runt ime . In this

exam ple, the error canno t be caught at compile t im e, but atrunt ime the error message "Variable does not exist : ABCXYZ" isdisplayed:

LOCAL ABCXYZ := "TEST"cMacrol := "ABC"cMacro2 := "ΧΥΖ"

? &(cMacrol + cMacro2) // Expected result: TEST

Prog ram ming a nd Utilit ies G uid e 2-67



The Ma cro Ope ra to r

Com pile an d Run

When CA-Clipper encounters a macro variable or macroexpression w ithin an expression, the macro symb ol behaves as

the compile-and-run operator.

If the macro is specified as a macro variable, the contents of themac ro variable is com piled by the macro com piler, then thecompiled code is executed and discarded:

cMacro := "DTOC(DATE())"? &cMacro

If an expression is specified enclosed in parentheses andprefaced by the macro operator (&), the expression is evaluated

and the resulting character string is compiled and run just as amacro variable is:

? &(INDEXKEY(0))

One of the interesting effects of macro expressions is that youcan compile a character string containing a code block definition.In this case, the character string containing the code block iscompiled and the run portion of the operation returns the codebloc k as a valu e. The resulting cod e block is saved an devaluated later with the EVAL() function.

bBlock := &("{|exp| Q0UT(exp)}")

EVAL(bBlock, DATE())

2-68 CA-Clipper




Relationship to Commands

Because of the long history of the macro operator (&) in

CA -Clipp er and i ts anteceden ts , it is impo rtant to understand theprecise nature of the relat ionship between commands andmacros.

U sin g w it h C o m m a n d K e y w o r d s

First , the macro o perator (&) cannot be used to substitute orcom pile com m and keyw ords. In CA -Clipp er, this is becau secommands are preprocessed into s tatements and expressions at

compile t ime.

N o t e : Redefini t ion of com m and keyw ords, how ever, can beaccomplished by modifying the command defini t ion in STD.CH,overr iding an exist ing com ma nd d efini t ion with a new defini t ionusing the #command direct ive, or redefining a commandkeyw ord using the #translate direct ive. In any case, redefini t ionof a command keyword can occur only at compile t ime—not atrunt ime.

U sin g w i th C o m m a n d A rg u m e n t s

Seco nd, in pr ior versions of CA-C lipper as well as other dialects ,ma cro variables were often used to specify the argum ents ofco m m an ds requirin g literal text valu es. This includ ed all filecom man d argum ents as wel l as SET comm ands w i th toggleargum ents . In these instances, you can now use an extendedexpression in place of the literal arg um ent if the expre ssion isenclosed in parenth eses. For examp le:

xcDatabase = "Invoices"USE &xcDatabase.

can be replaced with:

xcDatabase = "Invoices"USE (xcDatabase)

Prog ram ming an d Utilit ies G uide 2-69



The M acro Ope ra to r

It is important to use extended expressions, especially if you areusing local and static variables . Co mm and s are generallypreprocessed into funct ion cal ls with command argumentstranslated into funct ion argu men ts as legal CA-Clipp er values.

With f i le commands, for instance, f i lenames are stringified usingthe smart stringify result marker and passed as arguments to thefunctio ns that actually perfo rm the desired action s. If a li teral orma cro value is specif ied as the com ma nd argum ent , it isstringified. If, ho w eve r, the argu me nt is an extend ed ex pressio n,it is w ritten to the result text exactly as specified. For exa m ple,when the fol lowing specif icat ions of the RENAME command arepreprocessed, the result text is written as shown in bold:

#command RENAME <xc0ld> TO <xcNew> ;=> FRENAME(<(xcOld)>, <(xcNew)>)

RENAME &xc0ld TO &xcNewRENA ME (xcOld) TO (xcNew)FRENAME("&xc01dn, "&xcNew")FRENAME(xcOld, xcNew)

W hen the ma cro variables are s tr ingif ied, the macro variablenam es are hidd en in the s tr ing and not com piled. Later, a truntime, they are substituted into the string and passed asarguments to the FRENAME() funct ion. This precludes localand static macro variables since the names of the variables arenot present at run tim e to be substitu ted. Pub lic and priva te

variables , how ever, behave as you might expect . I f this seemssomewhat confusing, refer to the Variables section in this chapterfor mo re information about the difference between local andstatic variables, and private and public variables.

N o t e : Extend ed expressions are denoted in com ma nd syntaxwith metasymbols prefaced by a lowercase x.

2-70 CA-Clipper




Using with Lists

The macro operator (&) will not fully substitute or compile a list

as an argument of most commands, part icular ly thosecommands in which an argument l is t is preprocessed into anarray or a cod e bloc k. Instan ces of this are argu me nts of theFIELD S clause and SET IND EX. An exception is the SET C O LO Rcommand which preprocesses the list of colors into a singlecharacter s t r ing and passes i t to the SETCO LO R() funct ion.

In any case, l ist arguments should always be specified asextended ex pressions w ith each lis t argum ent specif ied:

LOCAL xcIndex := {"Ntxl", "Ntx2"}

SET INDEX TO (xcIndex[1]), (xcIndex[2])

Macros and Arrays

You can refer to arrays and array elements using both ma crovariables and macro expressions, with the restriction that thesubscript references cannot be made in a PRIVATE or PUBLICstatem ent. A furthe r restriction is that the m acro opera tor (& )cannot be specif ied in a LO CA L or STA TIC declarat ionstatem ent. Attem ptin g this gene rates a fatal com piler error.

For exam ple, valid references to array elements using ma crovariables includ e:

cName := "aArray"nElement s := 5cNameElement := "aArray[1]"

//Creates "aArray" with 5 elementsPRIVATE &cName.[nElements] // Creates aArray[5]&cNameE lement . := 100 // aArray[1] is now 100&cName.[3] := "abc" // aArray[3] is now "abc"





You can successfully apply a macro operator (&) to an arrayelement i f you use a ma cro expression. A macro variablereference, how ever, wil l generate a runt ime error. For exam ple,the following lists the values of all fields of the current record:

USE Customer NEWaStruc := OBSTRUC T()

FOR nField := 1 TO LEN(aSt ruc)? &(aStruc[nField, 1])

NEXT

N o t e : Because arrays are very pow erful in CA -Clipper, youmay not find the need to use the macro operator (&) to makevariab le references to arrays. W itho ut the aid of the macrooperator, you can assign array references to variables, returnarray references from functions, and nest array references withinother arrays. In add ition, arrays can be created by sp ecifyingliteral arrays or usin g the AR RA Y() function. For mo reinformation on arrays, refer to the Arrays section of this chapter.

M a c r o s a n d C o d e B lo c ks

The macro operator (&) can be applied to a macro variable orexp ression in a cod e block in m ost cases. The re is a restrictionwhen the macro variable or macro expression contains adeclared variable. You can not use a com plex expression (anexpression that contains an operator and one or mo re operands)that includ es the m acro o perato r within a code block. If this isat temp ted, a runt im e error occurs .

Note that this restriction has important implications on the use oflocal and static variables in the conditional clauses of commandssince these clauses are blockified as they are written to the resulttext w hen the comm and is preprocessed. This applies to al l FO Rand WHILE clauses, the SET FILTER command, and the SET

RE LA TIO N l inking expression. The general wo rkaroun d is togather the entire expression into a single macro variable thenapply the macro operator (&) to the variable.

2-72 CA-Clipper



The M acro Op era to r

U sin g w i th D a t a b a s e C o m m a n d C o n d i ti o n s

When using the macro operator (&) to specify condit ional

clauses of database commands such as FOR or WHILE clauses,there are some restr ict ions based on the expressio n 's com plexi tyand size as follows:

• The ma xim um str ing s ize the ma cro com piler can process is254 characters

• The re is a limit to the com plex ity of con dition s (the m orecom plex, the less the nu mb er of condit ions that can bespecified)

Invok ing Procedures and Func t ions

Procedure and funct ion cal ls can be referenced using macrovariables and expressions. With DO, the macro variablereference to the procedure can comprise all or part of thepro ced ure na m e. W ith a call to a func tion (built-in or user -defined) , the macro variable reference must include the funct ionname and al l of i ts arguments .

Instead of using the macro o perator to invoke a proce dure orfunct ion in this man ner, how ever, i t is mu ch cleaner and m oreeff icient to use a code block. For exam ple, if you ha ve c odesimilar to the following:

cProc := "AcctsRpt"

DO &cProc

You could easily replace it with code such as this:

bProc := &("{| | AcctsRpt()}")

EVAL(bProc)





The clear adva ntage of a code block in place of a mac roevaluation is that the compilation of a string containing a codeblock can be saved and, therefore, must be compiled only once,whereas macro evaluat ions have to be compiled each t ime they

are referenced.

External References

Procedures and funct ions used in macro expressions andvariables , but not referenced elsew here, must be d eclaredexternal using the RE QU ES T statement . Othe rwise, the linkerwill not include them in the executable file (.EXE).

Nes ted Macro Def in i t ions

The processing of macro variables and expressions inCA -Clipp er al lows nested macro defini t ions. For exam ple, afterassigning a macro variable to another macro variable, theoriginal macro v ariable can be expan ded, resul t ing in theexpansion of the second macro variable and evaluat ion of i tscontents . For exam ple:

cOne = "&cTwo"cTwo = "cThree"cThree = "hello"

? &c0ne // Resul t: "hello"

2-74 CA-Clipper



Arrays

Arrays

An array is a collection of related data items that share the samenam e. Each value in an array is referred to as an element . Arra yelements can be of any data type except memo, which is l imitedto fields. For exa m ple , the first elem ent can be a chara cter strin g,the second a nu m ber, the third a date , and so on. Arrays canalso contain other arrays and code blocks as e lemen ts .

Arrays are references. This mean s that a variable to wh ich anarray is assigned (or which is declared as an array) does notactually con tain the array . Inste ad, i t con tains a referenc e to thearray . In add ition, if a varia ble conta ining an array is pas sed a san argum ent to a proced ure or funct ion, a copy of the referenceis pas sed . Th e array itself is nev er du plica ted.

TYPE () and VALTY PE() re turn "A " for an a r ray. Because a r rayis a dis tinct data type in CA-C lipper, you can create com plexarray expressions.

Creating Arrays

Arrays can be specif ied with runt ime statements , such asPRIV ATE and PUBL IC, and wi th compi le - time dec lara t ionstatemen ts , such as LO CA L and STA TIC . The svntax forspecifying an array with any of these statements is either:

<identifier>[<nElementsl>, <nElements2>,. . .]

or:<identifier>[<nElementsl>] [<nElements2>].. .

Unlike other syntax representat ions, the square brackets are part

of the array definition and m ust be includ ed. Oth er than the firstd imens ion , <nElementsl>, all other dim ensi ons are op tional.

W ith the exception of stat ic array declarat ions, w hosedim ension s m ust be com pletely specif ied at comp ile t ime., arraysin CA-Clipper are dynamic, a l lowing the s ize to be completelydeterm ined at runt im e. Thu s, you can create an array w ho sedimensions are specif ied as expressions.

Prog ram ming a n d Utilit ies G uide 2-75



Arrays

For example:

LOCAL i := 12, j := 4LOCAL myArray[i, j]

Yo u can also use the AR RA Y() funct ion to create an array. W iththis funct ion, you sp ecify the dimensions as argu men ts , and thereturn va lue is an array referen ce. In fact, each of the arraydeclaration statements translates into two parts: the declarationof the array nam e and the subsequen t creat ion of an array andassignm ent of a reference. For exam ple, PUBL IC my Array [12] [4]is the same as:

PUBLIC myArra ymyArray := ARRAY( 12, 4)

Other funct ions that create arrays are DBSTRUCT() andDIRECTORY() .

Addressing Array Elements

After an array is created, i ts elements are accessed using aninteger index, commonly referred to as a subscript. To addre ss anarray element, place the subscript of the element in squarebrackets fol lowing the array nam e. For exam ple, suppo se thatmyArray is a one-d imen sional array with ten elements . Toaddress the f i rs t e lement , you w ould use:

myArray[1]

Note that subscript numbering begins with one.

To specify more than one subscript (that is, when usingmu lt idimen sional arrays) , you can ei ther enclose each subscriptin a separate set of square brackets, or separate the subscriptsw ith com m as and enclose the list in squa re brack ets. Forexam ple , if myArray is a two-d imen sional array, the followingstatements both address the second column element of the tenthrow:

myArray[10][2]myArray[10, 2]

2-76 CA-Clipper



Arrays

It is il legal to address an element outside of the boundaries of thearray. Atte mp ting to do so results in a run time e rror.

When making reference to an array element using a subscript ,you are actually applying the subscript operator ([]) to an arrayexpre ssion. An array exp ressio n, of cou rse, is any ex press ionthat evalu ates to an array. This include s function calls, variab lereferences, subscript ing operat ions, or any other expression thatevalu ates to an array. For exam ple, the follow ing are all valid :

{"a", "b'\ "c"}[2]x[2]ARRAY(3)[2]&(<macro expression>)[2](<complex expression>)[2]

Assigning Value s to Array Elements

When you create an array with one of the declaration statementsor with ARRAYQ, each element is set to NIL until the array isinitialized to some other value. Array initialization is theassignment of values to its elements with the assignment (=) orinline assignment operator (:=).

You can create an array and initialize it with a single function.The DBSTRUCT() function creates an array and initializes it withdatabase f i le s tructure information. Similarly, DIRECTORYQinitializes the array that it creates with disk directoryinform ation. You can assign these function results to variab leswhich can, in turn, be referenced as arrays.

It is also possible to initialize arrays at the time the y are crea tedusing declaration statem ents. To acco mp lish this, do not definethe array with dimensions in the declaration statement . Instead ,

just give it a na m e. After the array nam e, place an inlineassignment operator fol lowed by an expression that returns anarray. For exam ple, the follow ing statem ent creates a local arrayand initializes it with directory information:

LOCA L myA rra y := DIRECTORY(·•*.*», "D")




Arrays

The only limitation on this ability is with the STATIC statement,wh ich al lows only constants and simple expressions inassignments.

The AFILL() function initializes all the elements of an existingarray to a single value. For exam ple, the followin g e xam pleleaves you with a local numeric variable whose value is one:

LOCAL myArray[30]myAr ray := 1

The next example, on the other hand, assigns a value of one toeach element in my Array:

STATIC myArray[30]AFILL(myArray, 1)

Yo u can also use AF ILL () to initialize a range of elem ents. Forexample, the following lines of code initialize the first tenelements to one, the second ten elements to two, and the last tenelements to three:

AFILL(myArray, 1, 1, 10)AFILL(myArray, 2, 11, 10)AFILL(myArray, 3, 21, 10)

Array elements can also be initialized on an individual basis.For example:

myArray[1] := 1, myArray [2] := 2, myArra y[3] := 3myArray[4] = SQRT(4)

You can initialize array elements using any expression thatresults in a valid CA-Clipper data type, including code blocksand other arrays. On ce initialized, array elements can be used asvariables anywhere in the language that is appropriate for theirdata type.

2-78 CA-Clipper



Arrays

Multidimensional Arrays

In CA-Clipper, you can create a mult idimensional array bydeclar ing i t with more than one dimension parameter or byassigning an array to an existing array element.

You can create and maintain t radi t ional mult idimensional arraysthat have a f ixed nu mb er of eleme nts in each dimen sion. Forexample, a two-dimensional array is of ten used to represent therows and columns of a table .

To declare a two-dimensional array with ten rows and twocolumns, you might use the fol lowing:

PUBLIC myArray[10][2]

Usu ally, arrays that are created in this m anne r are expected toadhere to certain rules . For exam ple, each colum n contains thesame type of information for each row in the array (for example,column one might be a character s t r ing and column two anum ber) . Since CA -Clipp er does not enforce any rules on w hatcan be s tored in an array, you m ust im plem ent this level ofcontrol programmatical ly.

The fact that you can assign an array to an existing array elemental low s you to dyn am ical ly chan ge the s tructure of an array. Forexample, after an array is created, there is nothing to preventyou from doing something l ike this :

myArr ay[1] [2] := {1, 2, 3, 4, 5}

This ass ignment changes myArray significa ntly so it can nolonger be though t of as a two -dim ensiona l array in thetraditional sense because one of its elements is an arrayreference. In part icular, a reference to myArray[l][2][ l ] is nowvalid (it return s 1) w her e it w as not bef ore . Refe renc es to

myArray[ l ] [ l ] [ l ] and myArray[2] [2] [1] , however, resu l t inrunt ime errors .

This feature of assigning an array reference to an array e lem entis han dy in m any ap plicat ions. The thing to rem em ber is thatyou , as the programmer, must exercise whatever control youthink is necessary for s tor ing and ad dressing a rray elem ents .You cannot make any assumptions about the s tructure of anarray. You must enforce that s t ructure.




Arrays

Literal Arrays

Literal arrays, sometimes called constant arrays, can be createdat runtime using the fol lowing syntax:

{[<exp> [ <exp> . . . ]]}

For example:x := {1, 2, 3}γ := {"Hello", SQRT(x[2]), MyFunc(x)}

Creating an array like this is the same as declaring the array (forexample, with PUBLIC or LOCAL) then assigning the values toeach element individually. You can use li teral arrays any wh erean array can be spec ified, includ ing as literal array eleme nts. Forexample, to create a two-dimensional literal array, you could dothe following:

aTwoD := {{1, 2, 3} , {"a", "b" , "c "} , {.t., . t. , .f.}}

1 2 3

"a" "b" "c"

.t. .t. i .

If expressed as a character string, a literal array can be compiledwith the m acro operator. For examp le:

cArray := "{1 , 2, 3}aNew := &(cArray)? VALTYPE(aNew) // Returns: A

This is useful since you could not otherwise store arrays asdata base fields or as character va lues in text files. No te,how ever, that the ma cro com piler can process s trings up to 254characters in length only.

2 - 8 0 CA-Cl ipper



Arrays

Arrays as Function Argum ents a n d Return Va lues

Arrays can be passed as arguments to procedures and funct ions.When you specify an array as an argument to a routine, i t ispassed by value, as a default, if the routine is called using afunct ion-cal l ing convention . This mean s a copy of the referenceto the array is passed to a receiving parameter variable.Although a copy of the reference is passed, any changes made tothe referenced arrays are reflected in the original automatically.For example:

LOCAL myArray[10] // All elements set to NILAFILL(myArray, 0) // Elements initialized to 0MyFill(myArray) // Elements incremented by 1

? myArray[1] // Result: 1

FUNCTION MyFill(tempArray)FOR i = 1 TO LEN(tempArray)

tempArray[i]++NEXTRETURN NIL

When the funct ion MyFil l () executes , a copy of the reference tomyArray is pas sed to tempArray. W ithin My Fil l () the values inthe referenced array are incremented by one. When the funct ionreturns, the reference held by tempArray is discard ed, but thechanges to the referenced array appear after the call .

Arrays can be returned as values from funct ions. For exa m ple:

myArray := MakeArray (10, "New Value")

FUNCTION MakeArray(nElements, fillValue)LOCAL tempArray[nElements]AFILL(tempArray, fillValue)RETURN tempArray

Pro gram min g an d Utilit ies G uid e 2-81



Arrays

Traversing an Array

There are two ways to t raverse an array in CA-Clipper.

FOR...NEXT

The f i rs t and most easi ly und erstood traverse method is aFO R.. .NE XT lo op. This construct le ts you step through the arrayone element at a time using the array subscript of the currentdim ension as the control variable. In the fol lowing exam ple,each element in myArray is assign ed its array position as a valu e:

LOCAL myArray[10]FOR i := 1 TO 10

myArr ay[i] := iNEXT

To traverse a mult idimensional array, nest FOR.. .NEXTconstruc ts , one level for each dimensio n. The fol lowing exam pledisplays each element in a two-dimensional array:

FUNCTION ArrDisp(myArray)LOCAL i, j

FOR i := 1 TO LEN(myArray)FOR j := 1 TO LEN(myArray[1])

? myArray[i][j]

NEXT jNEXT iRETURN NIL

This method of array traversal is quite traditional and isprobably famil iar to you if have experience with a high-levellanguage such as C, Pascal , or BASIC.

AEVALO

The other method, AEVAL(), requires an understanding of codeblock s. This funct ion evalua tes a code block for each element ofan array, passing the elem ent value as a block para meter, andreturn s a referen ce to the array. For exam ple, the follow inginvocat ion of AEVAL() displays each element in a one-dimensional array:

AEVAL(myArray, {|element| QOUT(element)})

2 - 8 2 C A - C l i p p c



Arrays

For a mult idimensional array, you must specify nested AEVAL()funct ions to t raverse each dim ension. The following exam pleini t ia l izes and displays a two-dim ensional array:

LOCAL myArray [10][ 2], i := 1// Fill each element with row numberAEVAL(myArray, {|element| AFILL(element, i++)})// Display each elementAEVAL(myArray, {|element| AEVAL(element, ;

{ I value I QOUT(value)})})

Empty Arrays

An em pty array is an array with zero elements a nd, therefore, no

dim ensions. To create an empty array, declare an array withzero elements or assign an empty literal array to a variable.

For exam ple, the fol lowing statem ents are equivalent :

LOCAL aEmpty[0]LOCAL aEmpty := {}

You can use empty arrays whenever you do not know inadva nce wha t s ize array you wil l need . Later, you can ad delements to the array with AADD() or ASIZE() .

To test for an em pty array, use the EM PT Y() funct ion. Forexample :

FUNCTION ZeroArray(entity)IF VALTYP E(enti ty) = "A" .AND. EMPTY(entity)

RETURN .T.END IFRETURN .F.

You cannot, on the other hand, test for an empty array bycom paring i t to NIL . This comp arison alw ays evaluates to false




Arrays

Determining the Size of an Array

You can determine the number of elements in an array using theLEN () function. This returns the nu m ber of elem ent slots in the

array , or the last elem ent position in the array. The follow ingcode fragment demonstrates:

LOCAL myArray[10][12]? nArraySize := LEN (myArray) /./ Re tu rn s: 10

Note that this example returns the number of elements in thefirst dimension of myArray. Rem em ber that CA-C lipper createsmu lt idimension al arrays by nest ing subarrays within acon taining array . LE N() returns the nu m ber of elemen ts in thespecified containing array.

To determ ine the num ber of elements in a subarray, you app lyLEN() to the first element in the containing array:

? nNestedS ize := LEN(myArr ay[1]) // Retur ns: 12

Note that LEN() returns zero for an empty array.

N o t e : W hen there is not enough m emo ry to hold the s tructureyou are creat ing, you wil l receive the error messag e "UE 332 :Str i ng /A rra y mem ory overf low ." In this case, you need to

create a sm aller structure for the array. For more inform ation see"CA-Clipper Technical Specif icat ions" appendix in the ErrorMessages And Appendices Guide.

Comparing Arrays

The == operator compares two arrays for equivalence. Array s areequivalent if they are references to the same array (that is, theypoint to the same locat ion in m em ory). For examp le:

LOCAL myArray 3}sameArr := myArray

? sameArr = = myArraynewArr := ACLONE( myArray)? newArr == myArray

// Create a new reference// to myArray// Result: .T.// Create a new array// Result: .F.

Note that the = operator is not valid for comparing arrays.

2-84 CA-Clipper



Arrays

There is no s ingle operator that can check w hether al l e lem entsare the same in two dist inct arrays. To accom plish this , youmust t raverse the arrays and compare them element by element .

The fol lowing funct ion accomplishes this for one-dimensionalarrays:

FUNCTION ArrComp(aOne, aTwo)IF LEN(aOne) <> LEN(aTwo) / / Sizes are different

RETURN .F.END IFFOR i := 1 TO LEN(aOne)

IF (aOne[i] <> aTwo[i]]> II

t least oneRETURN .F.

IIelement is

END IFII

differentNEXTRETURN .T.

IISizes and elements

IIare identical

Ch ang ing the Size of a n A rray

There are two funct ions, ASIZE() and AADD(), that change thesize of an existing array. AS IZE () specifies the array to ch an geand the new size as funct ion argum ents . W ith this funct ion, yo ucan mak e an exist ing array ei ther larger or smaller. For exa mp le:

LOCAL myArray[10]ASIZE (myArr ay, 25) // Increase by 15 elements? LEN(myArray) // Returns : 2 5ASIZE(myArray, 5) // Decrease by 2 0 elements? LEN(myArray) // Returns: 5

When you enlarge an array, the new elements are added to theend of the array and are set to N IL. Shrin king an array (that is,making i t smaller) removes elements beyond the specif ied newarray s ize. ASIZ E() upda tes the array and returns a reference toit.

AADD() enlarges an array by one element and ini t ia l izes the

new elem ent to a part icular value. The new elem ent is add ed tothe end of the array. For exam ple:

LOCAL myArray[10]AADD(myArray, 500) // Add one element? LEN(myArray) // Returns : 11? myArray[11] // Returns : 500




Arrays

Inserting and Deleting Array Elements

The AINS() function inserts an element into an existing array at aspecif ied locat ion, pushin g al l subsequent elements dow n onepos ition. Th e last elem ent in the array is lost.

ADEL() deletes an element at a specified location, and allsubsequ ent elements are mo ved up one posi tion. The laste lement becom es N IL.

Both ADEL() and AINS() update the original array and return areference to it . Unlike A AD D() a nd ASIZE () , these funct ions donot change the size of the array.

Copying Elements and Duplicating Arrays

AC OP Y() copies elements from one array to another. The targetarray mu st exist prio r to invo king the function . W ith thisfunction, you can copy all elements or a particular range ofelem ents. If the source array contain s nested array s, the targetarray will contain only references to the subarrays, not actualcop ies. AC O PY () returns a referen ce to the target array.

For mult idimensional or nested arrays, use ACLONE() i f youw ant to duplica te the entire array. If the source array contains asubarray , ACL ON E() creates a matching sub array and f i lls i twith copies of the values in the original subarray, as opposed tocop ying a referen ce. This functio n creates the target array andreturns a reference to it .

2-86 CA-Clipper



Arrays

The fol lowing example i l lustrates the difference between thesetwo funct ions:

LOCAL aOne[4], aTwo[14]aOne[l ] := {1, 2, 3}ACOPY(aOne, aTwo) //

/ /? aOne[l] == aTwo[1] //aThree := ACLONE (aOne) //

/ /? aOne[l] == aThree[1] //

Copies elements fromaOne to aTwoReturns: .T.Duplicate aOne inits entiretyReturns: .F.

The first element in aOne is an array. Thus, af ter ACOPY() isinvoked to copy elements to aTwo, the first elements in thesearrays are equivalent (that is, are references to the samesubarray) . AC LO NE () c rea tes aThree as a duplicate, and theequivalence test fai ls because the subarrays being compared arenot the same. I f, how ever, aThree [ l ] and aO ne [ l ] w erecompared on an element by element basis , a l l e lements would bethe same.

Sorting an Array

The ASORTQ funct ion sorts an array and returns a reference tothe new ly sorted array. W ith this fun ction , you can sort an entirearray or a specified port ion. This exam ple sorts the ent ire array:ASORT(myArray)

This example sorts elements ten through f i f teen, leaving al l otherelements in their original place:

ASORT(myArray, 10, 5)

An addit ional feature of ASORT() lets you specify the sortcr i ter ia as a code block. For exam ple, the fol lowing stateme ntdoes a descen ding sort of an ent ire array:

ASORT(myArray,, , {|x , y| χ < y})




Arrays

Searching an Array

ASCAN() searches an array for a particular value specified as anexpression or a cod e block . This function operates on the entirearray or a specif ied ran ge of e lements . If used with a s implesearch expression, the funct ion searches the array until it finds amatching va lue an d re turns the subscript , or zero if the valuew as no t found. For exam ple :

LOCAL aArray := {"Tom", "Mary", "Sue", "Mary"}? ASCAN(a Array, "Mary") // Result: 2? ASCAN(aArray, "mary") // Result: 0

If the search criteria is specified as a code block, the funct ion ismuch more powerfu l . In the examp le above , the second

ASCAN () cou ld no t find the nam e because the search wa s case-sensi t ive. Th e fol lowing ex am ple uses a code block to perform asearch that is not case-sensitive:

? ASCAN(aArray, {|x| UPPER(x) == "MARY"})// Result: 2

Since the func tion lets yo u specify a range of subscripts toinclude in the search, it can r e sume the search w ith the nexte lement as in the fol lowing exam ple:

LOCAL myArray := {"Tom", "Mary", "Sue", "Mary"}LOCAL nStart := 1nEnd := LEN(myArray) // Set boundary conditionDO WHI LE (nPos := ASCAN(myArray,"Mary",nStart)) > 0

? nPos, myArray[nPos]// Test boundary conditionIF (nStart := ++nPos) > nEnd

EXITENDIF

ENDDO

2-88 CA-Clipper



Code Blocks

Code Blocks

Cod e blocks provide a mean s of export ing small pieces ofexecutable program code from one place in a system to another.You can think of them as assignable unnamed functions. The y areassignable because, except when executing them, CA-Clippertreats them as values. Tha t is, they can be stored in varia bles,passed as arguments, and so forth.

Cod e blocks bear a s trong resemb lance to ma cros, but with asignificant difference. Macros are character strings which arecompi led on the fly at runtime and imm ediately executed. Co deblocks, on the other hand , are comp iled at com pile t ime alon gwith the rest of the pro gra m . For this reason cod e block s aremore efficient than macros, while offering similar flexibility.

The difference between code blocks and macros becomesespecial ly importan t with declared variables. Variabledeclarations act at compile time and, thus, have no effect withinruntime ma cros. Since code blocks are com piled at com pile t ime ,declarations can be used to control access to variables in codeblocks. Variables that require compile-time declarations (staticand local variables, and declared para meters ) are never visible

within runtime m acros, wherea s they can be accessed freely inblocks.

Defining α C o de Block

The syntax of a code block is as follows:

{ I [ r g u m n t l ist>] \ <exp list>}

Both <argument Hst> and <exp list> are comm a-separa ted . The

expressions must be val id CA-Clipper expressions—they cannotcontain commands or s tatements , such as control s tructures anddeclarat ions.

N o t e : The vertical bar s that delim it a code block argu m ent listmust be present, even if there are no arguments, to distinguish acode block from a literal array.

Prog ram ming a n d Utilities G uid e 2-89



Code Blocks

Some examples of code blocks fol low:

I "just a string"}{ Ρ I ρ + 1}{ χ, y| SQRT(x) + SQRT(y)}

{ a, b, c| MyFunc(a) , MyFunc(b) , MyFunc(c)}

Executing α C o d e Block

The EVA L() funct ion executes a code block. EV AL () takes ablock as i ts f i rst argum ent , fol low ed by a lis t of param eters . Thefunct ion then executes the code block, passing the specif iedparameters as arguments . The expressions are evaluated inorde r from left to right. The retu rne d value is the result of thelast (or only) exp ressio n in the list. For exam ple :

bBlock := {|nValue| nValue + 1}? EVAL(bBlock, 1) // Result: 2

The AE VA L() and D BEV AL () func t ions al so execute code b locks .These are i terator funct ions that process an array and a da tabasefile, respect ively, executing a code block for each element orrecord.

Sco pe of Variables Within a C o d e Block

When a code block is executed, local and stat ic variablereferences (other than arguments) are scoped to the procedure orfunct ion in w hich the code block wa s defined. A local variablereferenced in a code block is stil l visible after the declaringfunction is no longer active, as long as there is an active referenceto the code block. For exam ple:

bBlock := MyFunc()FOR i := 1 TO 10

? EVAL(bBlock)NEXTRETURN

FUNCTION MyFunc()LOCAL nNumberLOCAL bBlocknNumber := 10bBlock := { | I nNumber++}RETURN bBlock

2-90 CA-Clipper



Code Blocks

In this example, each t ime the code block returned by MyFunc()is evalu ated, i t increm ents nNumber and returns the new va lue.

nNumber is accessible through the code block as the funct iondefining the code block 's act ivat ion record becomes detachedfrom the act ivat ion s tack w hen the funct ion returns. Thefunct ion 's local variables then beco m e, in essence, a free-f loat ingarray. The detached act ivat ion l ives in object m em ory and staysalive as long as any of the blocks referring to it are alive.

This facility has significant ramifications for the capabilit ies of acode block. In part icular, it solves the pro blem in wh ich a co deblock instance needs long term own ership of som e values . I t

means that you must macro-compile a code block only i f theactual code to be executed is not known unti l runt ime.

No te also that every call to the funct ion g enerates uniq ueinstances of the local variables . Tho se variables continue to existas long as there is a code block that refers to them.

Using this fact, along with the fact that a code block can bepassed as a parameter to another program, you can export s tat icand local variables . For example:

FUNCTION One()LOCAL myVarmyVar := 10bBlock := { I number I number + myVar}

NextFunc(bBlock)

RETURN NIL

FUNCTION NextFunc(bBlock)RETURN EVAL(bBlock, 200)

W h e n bBlock i s eva lua ted in Nex tFunc() , myVar, w hich is loca l to

funct ion O ne() , beco m es vis ible even thoug h i t is not p asseddirect ly as a parameter.

Note that if the specified variable is a private or public, thevariable is not exported from the defining rout ine. The current lyvisible copy of the variable is used instead.




Code Blocks

Using Code Blocks

Code blocks are part icularly useful when creat ing black boxfunct ions which can operate without knowing what type ofinformation is passed to them. Consider the following:

FUNCTION SayData(dataPassed)// Display dataPassed as a stringDO CASECASE VALTYPE(dataPassed ) = "C" // Character

@ 10,10 SAY dataPassedCASE VALTYPE(dataPassed) = "N" // Numeric

@ 10,10 SAY LTRIM(STR(dataPassed))CASE VALTYPE(dataPassed) = "L" // Logical

@ 10,10 SAY IF(dataPassed, "True", "False")ENDCASERETURN .Τ.

In this example, an error occurs if data of any type other thanthose spec ified is pas sed to Say Da ta(). If, for exa m ple, a dateneeds to be displayed, SayData() must be modif ied.

In the following example, the code to be executed is stored in ablock:

charCode := ί data data}numCode := ( data LTRIM(STR(data) ) }logCode := { data IF(data, "True", "False")}dateCode := { data DTOC(data)}

SayD ata() can now be d efined as a black box routine which canact on any type of data. Th e decision of wh ich block to pass toSayD ata() is mad e in the call ing prog ram :

FUNCTION SayData(dataPassed, codeBlock)// Display dataPassed as a string@ 10,10 SAY EVAL(codeBlock, dataPassed)RETURN .T.

Code blocks are also used to pass an expression to a function orprocedure that you do not want to execute until sometime later.

A goo d exam ple of this can be found in STD.CH with thedef in i t ions of the SET KEY and SET FUN CTIO N comm ands .Both commands translate into a call to the same function,although the operation performed is not the same in both cases:SET KEY assigns the name of a procedure or function to callwhen the specif ied key is pressed, while SET FUNCTIONassigns a string to stuff into the keyboard buffer.

2-92 CA-Clipper



Code Blocks

Evaluation of Macros in Code Blocks

W hen a code block contains a macro, an ambiguity ar ises

regarding when the macro is evaluated. There are twopossibilit ies, early or late evaluation.

Early Evaluation Early evaluat ion mea ns that the ma cro is expa nded at the t imethe code block is created, and the expanded value remainsconstant for al l subsequ ent evaluat ions of the block. CA -Clip peruses early evaluat ion by d efaul t , with an al ternate m ethodavailable for late evaluation.

As an example of ear ly evaluat ion, consider a SET FILTER

command in which the f i l ter expression is a macro:SET FILTER TO &cFilter

A fi l ter expression, specif ied by a SET FILTER command, isexecuted each t ime a SKIP command is issued. The macro s tr ingcontained in cFilter above , how ever, should be expanded onlyonce, wh en the com m and is fi rst issued. Othe rwise , i f the ma crois expa nded each t ime the f i lter block is evaluated , the m acrovariable (cFilter above) m ust be preserved for the durat ion of thefilter.

In CA-C l ipper, the SET FILTER com ma nd i s implem ented by u seof a code block. The code for the above com m and , af terpreprocessing, is similar to the following:

DBFILTER({| | &cFilter})

Early evaluation of the macro within the code block results in thedesired behavior: cFilter is evaluated w hen the block is defined(as part of the creation o f the block ). Th e bloc k is created via themacro system and remains constant through al l subsequentblock eva luat ions, regardless of any chang e to the value ofcFilter.




Code Blocks

Late Evaluation Late evaluat ion me ans that the ma cro is evaluated each t ime theblock is evaluated.

As an exam ple of a s i tuat ion w here late evaluat ion is required,

consider a block which must perform a macro operat ion on oneof i ts own parameters .

The following block attempts to assign a value to a variable byuse of a macro:

bAssignByName := {|vName, value| &vName := value}

Because CA-Clipper implements early evaluat ion, this codeblock w ou ld not have the desired effect : instead of evaluat ing themacro each t ime the block is run, CA-Clipper would evaluate the

ma cro w hen the block was f i rs t created. The ini t ia l value ofvName would become part of the block.

Late evaluat ion is avai lable by using a ma cro expression. Theabove code block wil l funct ion correct ly i f defined as fol lows:

bAssignByName := {|vName, val ue| &(vName) := value}

The use of a ma cro expression ( the macro operator applied to anexpression in parenthe ses) prevents the early evaluat ion fromtaking place, and the code block w il l evaluate the macro s tr ing

contained in vName during each block evaluat ion.

2-94 CA-Clipper



Code Blocks

Storing an d C om piling C o d e Blocks at Runtime

Although you cannot s tore code blocks direct ly to database f ields

or (.mem ) files, you can store them as char acter strings. W he nyou w ant to use a code block defini t ion s tored as a characterstring in a database field, compile the field using the macroope rator then assign the resulting cod e blo ck to a variab le. Forexample :

USE DataDict NEW

// Create a block string and assign it to a fieldvariableAPPEND BLANKREPLACE BlockField WITH { | | Validate()}"

// Later compile and execute the blockbSomeBl ock := &(Block Field)EVAL(bSomeBlock)

Instead of s toring the com piled co de block to a variable andevaluat ing i t , you cou ld com pile and eva luate in a s ingle s tepwi th EVAL(&(BlockFie ld) ) .

There is , however, a speed advantage to s tor ing the compiled

code block to a variable, since the compile step only has to beperformed once. Once compiled, the variable can be passedthroughout the system and evaluated at the same speed as otherCA-Cl ipper-compi led code .

N o t e : The ma cro operator is appro priate only for use withcharacter expressions. Th us, you canno t com pile a code blockdirect ly with the macro operator.




Objects and Messages

Ob jec t s a n d M essages

CA -Clipp er offers a l imited imp lemen tat ion of a special datatype cal led object. The con cep t of an object is part of theobjec t-or ien ted programm ing paradigm.

CA-Clipper objects are complex data values which have apredefin ed structure and set of behav iors . A small num ber ofpredefined object types, called classes, are part of the system.These classes support part icular operat ions in CA-Clipper.Creating new classes and subclassing of existing classes are notpossible in CA-Clipper.

N o t e : CA -Clipp er is not an object-oriented languag e. The

CA-Clipper implementat ion of objects represents only a smallsubset of the object-oriented parad igm .

Classes

In CA -Cl ipp er, there are several different types of objects. Anobject 's type is known as its class. The information contained inan object, and the operations that can be applied to it , varydepending on the class of the object.

For each available class, there exists a special function called acreate function. Th e create fun ction facilitates the creation of newobjects of the associated class.

2-96 CA-Clipper




Instances

You create a new object with a call to the create function for a

particular class. The object will have the attributes andbehav iors specif ied in the descript ion of the class . The n ewobject is known as an instance of the class.

Like CA-C lipper arrays, objects are han dled referent ial ly. Thismeans that a program variable cannot actual ly contain an object .It can, ho w eve r, con tain a referen ce to an object. Th e varia ble isthen said to refer to the object , and operat ion s are perform ed onthe object by applying the send operator (:) to the variable.Object references can be freely assigned, passed as parameters ,

and returned from funct ions. Tw o or m ore variables can containa reference to the same object (if , for example, a variablecon tainin g an object referen ce is assig ned to ano ther var iabl e). Inthis case, both variables refer to the object, and operations areperform ed on the object by app lying the send operator to ei thervariable.

Objects continue to live as long as there are active references tothem som ew here in the system . W hen al l references to an ob jectare el iminated, the system automatical ly reclaims the spaceoccupied by the object .

When you create a new object , the create funct ion returns areferen ce to the new object. Yo u can then assign this refere nce toa variable, and access the object through that variable.





Instance Variables

An object contains within it all of the information necessary for itto perform the operations specified for its class. This information

is stored inside the object in special storage locations calledinstance variables.

When you create a new object, i t receives its own dedicated set ofinstance variables . The new instance variables are autom atical lyassigned initial values.

M ost instance variables are invisible to the program me r.H ow ever, som e instance variables are accessible . These areknown a s exported instance variables . Expo rted instance

variables can be inspected a nd, in some cases, assigned using thesend operator (:) .

Sending Messages

Each class defines a set of operat ions that can be perform ed onobjects of that c lass . These op erat ions are perform ed by sending amessage to the object using the send op erator (:) .

The syntax for sending a message to an object is as follows:<object> : <message> [ (<parameter list>) ]

For example:

oGetrleft()

In this example, oGet is the name of a variable that contains anobject referen ce. left() is the mes sag e bein g sent; i t specifies theoperat ion to be perform ed. The avai lable operat ions (andcorresponding messages) vary depending on the class of the

object.

2-98 CA-Clipper




Parentheses are optional if no parameters are supplied in themessa ge send. By convention, howev er, parentheses are used todist inguish a mess age send w ith no parameters from an access to

an exported instance variable.

Executing a message send produces a return value, much l ike afunction call . The return value varies depending on theope ration perfo rm ed. Of ten, this return value is a reference tothe object that was just operated on (referred to as self). Thisallows multiple messages to be sent in a chain:

oGetrleft():right()

Accessing Exported Instance VariablesSome classes allow access to the instance variables within objectsof that class. These variables are called exported instance variables.The definition for a class specifies which, if any, instancevariables are exported . Som e exported instance variables aresaid to be assignable. An assignable instance variable can bemo dif ied using a special variant of the message send operator.

You access exported instance variables using a variant of thenorm al messag e sending syntax. The syntax for retr ieving thevalue of an instance variable is:

<object>:<instance variable>

The syntax for assigning a new valu e to an assignable e xpo rtedinstance variable is:

<object>-.<instance variable> := <value>

For example:nRow := oBrowse:rowPos

oBrowse:c argo := xNewCar go

Conceptually, i t is easiest to consider an instance variablereference (of the form <object>:<instance variable>) as if it is asingle variable—both are valid in all of the same contexts.Instance variables , however, are much more powerful thanvaria bles. Internally , assig nm ents and retrievals to instance aremapped to methods, which can enforce val idat ion rules andperform other act ions.




The Database System

For example, in the Error class, assigning a value to theErrorrgenCode instance variable sets the Erron descript ioninstance variable to the default description for that type of error.This helps ensure consistency in the messages the user receives

when errors occur.

Th ou gh this is useful, there is still a need to act up on the datastored in the object, independently of setting instance variables.This is accomplished by sending messages to the object to invokethe desired methods.

The D ata ba se System

The CA-Clipper database system is composed of work areas thatare used to manage database and other related files, andoperations designed to manipulate those files. A database file isa collection of related information that is stored in the form of atable. Th e design of the table, kno w n as the structure, is alsostored in the database file.

The structure is defined and added to the database file when thefile is created . It consists of one or mo re field definitionsdescribing the name, width, and data type attributes for eachcolu m n in the table. The table row s, or record s, are add ed to thefi le using ap pend operat ions wh ich understand and enforce thestructu re on a field by field basi s. Reco rds are added to adatabase file in a particular physical order that is used, bydefault, when accessing the file.

An index file is an ancillary file that is created separately fromthe databa se file. It lets you d efine and ma intain a logicalordering for a database file without affecting the physical fileorder.

Several database files that have related structures and data canbe associated, along with their index files, using the SETREL AT ION com man d. SET REL ATIO N le ts you es tab l ishrelationships between several files and operate on them as asingle entity known as a database, or view.

2-100 CA-Clipper



The Database System

The CA-Clipper package contains a database ut i l i ty, DBU.EXE,that le ts you perform most database and index operat ions usinga me nu -driv en system . It is an excellen t tool for design ing

database file structures for your applications and for enteringtest data . Refer to the "Database Uti l i ty—DBU.EXE" chapter inthe Programm ing and Utilities Guide for further informationregard ing DBU.

This section describes the various facets of the database systemand gives a br ief overview of all database and index operat ion s.

Work Areas

The CA-Clipper database system defines 255 work areas. 250 ofthem are available for your use; with the remaining five reservedfor internal use. A work area is essentially an area in m em or y inwhich you can manage a s ingle database f i le along with anoptional memo file and up to 15 index files. A work area isoccupied or unoccupied, depen ding on wh ether or not i t containsan open file. At application startup all work areas areunoccupied, and work area number one is the current, or active,,work area.

Access ing Work Areas

To open a database file, you must first access the work area youwa nt to use. The most com mo n way to do this is with theSELE CT com ma nd. SEL ECT is des igned spec i fica lly to mo vebetween work areas by changing the current work area to theone you specify.

The general usage rules for SELECT are:

• To access a specif ic uno ccup ied wo rk area, specify SEL EC Twith a number between one and 250

• To access the next avai lable uno ccup ied wo rk area, useSELECT 0

• To access an occ up ied w ork area (that is, an area in w hichthe database f i le is in USE) , specify SEL EC T w ith the al iasname rather than the work area number




The Database System

In CA-Clipper, the USE command supports a NEW clause thatSELECTS the next unoccupied work area before performing theopen operat ion. This feature ma kes the SEL EC T 0 commandobsolete, so that any code of the form:

SELECT 0USE <xcDatabase>

can be replaced with:

USE <xcDatabase> NEW

After a USE , the selected work area remains act ive.

If no ALIAS clause is specified, as in the above example, thework area in which the database file is opened is assigned an

alias na m e that is the same as the data base filenam e. This na m eis used w ith SEL EC T to access the work area.

Aliased Expressions Aliased expressions are used to tempo rari ly access a wo rk areafor the purp ose of expression evalu at ion. To form an al iasedexpression, enclose the expression in parentheses and prefix itwith the desired alias name and the operator (->) (for example,<id Al ias >-> (<e xp >)) . The wo rk area is selected, the expressionevaluated, and finally the original work area restored.

You can also evaluate s imple database funct ions and morecom plicated expressions in unselected wo rk areas this wa y. Forexample :

• Cu st-> (EO F() ) evalu ates the end of file status in the Custwork area.

• Cus t -> (HEA DER () + (LA STR EQ ) * RECSIZEQ)) compu te sthe size of the file in the Cust work area.

• Cu st->A m ou nt + total adds the value of the Amount field inthe Cust work area to the variable total.

2-102 CA-Clipper



The Data bas e System

No tice that in the f inal exam ple ab ove, Amount is referen cedexplicitly with its alias name, no parentheses are used within theactua l aliased express ion. This explicit field referen ce avo ids any

ambiguity that may exist among f ield and variable names andillustrates the following point: using an aliased expression doesnot overr ide any compiler assumptions about variables withinthe expression, whereas using an alias as an explicit fieldreference does.

In other words, the compiler does not assume that everythingwithin an expression refers to a field simply because theexpression is preceded b y an alias . Instead, the s tandardprecedence rules resolve ambiguit ies when the expression is

evaluated at runt im e. You can, howe ver, expl ici t ly reference af ield with an al ias , thereby removing any ambiguity that mightexist at compile time.

To i l lustrate , suppose you have the fol lowing code that uses alocal variable amount and a field called Amount in the Cust w orkarea. This al iased expression accesses the local variable n am edamount becau se whe n the expression is evalua ted, the variable isvis ible and takes precedence over the f ield with the same name:

LOCA L total := 0, amount := 0total := Cust-> (Amount + total)

Essential ly, evaluat ing Cust->(Amount + total) is the same asselect ing the Cust work area, and evaluat ing the expressionAmount + total .

Changing this line of code as follows accesses the field Amountrather than the local variable. The reference to Am ou nt u singthe Cust alias is an explicit field reference, which overrides thelocal variable of the same name:

total := Cust->A mount + total

As a good programming pract ice, you should make al l ident if ierreferences explici t and avoid naming confl icts wheneverpossible . Otherwise, you may not agree with decisions made bythe compiler to resolve ambiguit ies .




The Da taba se System

Work Area At t r ibutes

A wo rk area provides a mean s for logical ly group ing at t r ibutespertaining to a database file. These are called work area

attributes and are listed in the table below:

C o m m a n d / F u n c t i o n Attribute

S E T D E L E T E D Delete record filter

SET FILTER Logical record filter

ALIAS O Databa se al ias nam e

BOF() Beginning of file flag

DBFILTER() SET FILTER condit ion

D B R E L AT I O N ( ) , SET RELATION informat ionDBRSELECTO

EOF() End of file flag

F C O U N T ( ) Number of f ie lds

F O U N D ( ) Search flag

FLOCK() , RLOCK() Lock status flags

INDEXKEYO Index key expression

I N D E X O R D O SET ORDER value

LO CA TE, CO NT INU E LOC ATE cond it ion

LASTREC() Number of records

R E C N O ( ) Record number

SELECTQ Work area number

2-104 CA-Clipper



The Database System

Database Files

The database file is the main file type and has a default extensionof (.dbf). A datab ase file, often called a table, consists of onevariable length header record that defines the structure in termsof its field definitions, and zero or more fixed length records thatcontain actual data for nonmemo fields and pointer informationfor m em o f ields. Each record has one addit ional byte for therecord delete s tatus flag. The CA -Clipp er databa se f ile form at iscompatible with dBASE III PLUS.

Database files can be thought of as tables, where each field in thestructure represents a colum n of the table and each record

represents a row.

M e m o F ile s

If a database file structure has definitions for one or more memofields, there is one memo file associated with that database file.The memo f i le has a defaul t extension of (.dbt) and the sam e roo tfilename as the associated database file.

By defaul t , the databa se and m em o f i les are created andmaintained in the same directory.

The data for all memo fields is stored in the same memo file, nomatter how many memo f ields are defined in the database f i lestructu re. Each m em o field in the data base file contain s apointer into the memo file, so the database system can quicklylocate the associated data.

The memo f i le is automatical ly opened and maintained in thesam e wor k area as the databa se f i le .




The Database System

Database Fi le At t r ibutes

Like work areas, database files have associated attributes aslisted in this table:

Funct ion Att r ibute

DELETED() Record delete status flag

FIELD() Field name

H E A D E R ( ) He ader s ize in bytes

L U P D AT E ( ) Date of last upda te

RECSIZEQ Record size in bytes

D a t a b a s e O p e r a t i o n s

There are several operations (database operations) that can beperformed on an open database f i le .

The following table categorizes all of the database operations.Note that all of these operations require an open database file inthe current ly selected work area:

C a t e g o r y C o m m a n d / F u n c t i o n

Add A P P E N D B L A N K , A P P E N D F R O M ,BROWSE()

Close CLOSE, USE

Compute AV E R A G E , C O U N T, S U M

Create C O P Y S T R U C T U R E , C O P Y S T R U C T U R EE X T E N D E D , C O P Y TO , C R E AT E , C R E AT EFRO M, JOIN, SORT, TO TAL

Delete DELETE, PACK, RECALL, ZAP

Disp lay DISPLAY , LABE L FOR M, LIST, REPO RTisplayFORM, BROWSEQ, DBEDIT( )

Continued

2-106 CA-Clipper



The Database System

Continued

C a t e g o r y C o m m a n d / F u n c t i o n

Filter INDEX. . .UNIQUE, SET DELETED, SETFILTER

Information AFIELDS()

Iterate DBEVAL()

Lock SET EXCLUSIVE, UNLOCK, FLOCK() ,RLOCK()

Naviga te C O N T I N U E , F IN D , G O , L O C A T E , S E E K ,SKIP

Open USE

Order INDEX , REIND EX, SET IND EX, SETO R D E R , S O RT

Rela te SET RELA TION

Upda te ©...GET < i d F i e l d > / R E A D , R E P L A C E ,UPDATE, BROWSE() , DBEDITQ

R e c o r d S c o p i n g

Many database operat ions can process subsets of records withina wo rk area using scope and condit iona l clauses. For anydatabase comm and tha t a llows a <scope> as part of its syn tax, thesyntax of the <scope> is as follo ws :

[ALL I NEXT <nCount> | RECORD <nRecord> | REST]

• AL L processe s al l records

• N EX T processes the current record and the specif ied nu m berof records

• RE CO RD proce sses the specif ied record• RE ST processes all records from the current record to the

end of file




The Database System

Commands specif ied without a scope defaul t to the currentrecord (NEXT 1) or ALL records, depending on the command.For example , DELE TE and R EPL AC E typica lly process thecurrent record by i tself and, therefore, defaul t to NE XT 1. Other

commands , such as REPORT and LABEL FORM, typica l lyprocess a set of records and, therefore, default to ALL records.Specifying a scope changes this defaul t by indicat ing how manyrecords to process and where to begin.

The set of records processed can also be restricted using acondit iona l clause w hich specif ies a subset of records based on alogical condit ion. The two condit ional clauses are FO R andW H I L E .

A FO R clause defines a condit ion that each record within thescop e mu st m eet in orde r to be proc essed . If no other scope isspecif ied, FOR changes the defaul t scope to ALL records.

A WHILE clause defines another condit ion that each recordprocessed m ust m eet; as soon as a record is encountered thatcauses the condit ion to fai l , the com m and terminates . I f no o therscope is specif ied, WHILE changes the defaul t scope to REST.

Specifying a scope, a FOR clause, and a WHILE clause within thesame command syntax can raise quest ions regarding the order inw hic h the clau ses are pro cesse d. The scope is evalu ated first inorder to posi t ion the record pointer. The n, the W H ILE clause isevaluated and, if the condition is not met, the process terminates.If the WH ILE c ondit ion is met , the FO R clause is evaluated. I fthe FOR cond it ion is a lso met , the record is processed ; otherw ise,it is not. Either w ay , the record poin ter is m ov ed to the nextrecord within the scope until the scope is exhausted.

2-108 CA-Clipper



The Database System

The Reco rd Process ing Pr imitive—DBEVALO

The i terate operat ion, DB EV AL (), is relatively new and ,

there fore, dese rves further explan ation. This function is thedatabase primit ive in STD.CH that defines database commandsthat allow record scoping, and it is sometimes called the recordprocessing primit ive.

DBEVAL() evaluates a code block for each record matching thespecif ied scope and condit ions. I t creates user-defined databas eprocess ing commands . The DBEVAL() en t ry in the "LanguageReference" chapter of the Reference Guide has more informationand exam ples. For addit ional information on code blocks, see

the Code Blocks section earlier in this chapter.

Index Files

Database files are maintained and processed in a particularphysical order identical to the order in which records are addedto the fi le . Each record is num bere d sequential ly beginning withone , and the number of the current record can be accessed withthe REC NO Q function. Indexing prov ides a me ans for logicallyord ering the databa se file acco rdin g to the data it con tains. InCA-Clipper, you can index by creating index files in a work areawith a database file.

N o t e : Altho ugh the default me thod for creat ing andmaintaining index f i les is unique and incomp atible with othe rdialects , CA-Clipper supplies several Replaceable DatabaseDrivers (RDD s) for using various index f ile formats . Som e R D Dssupport multiple orders per index file, while others, l ike thedefau lt R D D , supp ort only a single order per inde x file. Thissect ion applies specif ical ly to the default RD D, DBF NT X, but c anbe general ized to other RDD s. Refer to the Drivers Guide formo re specific information abou t a part icular RD D.




The Database System

C r e a t i n g

You create index files for the database file in the current workarea with the INDEX command in which you specify an order

key expression. The ma xim um length of the key expression is250 characters, and its type can be character, date, or numeric.

You determine the index key value for each record in thedata base file using the inde x key expre ssion. This expression isstored in the index file in such a way that the database file can beprocessed in order according to the key values which can besearched very quickly.

The UN IQU E c lause of the IND EX com man d and the SET

UNIQUE ON flag create an index file in which only the firstoccurrence of any given key value is maintained in the index file.Uniqueness is an attribute that is stored in the index file.

O p e n i n g

You can create several index files for a single database file so thedata can be accessed in ma ny different way s. On ce the necessaryindex files are created, you must open them along with theassociated database file in order to use them. You can open upto 15 index files at the same time with the INDEX clause of theUSE command or wi th SET INDEX.

Like all other database file opening operations in CA-Clipper,USE and SET INDEX firs t search the current SET DEFAULTdrive an d direc tory for the file to open . If the file is not fo und ,the SET PA TH list is search ed in the order specified. On ly afterall paths are searched is an open operation considered a failure.

2-110 CA-Clipper



The Data bas e System

Order ing

W ith both USE an d SET IN DE X yo u lis t the index f i les you wan t

to open, and the first one in the list becomes the controlling index.The controlling index defines the order in which the database fileis processed and is the only index that can be searched.

The SET ORD ER com man d changes the cont ro ll ing index byspecify ing a position in the inde x file list. SE T OR D ER T O 0specifies the physical order as if no index files were in use.

S e a r c h i n g

SEEK and FIND locate a record based on its index key value inthe controlling index file. SEEK is the preferred searchcommand; FIND is an obsolete command that is provided forcom patibility only. Searc hing an index file using either of thesecommands is much faster than performing a sequential search.

CA-Clipper uses one of two index search methods depending ona global f lag sett ing, SET SO FTS EE K. If SET SOF TSE EK is OF F(the default), a failed index search moves the record pointer tothe end of file, setting EO F() to true (.T.). If SET S O FT SE EK isO N , a failed index search moves the record pointer to the recordwith the next higher index key value.

The FOUND() function tests the success or failure of a searchoperation in either case.




The Database System

U p d a t i n g

As long as an index file is open, any changes made to thedatab ase file are autom atically reflecte d in the index file. This is

true of all ope n ind ex files, not just the controlling inde x.Changes to a database file are made using any of the databaseupdate operations mentioned earlier in this section.

Ad dit ional ly, database operat ions that move the record pointerupdate the index file before moving the record pointer if theindex key value has chan ged. A CO M M IT or an index closeoperation also updates the index file.

The REINDEX command recreates al l open index f i les in the

current work area by reindexing each record in the database file.

Closing

Close index f i les with SET INDEX TO with no parameters orCL OS E IND EX . An y of the database close operat ions also closesopen index files in the same work area.

2-112 CA-Clipper



The Inpu t /Outp ut System

The Input/Output System

The CA-Cl ipper language provides a comple te inpu t /outp utsystem allowing data entry and data display on the screen andthe printer. The system includes built-in data validation that isextens ible through th e use of func tions. Includ ed facilities letyou create simple columnar reports and mailing labels, and, withthe provided commands and l ibrary functions, you can createreport ing mecha nisms to sui t your own need s. This sect ionintroduces you to CA-Clipper 's input/output system, giving youbasic information on controlling the console and printer.CA-Clipper has the ability to display output to the screen in oneof two modes: text mode and graphic mode.

Text Mode

In text mode, all characters that are displayed must be one of 255characters that make up the ASCII character set. In addition,you can place only one character at one particular location on thescreen.

These locations are typically sixteen pixels high by eight pixels

wid e. A pixel is the smallest un it that can be disp layed on acomputer screen that represents exactly one color.

Graphic Mode

In graphic mod e, how ever, in addit ion to the regular A SCIIcharacter set, you now have control over what is displayed inpixel coordinates instead of row and column coordinates as intext mode. Using graphic mode, bi tmaps can be displayed,

smooth l ines can be drawn, and applicat ions look smoother andmore elegant than ever before.




The Input/Output System

For comp atibi l ity with previou s versions of CA -Clipper, textm ode is the default , but sw itching from text mod e to graphicmod e is easy. S imply use the SET VIDEO MO DE com ma nd asshown in this example:

// Header file with graphic constants#include "Llibg.ch"

SET VIDEOMODE TO LLG_VIDEO_VGA_640_480_16// All output to the screen will now be in graphicmode

SET VIDEOMODE TO LLG_VIDEO_TEXT// Now all output will be in text mode

Using SET VIDEOMODE wi th the cons tantLLG _VID EO_ VG A_6 40_48 0_16 f ir s t c lears the screen then

switches to a 640 χ 480 pixel screen in VG A m ode w ith s ixteencolor support . You r video card must be VE SA 1.2 comp atible touse graphic mo de. See the SET VIDE OM OD E com man d in theReference Guide for more details.

LLG_VIDEO_VGA_640_480_16 and LLG_VIDEO_TEXT a re theonly display modes buil t into CA-Clipper.

For more detai led information about displaying output ingraphic mode, see the "Program ming in Graphic Mo de " chapter

later in this guide.

2-114 CA-Clipper



The Input /Output System

Console Operations

Commands and funct ions that display output on the screen

witho ut reference to row , colum n, or pixel posi t ion are cal ledconsole operations. Used in conjunction wi th SET ALT ER NA TEand SET PRINTER, these operat ions can s imultaneously sendou tpu t to the screen, a text file, and the printer. H ow eve r, themajor i ty of the console com man ds have TO PRIN TER and TOFILE clauses that supersede SET PRINTER and SETAL TE RN AT E. The fol lowing table l is ts a l l the consoleoperat ions in the CA-Clipper language:

O p e r a t i o n O u t p u t

? 1 ?? The resul t of one or more expressions

A C C E P T A prompt. Waits for character input .

D I S P L AY 1 LIST The con tents of a data base file

IN PU T A prom pt. W aits for input of any type.

L A B E L F O R M The contents of a database file as labels

R E P O RT F O R M The contents of a database file as a report

TEXT . . .END TEX T A block of textTY PE Th e conte nts of a file

WA I T A prom pt. Wa its for a s ingle cha racterinput.

QO UT QIQ QO UT Q The resu l t o f one or more express ions

SET CO NS OL E is an impor tan t comm and to console opera t ionssince it le ts you tem porari ly su ppress the screen output with outaffect ing fi le and printer output . For exam ple, if you are p rint inga report, i t can be disconcerting to see the report scrolling up thescreen wh ile i t is pr int ing. To control this , SET CO N SO LE O FFbefore printing the report, as in this code segment:

USE Accounts NEWSET CONSOLE OFFREPORT FORM Accounts TO PRINTERSET CONSOLE ONCLOSE Accounts




The Input / Ou tput System

Full-Screen Operations

The full-screen operations address the screen (and some times theprinter) directly, usually by addressing a specific row and

column. These operat ions are dis t inguished from consoleoperat ions in that they ignore SET ALTERNATE, SETCONSOLE, and SET PRINTER:

O p e r a t i o n Result

@.. .BOX Draw a box

©.. .C LEA R Erase the screen

©. . .SAY Display the result of an expression

Θ.. .ΤΟ Draw a box

C L E A R Erase the screen

CO L() Return current colum n posi t ion

ROW() Return current row posi t ion

M A X C O L O Return the maximum column posi t ion

M A X R O W ( ) Return the maximum row posi t ion

SAV ESC REE N() Save a screen reg ion

REST SCR EEN Q Restore a screen region

N o t e : In graphic mo de , the SAV ESCRE ENQ andRE STS CR EE N() funct ions should be used with caut ion. Pleasesee these entries in the Reference Guide for mo re information.

Of al l the ful l -screen op erat ions, only @.. .SAY can be redirectedto the printer with SET D EV ICE and wri t ten to a f i le with SETPR IN TE R. Printing is discu ssed later on in this section.

2-116 CA-Clipper




Controlling Screen Color

SETCOLOR() al lows you to save the current color set t ing and

optional ly set new co lors for subseq uent screen paint ing. A co lorstr ing contains several color set t ings, each correspond ing to adifferent logical region of the screen.

All console and ful l -screen operat ions (with the exception o f@.. .GET) use the s tandard color set t ing when displaying to thescreen. The GE T area (@.. .GET ) uses the enha nced set t ing, andthe unselected set t ing causes all GE Ts other than the current o neto be disp layed u sing a different color a t t r ibute.

For more information regarding color, including a l is t of theavai lable color code s, see SE TC OL OR () in the " Lan gua geReference" chapter of the Reference Guide.

Controlling Output Destination

In CA -Clipp er, the screen is alw ays the defaul t ou tputdestination, but you can direct output to the printer or a disk file.

Directing Output to the Printer

The way to direct output to the printer depends on whatopera t ion you are us ing . Ma ny console com ma nds have a TOPR INT ER clause designed to echo output to the printer. Forinstance, to print a set of labels:

LABEL FORM Ship TO PRINTER

For console commands that do not support this clause, use theSET PRINTER command :

SET PRINTER ONDO WHILE .NOT. EOF()

QOUT(Name)SKIP

ENDDOSET PRINTER OFF




The Input / Ou tpu t System

You can use SET PRINTER instead of the TO PRINTER clause, i fyou prefer. As s tated earlier, you ma y wa nt to SET CO N SO LEO FF before direct ing con sole outpu t to the printer.

For O. ..SAY, use the SET DE VICE com ma nd:SET DEVICE TO PRINTERDO WHILE .NOT. EOF()

@ 1, 1 SAY NameSKIP

ENDDOSET DEVICE TO SCREEN

Unlik e console op erat ions, @.. .SAY displays ei ther to the screenor to the printer, but never to both devices simultaneously.

CA -Clipp er al low s other pr inter controls , including access to thecurrent pr inthea d posi t ion with PR OW () and PC OL (). Thesefunct ions al low relat ive printer addressing with @.. .SAY in muchthe same way as ROW() and COL() do relat ive screenaddressing.

When print ing with @.. .SAY, a page eject is issued anytime youaddress a row that is less than the current PROW Q value.SETPRQ) rese ts PROW() and PCOL() to prevent an au tomat icpage eject where it is not desired.

SET M A RG IN sets the lef t pr inter ma rgin. W ith console ou tput ,the margin set t ing indents outpu t whe never there is a new l ine.@.. .SAY adds the margin set t ing to the specif ied column value.

2-118 CA-Clipper




Direct ing O utpu t to α Fi le

The SET PRINTER command has a second form that is used to

change the output device, al lowing you to access more than oneprinter and to direct printed output to a f ile . SET PR INT ER TOsets the output device for all printed output, including consoleand full-screen operations.

You cannot send @...SAY output directly to a file. Instead, youmu st reroute its printed outpu t to a fi le with SET PRIN TE R TOas in this example:

SET PRINTER TO AtOut.prnSET DEVICE TO PRINTER

// <@...SAY commands go here>SET DEVICE TO SCREENSET PRINTER TO

Redirect ing printer output to a text f ile with SET P RIN TE R TOcauses all printed output to go to the file, not just @...SAYs.Thus, it can be used to send @...SAY and console output to thesame f i le , as long as both SET DEVICE TO PRINTER and SETPRINTER ON are in effect :

SET PRINTER TO AtOut.prnSET DEVICE TO PRINTER// <@...SAY commands go here>

SET PRINTER ON

// <console operations go here>

SET PRINTER OFFSET DEVICE TO SCREENSET PRINTER TO

You can direct output to a file without rerouting printer output.

Th e easiest way is to use the TO FIL E option if i t is sup po rted . Ifno t , u se SET ALT ERN ATE :

SET ALTERNATE TO OutFile.prnSET ALTERNATE ON

// <console operations go here>

SET ALTERNATE OFFCLOSE ALTERNATE




The Keyboard System

The Keyboard System

By defaul t , CA-Clipper applicat ions automatical ly save thecharacters typed on the keyboard in a buffer cal led the keyboard ,or typea head , buffer. The characters in the keybo ard buffer arethen removed on a first in, first out basis and used as input whenrequired by a wait s tate or INKE Y(). The wait s tates includeACC EPT, INPUT , REA D, WA IT, ACH OICE( ) , DBED IT( ), andM E M O E D I T ( ) .

The buffer ing of keystrokes lets the user continue typing withou thaving to wait for the application to catch up, and it is veryconvenient, especially for applications that are data entryintensiv e wh ere the user hap pe ns to be a very fast typist. This

feature may never affect the way you program your applicat ions,but there may be cases when you want to control the keyboardbuffer. This sect ion describes the commands and funct ionsavai lable in CA -Clipp er that affect the keyboard b uffer.

Ch an gin g the Ke ybo ard Buffer Size

SET TY PE AH EA D cont ro ls the number of charac ters thekeyb oard buffer can hold . The minim um size of the keyboard

buffer is zero characters, a setting which essentially disables thekeyboard buffer so the user can type only when an operat ionrequir ing inpu t is act ively executing. The m axim um keyboa rdbuffer s ize is 32,767 characters . Issuing a SET TYPEAHEADcommand in an applicat ion clears the current contents of thekeyboard buffer before changing the buffer s ize.

2-120 CA-Clipper



The Keyboard System

Putting Characters in the Keyboard Buffer

KEYBOARD is used to programmatical ly put characters into the

keyboard buffer. This command clears al l pending keystrokesbefore placing one or more ASCII characters in the keyboardbuffer. You can use the CHR() funct ion with KEYBOARD fornonp rintable keystrokes such as a carr iage return (CH R(13)) .

Characters placed in the keyb oard buffer this wa y are t reatedjust as i f they were typed from the keybo ard— they are notexecuted until extracted by a wait state or by INKEYQ.

KEYBOARD is useful for developing self-running demonstrat ion

programs in CA-Clipper, and i t is also commonly used with theAC HO ICE () user funct ion to force a part icular me nu select ion.

Refer to the "CA-Clipper INKEY() Codes" appendix in the ErrorMessages and Appendices Guide for a complete list of key codes.

Reading Characters from the Keyboard Buffer

The re are three func tions that access the key boa rd buffer . Th eseare INKE Y() , LA STKE Y() , and NE XTK EY() . Each funct ionreturns a num eric value betw een -39 and 386, identifying theINKEY() code of keys including function, Alt+function,Ctr l+function, Alt+let ter, and Ctr l+let ter key combinat ions.

INKEYQ is the only keyboard function that actually extracts achara cter from the ke ybo ard b uffer. In this sense, it is l ike a waitstate, but it may or may not pause for input depending on itsargum ent. INK EY () extracts the next pend ing keystroke fromthe keyboard buffer and returns the AS CII value of that key.This function is useful for polling the keyboard or pausingprogram execution.




The Keyboard System

NEXTKEYO returns the ASCII value of the next pendingkeystroke without removing i t f rom the keyboard buffer.

LA STKE YO returns the ASCII value of the last keystroke

extracted from the keyb oard buffer. Keystrokes are extractedfrom the buffer either by IN KE Y() or by a wait state. Thisfunction has several applicat ions, including d etermining the keyused to terminate a READ.

Controlling Predefined Keys

There are several com ma nd s and functions that control theaction of specific, pred efined ke ys. Thes e are sum ma rized in the

following table:

C o m m a n d / F u n c t i o n Purpose

SET ESCAPE Togg le abil ity to terminate RE ADwith Esc

S E T W R A P Toggle circular me nu navigat ionwith Up arrow and Down arrow

ALTD() Toggle ability to invoke the

debugger wi th Al t+DREADEXIT( ) Togg le abil i ty to terminate RE AD

with Up arrow or Down arrow

S E T C A N C E L Q Toggle ability to terminateapplicat ion with Alt+C

In addition to these limited controls, all predefined keys can becompletely redefined with SET KEY.

2-122 CA-Clipper



The Keyboard System

Reassigning Key Definitions

SET K EY lets you redefine any key on the keyboard byspecifying a procedu re to be executed w hen the key is presseddur ing a wai t sta te . Three parameters , PRO CN AM E() ,PRO CLIN E() , and REA DV ARQ , are au tomat ica l ly passed to theproced ure. As with IN KE Y(), keys are ident if ied by a num ericASCII code.

Another com ma nd, SET FU NC TIO N, redef ines func tion keysjust as SET KEY redefines other keys. This command, however,i s preprocessed in to SET KEY and KEY BO AR D com ma nds ,causing SET FUNCTION to clear a SET KEY for the same key

num ber. This is incom patible with previous releases ofCA-Clipper which maintained a separate l is t for SETFUNCTION and SET KEY def in i t ions .

A total of 32 keys can be SE T at one time. At startup, the sy stemassu m es that F l is set to H elp . If you link a pro cedu re calle dHelp into the current progra m, pressing Fl from a wait s tateexecutes it .

All SET KE Y defini t ions take precede nce over the s tandard keydefinitions. This includes predefined keys such as Insert andDelete that are used in editing, as well as keys such as Esc andAlt+C that you can control with bui l t - in commands andfunct ions.

Clearing the Keyboard Buffer

Yo u can clear the keyboard b uffer of al l pendin g keystrokes withCL EA R TYP EA HE AD . This com man d is usefu l whe n you wantto be sure the user does not byp ass imp ortant me ssages on the

screen. Simp ly displaying the messa ge and wait ing for aresponse q uickly f lashes the message and uses the next pe ndingcharacter in the keybo ard buffer for the response. Ho we ver,i ssu ing a CL EAR T YP EA HE AD before d isp lay ing the messageensures that there are no pending characters and forces the userto read the messa ge before enter ing a response.

Prog ram ming a nd Utilit ies Gu ide 2-123



The Low-Level File System


Several funct ions are provided that a l low you to manipulateDO S binary f i les direct ly from a CA -Clippe r application. Theseinclude the capability to open existing binary files, to create newfiles, and to read from and write to open files. This sectiondescribes these functions and their capabilit ies. Note that thefunct ions de scribed herein al low low-level access to DO S fi lesand devices. They require a thorough knowledge of theoperat ing sy stem and should be used with care. Refer to the"Language Reference" chapter of the Reference Guide for moreinformation on a part icular fu nct ion.

Opening α File

There are two functions available to open a binary file. The first ,FOPEN(), opens an exist ing f i le , while the second, FCREATEQ,creates a new file, leaving it open for use. Both functions returna numb er represent ing the DOS fi le handle for the open f ile . Thefile handle must be saved in a variable to identify the file to otherfunc tions. FC RE AT E() lets you spe cify a DO S file attribute, andFOPEN() lets you specify the DOS open mode.

Since these functions are dealing with files at the operatingsystem level , they do not respect the SET DEFAULT and SETPA TH set t ings. Instead, unless a f i lename is unam biguou slyidentif ied with a path, the current D OS d rive and directory areassum ed. Also , no f i le extension is assum ed unless one isexplicitly specified.

2-124 CA-Clipper




Reading from a File

Once a binary file is open, you can read its contents with one oftwo funct ions, FR EA D() or FRE AD STR (). Both funct ions requirethat you ide ntify the file using its file han dle . Spe cifying aparticular file is necessary since more than one binary file can beopen at a time.

FREAD() and FREADSTR() are very s imilar in funct ional i ty. Themain difference is that FREAD() requires you to specify where tosave the characters read from the fi le , wh ereas FRE AD STR ()returns the characters read as a character string.

In either case, the data read from a binary file is in binary form.Thus, several funct ions are provided to convert binary data tonumeric so that you can manipulate the information in yourCA-Clipper applicat ion.

All of the conversion funct ions require that the argument berepresented as a character s t r ing, which makes them work easi lywi th FREAD() and FREADSTR() .

Writing to α File

Once a binary file is open, you can write to it with FWRITE().This function requires that you identify the file using its filehan dle . It is nece ssary to specify a particu lar file since mo re th anone binary f ile can be open at a t ime. You can not use FW RITEQon a f i le that was opened in read-only mode.

With FWRITE() you specify a character string to write to the file.The I2BIN() and L2BIN() funct ions are provided to convertCA-Clipper numeric values to binary form and return the resul ts

as character strings. These character strings can then be writtento a binary file.





Manipu lating the File Pointer

When a binary file is initially opened for use, the file pointer ispositioned to the beginning of the file. The read and writefunct ions m ove the f ile pointer, as nee ded , to perform theiroperation, and leave the pointer in its new position in the file.

Another funct ion, FSEEK(), le ts you move the pointer direct ly toa specific position in the file. This function is particularly usefulif you must read or wri te characters somewhere in the middle ofa file but are not interested in the information preceding thosecharacters . Instead of perform ing a read operat ion to bypass theunwanted da ta , you would per form an FSEEK()—which i s muchmore efficient—to move the file pointer to the correct position in

the fi le . The n, you wou ld read or wri te the necessary characters .

FSEEK() is very flexible in its ability to position the file pointer.You specify an argument that tells the function to begin from thebeginning of file, from the current file position, or from the endof fi le , and ano ther argum ent that indicates the num ber ofposi t ions to move.

Closing α File

FC LO SE() closes an open binary f i le and wri tes the associatedD OS buffe rs to disk. This function requ ires that you identify thefile you want to close by its file handle. Specifying a particularfile is necessary since more than one binary file can be open at atime.

2-126 CA-Clipper




Error Detection

When using the low-level file functions, you can test for errors

with the individual funct ion return value or with the FERROR()funct ion. W hich m ethod yo u use depen ds on the level of detai lyou want . The fol lowing table sum ma rizes the return values ofthe low-level file functions that indicate an error condition:

Funct ion Error Condit ion

FCLOSE() Returns false (.F.)

FCREATE( ) Returns -1

FOPEN() Returns -1

FR EA D( ) Retu rns zero or a value less than thenumber of bytes to read

FREADSTR() Returns a null string

FSEEK() No error condit ion

FWRITE() Returns zero or a value less than thenum ber of bytes to wri te

FER RO R() returns a DOS error num ber for the last low-level f i lefunction exec uted . If there is no error, FE RR OR () returns zero.After determining that a function has failed by checking itsreturn value, you can use FERROR() to narrow down the causeof the error. This fun ction retains its valu e until the nextexecution of a low-level file function.






Chapter 3

The Runtime Environment


After you have designed, wri t ten, debugged, and configured aCA-Clipper application, the next step is to install the program on

the end user 's machine . This process consis ts of preparing theuser 's wo rkstatio n. Before doing this, ho w ever , there are anumber of issues to understand in order to guarantee that yourapplication will run correctly in the user 's computingenvironment .

This primarily consists of setting the workstation operatingsystem environm ent so the prog ram w il l have enough resourcesto run, configuring the applicat ion 's environmen t , andconfiguring the user 's netw ork environm ent to ensure thatsoftware instal led on the netw ork w il l operate correct ly and hav eaccess to shared resources.

In this chapter, the following major topics are discussed:

• Set t ing the workstat ion environm ent

• Set t ing the applicat ion environm ent

• Set t ing the netw ork environm ent

• The app lication batc h file

Prog ram ming a nd Utilit ies G uide 3-1



Sett ing the Workstation Environment

Setting the Workstation Environment

The workstat ion 's operat ing environment is configured by twofacilit ies at system initialization: settings defined in CONFIG.SYSand commands executed in AUTOEXEC.BAT.

CONFIG.SYS CO NF IG.SY S is an ASC II text f i le that DO S processes duringsystem initialization. It is used to config ure the work station 'soperat ing system environm ent by set t ing the num ber of internalbuffers and open files and installing device drivers to enableRAM disks, terminal emulat ion, extended or expanded memory,and other peripheral devices. Of particular interest whenexecuting CA-Clipper programs are the FILES and BUFFERSsettings, although there are others.

When the user 's computer is s tar ted, CONFIG.SYS must belocated in the root directory of the user 's startup disk. After theoperating system is configured the system batch fileAUTOEXEC.BAT is ca l led .

AUTOEXEC.BAT AU TO EX EC .BA T is a special batch f i le located in the rootdirectory of the wo rkstat ion s tar tup disk. After the com ma ndprocessor (C O M M A N D . C O M ) is loaded, it looks forAUTOEXEC.BAT and executes al l of the commands found in thefile. Typica l ly, an AU TO EXE C.BA T wou ld per form one or moreof the fol lowing operat ions:

• Define the PA TH environm ent variable to tellC O M M A N D . C O Mwhere to look for executable files if theyare not located in the current d r ive/d irecto ry

• Execute a ser ies of SET com ma nds to define com mo nenvironment variables

• Use the M O DE com m and to configure the ser ial port andredirect printed output to it

• Loa d TSR pro gra m s, such as the netw ork shell or a localprint spooler

• Invo ke a defau lt app lication , such as a D O S shell or usermenu

3-2 CA-Clipper

http://command.com/

http://command.com/

http://command.com/

http://command.com/




For more information on the full range of configurations that canbe made in CO NFIG .SYS and AUT OEX EC.BA T, re fer to yourDOS manual .

Files and Buffers

In order for a CA-Clipper application to run, i t must haveenou gh f i le handles a nd buffers , which you configure u sing theFILES and BUFFERS commands in the CONFIG.SYS fi le .

The FILES command uses file handles to set the num ber of files ordevic es that can be ope n at one time. The defau lt valu e is eight,

but FILES can be set as high as 255 if the user 's workstation isrun ning DO S 3.3 or high er. If the nu mb er of file han dles isgreater than 20, you m ust use the CLIPPER environm entvariable (discussed later on in this chapter) to tell CA-Clipperhow many handles to use.

The actual number of file handles to specify depends on yourapplicat ion. As a general pr inciple , you should al low one h andlefor each databa se and index file in you r app lication. No te,how ever, that som e operat ions, such as indexing and sort ing,create temporary files. This increases the number of file handlesrequired for the application to run.

If the user 's workstation is running a version of DOS earlier thanversion 3.3, the maximum number of files that can be open at onetime is 20. If this is the case, you m ay w ant to upgra de to a mo rerecent version of DOS.

The BUFFERS command al locates the number of buffers (diskcache) DOS uses to keep copies of the sectors most recently readfrom o r written to disk. If not specified , the default value is two

for IBM P C /X T s and three for IBM ATs and beyo nd. Therecommended number of buffers for CA-Clipper is e ight .

For exam ple, the CO NF IG.SY S fi le for versions of DO S prior to3.3 should contain the following two statements:

FILES=20BUFFERS=8

Programming and Util i t ies Guide 3-3




Ch an g in g the DOS Env i ronment S ize

W hen set ting up you r applicat ion on a user 's ma chine, i f youadd more environment variables than will fit in the default

environment space (160 bytes in version 3.2), a DOS errormessage is displayed, and the variable is not assigned.

In DOS versions 3.2 and above, you can change the defaultenvironment s ize by specifying a SHELL command inCONFIG.SYS, l ike this :

SHELL=COMMAND.COM /E:<nBytes> /P

<riBytes> is the initial allocation of enviro nm ent space and can beany value between 160 and 32,768. The recom men ded value is

1024 bytes.

Specifying the Locat ion of Executable Fi les

With a CA-Clipper program, there are normally two types offiles associated with the application's executable image:

• Exe cuta ble files (.EXE)

• Ov erlay files (.OVL)

N o t e : Ov erlay files are app licable only if the applica tion w aslinked w ith a real m od e linker. If you link with a protectedmode l inker such as CA-Clipper/Exospace, the applicat ion wil lnot have associated .OVL files because they are not necessary.Protected-mode applicat ions overlay code as needed when theapplicat ion is runnin g— but i t is completely automatic andtransparent, and you never need to worry about it .

In the runtime environment, there are som e specific rules as tohow these files are located when invoked or requested.

The executable file (.EXE) is the program file that can be invokeddirect ly from the DOS command prompt and is searched for inthe current directory . If not foun d, the current PA TH issearched.

3 -4 CA-Cl ipper




Overlay files (.OVL) are files associated with the application.EXE file and contain either dyna mic or static overla ys. Th ey a researched for only in the directory w here the .EXE is located . N o

other directories are search ed. Tf not fou nd, a runtim e error isgen erated . This m eans you m ust install all overla y files in thesame location as the executable (.EXE) file.

To assure executable files (.EXE) and associated files can belocated, add the location of the .EXE file to the PATHenvironment variable in the user 's AUTOEXEC.BAT fi le:

SET PATH=C: \APPS\MYAPP

Temporary Files

In the process of some operations, such as sorting and indexing,CA-Clipper creates temporary files. These files are created eitherin the current directory or in the directory specified by theenviron men t variable TM P. To assign a TM P variable, place acommand l ine l ike the fol lowing in the user 's AUTOEXEC.BATfile:

SET TMP=C:\TEMP

You can overr ide the TMP set t ing using the TEMPPATHenvironment setting. See the Setting the ApplicationEnvironment section later in this chapter for more information.

Specifying the Location of C O M M A N D . C O M

When you use the RUN command to execute external programs,the applicat ion ru nt ime system n eeds to loadC O M M A N D . C O M to execu te the specified pro gra m . To do this succe ssfully, the

environment variable COMSPEC must point to the locat ion ofC O M M A N D . C O M . No rm ally , DO S sets the valu e of thisvariable to the root directory of the startup disk.

If for some reason this is not the case, add an explicit assignmentof CO M SPE C in the user 's AUT OE XEC .BAT or appl ica tion ba tchfile (discussed later in this chapter), as follows:

SET C0MSPEC=C:\D0S


http://apps/MYAPP

http://temp/

http://command.com/

http://command.com/

http://command.com/

http://command.com/

http://command.com/

http://command.com/

http://temp/

http://apps/MYAPP




Configuring the Serial Port

If the workstation is printing to a local printer attached to a serialport , you must configure the port with the MODE command.M O D E is used to configure the ser ial port with the app ropriatebaud rate, parity, word length, and stop bits for the attachedprinter. A subsequen t M O DE com ma nd can also be used toredirect output from the defaul t paral lel port (LPT1, LPT2, orLPT3) to a ser ial port (COM1 or COM2).

For CA-Clipper programs running on a workstat ion with a ser ialport and a local pr inter at tached, the recommended procedure isto fi rst run M OD E w ith the configurat ion op t ions within theapp lication batch file (discussed later in this chap ter). To

redirect pr inted outpu t from the defaul t parallel port , you havetwo choices: you can ei ther redirect output using the MODEcom ma nd in the applicat ion batch f i le , or you can use the SETPRINTER command within the applicat ion.

Using MODE For exam ple, the fol lowing applicat ion batch f ile show s how touse the MODE command to configure a ser ial port and redirectoutput to it:

REM Application batch fileMODE C0M1:=1200, 8,1,ΡMODE LPT1:=C0M1MYAPP.EXEMODE LPT1

Using SET PRINTER If SET PR IN TE R is use d, the referen ce to the port can be a li teralor variable value, but a li teral value designat ion is some wh atrestrictive and environment specific. The printer port can bespecif ied to the SET PRINTER command as an extendedexp ression . This allow s yo u to pass the print destination to anapplicat ion via an environment variable or as a command l ineargument of the applicat ion.

For example, this application batch file configures the serial portthen defines an environment variable designat ing the printerpor t as COM1:

REM Application batch fileMODE COM1:=1200,8,1,PSET CLIPP0RT=C0M1MYAPP.EXEMODE LPT1

3 -6 CA-Cl ipper



Set ting the Ap pl ica t io n Environment

In the CA -Clippe r applicat ion, the GE TEN V() funct ion is used toobtain the port. If the env iron m ent variab le exists, SETPRINTER directs output to the specified port:

IF EMPTY((cDest := GETENV(" CLIPP0RT ")))SET PRINTER TO (cDest)

ELSESET PRINTER TO LPT1

ENDIF

Setting the Ap plic at io n Environm ent

Once you have set the workstat ion environment , you may needto set the applicat ion environm ent . CA -Clippe r prov idesruntime configurat ion control of CA-Clipper-compiled programswith a number of settings that you can specify in a DOSenvironment variable named CLIPPER or on the applicat ioncommand l ine .

The following table lists the syntax and a brief description ofeach setting:

Sett ing M e a n i n gBAD CAC HE Save / r e s to re EM M page f rame on

each EMM access

CG ACU RS Preven t u se o f EG A /V G A ex tendedcursor capability

OYNF:<nHandles> Specify number of file handles fordynamic overlay system use

E:<nExpandedKBytes> Conf igure amount of expanded

memory¥:<nHandles> Set maximum number of f i le handles

INFO Display mem ory configurat iondetails at startup

Continued




Set ting the Ap pl ica t ion Environment

Continued

Sett ing M e a n i n g

NO IDL E Prevent detect ion of idle t ime during

execution of compiled applicat ions

SWAPK:<nBytes> Specify maximum size of disk swapfile used for VM system

SW A PP A TH : '<^ / z> ' Spec ify l oca tion o f VM swap f il e

TEMPPATH: '<paf / /> ' Control placement of temporary sortand index files

X:<nKBytes> Exclude avai lable memory

N o t e : I f you link you r applicat ion with C A-C lipp er/E xos pac e,there are several additional runtime environment settings thatyou can use to control the VM system. See the EX OS PA CEEXECUTABLE CLIPPER command in the "CA-Cl ipper Pro tec tedMo de Lin ker— EXO SPA CE .EXE " chapter of th is gu ide for a tab leof these settings.

The fol lowing rules apply when specifying environment set t ings,regardless of wh ether you specify them on the applicat ioncommand l ine or in the CLIPPER environment variable:

• Prefac e each setting wi th a dou ble-slash

• Place a single blan k spac e betw een settings

• Place a colon betw een set t ing and argum ent , with nointervening space

It is possible to specify a setting twice, once in the CLIPPERenvironment variable and then again on the applicat ioncom ma nd l ine. I f you do this , set t ings on the com ma nd l ineoverride like settings in the environment variable. This feature

provides an easy way to define those settings that are more orless permanent using the CLIPPER environment variable and tooverride those settings on an application-by-application basis.

3-8 CA-Clipper




Application C om m an d Line

To specify environment set t ings on the applicat ion commandline, use the following syntax:

<app> [//<setting> . . . ] [<app arguments>]

No te that a l l environm ent set t ings must com e before anyapplicat ion arguments on the command l ine.

Tip: I f you wish to use the comm and l ine meth od forspecifying environment settings but also wish to hide thecommand l ine complexi ty from your end user, use an

application batch file (discussed later in this chapter) toinvoke the application with the configuration settings.

The CLIPPER Environment Var iab le

The CLIPPER variable can be entered at the DOS prompt orincluded in the user 's AUTOEXEC.BAT or applicat ion batch f i le(discuss ed later in this cha pter) . If the user will be accessin g theapplicat ion from a network, you can also add the SET CLIPPERcom ma nd to the user 's login scr ipt .

To specify environment set t ings using the CLIPPER environmentvariable, use the fol lowing syntax:

SET CLIPPER=[ / /<setting> . . .]

N o t e : W hen l inking your your applicat ion, you can specifyapplicat ion environment set t ings using an environment variablename other than CLIPPER.





Saving/Restoring EMM Page Frame—BADCACHE

BADCACHE causes the Vir tua l Memory Manager (VMM) topreserve and restore the s tate of the Expanded Memory Manager(EMM) page frame before and af ter every EMM access ( theEMM page frame is an area in real address space through whichEM M da ta is acce ssed ). This setting can be used to correctproblems when there are confl icts with other programs that useE M M .

Note tha t on some EM M sys tems, the BA DC AC HE se tt ing m ayadversely affect VM M perfo rma nce. I t should be used only ifyou experience disk or file corruption because of a conflict with adisk cache or other resident software.

Preventing Extended Cursor Use—CGACURS

CGACURS prevents the use of the extended cursor capabil i ty ofthe EG A /V G A . Spec i fy ing this se tt ing may prec lude somecursor mo des by some d isp lay adapters . CG AC UR S preventsthe unusual cursor behavior when a CA-Clipper program isexecuted in some mult i tasking and TSR environments .

Specifying Number of Dynamic Overlay File Handles—DYNF

DY N F specif ies the nu mb er of fi le handles the dynam ic overlaysystem is allow ed to use. Va lid settings range from 1 to 8,inclu sive. If not spe cified, the default is 2.

3-10 CA-Clipper



Set ting the App l ica t io n Environment

Configuring Expanded Memory—Ε

CA-Cl ipper-compi led programs can use expanded memory tospeed up processing, as well as some disk-based operat ions.CA-Cl ipper can use memory conf igured as expanded memoryaccording to the Lotus-Intel-Microsoft (LIM) Expanded MemorySpecif icat ion (EMS) version 4.0 or higher.

Expanded memory is automatical ly al located in i ts ent i rety ats tar tup—there is no dynamic al locat ion as execution proceeds.The maximum amount al located is l imited by four factors:

• The amo unt of expande d mem ory ava i lab le

• The //E:<nExpandedKBytes> enviro nm ent set t ing• A theore tica l ma xim um of 32 M B

• The amou nt of convent iona l me mo ry ava i lab le

The Ε parameter can be used to restr ict the amount of expandedmemory automatical ly al located to <nExpandedKBytes>. Forexample, specifying the fol lowing Ε parameter restr icts theexpanded memory CA-Cl ipper wi l l a l loca te to 2 MB:

SET CLIPPER=//E:2000

Note that a cer tain amount of conventional memory must beused to contain management tables for the vir tual memorysystem—the more total memory (both conventional andexpanded), the more space taken up by this control information.The am ount of expanded m em ory used m ay be less than theamount avai lable i f there is insuff icient conventional memory tohold the tables.




Set t ing the Ap pl ica t ion Environment

Specifying the Number of Files—F

If you have an application that uses more than 20 files and arerunning under DOS 3.3 or greater, you must use the F parameterto inform CA-Clipper of the maximum number of f i le handles touse. This param eter is used in com binat ion w ith the value youspecif ied with the FILES set t ing in CONFIG.SYS.

When specif ied, CA-Clipper determines the number of f i les thatcan be opened using the smaller of the F parameter and theCO N FIG .SYS FILE set t ing. For exam ple, i f the FILES co mm andis set to 120 and the F parameter is set to 50, the maximumnumber of files that can be opened is 50. The ideal <nHandles> isan odd number that is 5 less than the number specified with the

FILES setting.

Kee p in m ind that the F par am eter shou ld be set judic ious ly. Itmust be large enough to allow the use of all needed files and yetnot so large that valuable memory space is used unnecessarily.

Displaying M em ory Configuration Details at Startup—INFO

INFO provides the fol lowing information about CA-Clipper 's

memory usage at appl icat ion s tar tup:• Th e first l ine describ es the gene ral pro duc t version , revision,

and internat ional version .

• DS=<offset>:0000 is the add ress for the data segm ent orDG RO UP . This value has no application funct ional i ty.

• DS avail=<memory>KB reflects the am oun t of DG RO UPavailable which is used for the allocation of the processorstack, CA-Clipper s tat ics , CA-Clipper environmentvariables , and the evaluat ion s tack.

• OS avail=<memory>KB represents the amo unt ofconventional memory avai lable for VMM swap space. I f thereported value is too low, there is a strong possibility theprogram w i l l t e rmina te wi th a "Convent iona l M emoryExhausted" unrecoverable error.

3 -12 CA-Cl ipper



Set t ing the Appl ica t ion Environment

• EMM avail-<EMM memory>KB shows the amou nt of EM M(expanded m em ory) al located to the current applicat ion. A"V " fol lowing the EMM avail value appears when the

applicat ion is loaded with the BADCACHE configurat ionsetting.

• Fixed Heap-<fixed heap>KB/<number of fixed segments> showsthe size of the fixed heap in kilobyte increments in additionto the nu m be r of fixed segm ents. Fixed hea p is used forsym bols at runt ime (macro s) , s tatic al locat ions (extendsystem), the EMM table, and the symbol table.

Preventing Detection of Idle Time—NOIDLE

NOIDLE prevents CA-Clipper from detect ing and takingadvantage of idle t ime during execution of compiledapplicat ions.

If N OI DL E is not specif ied, CA-C lipper detects idle s tates (forexample, keyboard wait s tates) during execution of compiledapplicat ions. W hen an idle condit ion is detected, the system usesthe slack time to perform garbage collection, file updates, andother rout ine housekeeping dut ies . This increases system

performance by doing this work while the applicat ion is wait ingfor user input.

N o t e : N O IDL E is provid ed for applicat ions in which idle timeprocessing is unacc eptable. Since it reduces overal l systemperformance, i ts use is general ly not recommended.





Specifying Maximum Swap File Size—SWAPK

SWAPK specif ies the maximum al lowable s ize of the disk swapfile used for the virtua l m em ory (V M ) system . Settings arespecif ied in KB incremen ts . Valid set t ings range from 256 to65,53 5, inclu sive. If this setting is not spe cified, the default is16,384 (16 MB).

N o t e : Sw ap space is a l located only as need ed— a p art icularsetting does not guarantee that the swap file will get that big.Suppressing or restr ict ing disk swapping may cause anapplication to fail .

Specifying Swap File Location—SWAPPATH

SWAPPATH specif ies the locat ion of the vir tual memory swapfile. If not spec ified, the sw ap file is created in the curren t D OSdrive and directory.

Specifying Temporary File Location—TEMPPATH

TEMPPATH controls the placement of temporary f i les created

du ring sorting and index ing. By default these files are place d inthe current DOS directory or in the directory specified by theSET T M P en vironm ent variab le, i f i t is defined.

N o t e : Tem pora ry f i les created during sort ing and indexing canbe qui te large. Set t ing TEMPPATH to a small volume (forexam ple, a ram d isk) ma y cause these operat ions to fai l. Ingeneral , the volu me w here these temp orary f i les wil l be w ri t tenshould have an available capacity at least twice the size of thelargest index to be created or database file to be sorted.

3-14 CA-Clipper




Excluding Available Memory—X

In certain situations, especially debugging, you may need to test

how a program operates in a memory environment less than thecurrent machine offers. You can do this using the X parameter toexclude <nKBytes> of m em ory from being allocated, except forthe RU N comm and . For exam ple , i f you spec i fy / /X :6 4 wi th aRAM configurat ion of 640 KB, memory is al located as though thecom puter contains only 576 K B (that is , 640 - 64) of mem ory.

Valid values for <nKBytes> ran ge from zero to 64, inclusive . Th edefault value is zero.

Νοίθ Memory—X is excluded before other memory isal located. The am oun ts al located for other purp oses arediminished accordingly.

The BLINKER Environment Var iab le

The BLINKER environment variable can be used to al ter set t ingsquickly while testing an application, and once the application isin production it provides unique settings for individual

workstat ions.

Set t ings in the BLINKER environment variable should beseparated by spaces.

This example disables Blinker 's use of the EMS pageframe, andsets the size of the overlay pool to 30KB:

SET BLINKER=/OP- /ΟΟ3 0

The environment variable name 'BLINKER' can be changed withthe use o f t he comm and BLINKE R ENV IRON ME NT NA M E,wh ich wil l avoid confl ict with other Blinker l inked program s thatare present on the same computer.





This example changes the name to 'MYAPP' , causing Blinker toignore the 'BLINKER' variable, using 'MYAPP' instead:

SET ΜΥΑΡΡ=/ΟΡ- /ΟΟ30 /CX128

N o t e : For all settings, the Blinker overlay ma nag er ob tainscontro l befo re the pro gra m begin s execution. As a result thesystem resources controlled by these settings are allocated beforethe main program gets control .

C o n t ro l li n g A m o u n t o f EM S M e m o r y — / C E n n n , n n

/CE nn n,n n i s an overr ide of the l ink- time comm and BLINK ERCACHE EMS nnn which cont ro ls the amount of EMS memory

used by the overlay m ana ger for overla y cach ing. For details ofthe usage of these va lues , see the comma nd B LINK ER CA CH EEMS.

C o n t ro l li n g A m o u n t o f X M S M e m o r y — / C X n n n , n n

/CXnnn,nn is an overr ide of the l ink-t ime command BLINKERCA CH E XM S nnn which cont ro ls the amount of XM S m emoryused by the overla y man ag er for overla y cach ing. For details of

the usage of these va lues , see the comm and BLIN KER CA CH EXMS.

Cont ro ll ing Ope ra t in g S ize o f B linker Ov er lay Po o l— /OO nn n

/ OO nn n is an overr ide of the link t ime Blinker com m andBLIN KER OV ERL AY OPSIZ E η which cont ro ls the opera t ingsize of the Blinker ov erlay p ool. For details of the usage of thisva lue , see the command BLINKER OVERLAY OPSIZE.

3-16 CA-Clipper



Sett ing the Network Environment

Con t ro l ling Al loca t ion of Ov er l a y Po o l— /OP c

/OPc (where c=- is disabled, and c=+ is enabled) is an overr ideof the l ink- t ime Bl inker command BLINKER OVERLAYPAGEFRAME which controls the al locat ion of the overlay poolusing the EM S (3.2+) pagefra me . For detai ls of the usage of thisva lue , s ee t he comm and BLINKER O VER LAY PAG EFRA M E.

Cont ro l ling Al loca t ion of Ov er l a y Po o l— /OU c

/OUc (where c=- is disabled, and c=+ is enabled) is an overr ideof the l ink- t ime Bl inker command BLINKER OVERLAY UMBwh ich controls the al locat ion of the overlay poo l using XM S 2.0

up per me m ory blo cks. For detai ls of the usage of this value, seethe command BLINKER OVERLAY UMB.

Setting the Network EnvironmentIf your application is installed on a network, there are some basicrequirem ents that m ust be fulf i lled for the applicat ion to opera teproperly.

Network Hardware Requirements

In order for a CA-Clipper-compiled program to operate on anetwork, there are some basic hardware and operat ing systemrequirements:

• The wo rkstat ion operat ing system mu st be DO S 3.3compat ib le

• The wo rkstat ion mu st have enou gh m em ory to run thenetwork operat ing system shel l , the workstat ion operat ing

system, and the CA-Clipper applicat ion

• The netw ork operat ing system mu st supp ort the DO S 3.3ne tworking pro tocol

N o t e : The amo unt of m em ory used by the netw ork shel l variesfrom one network operat ing system to another.





Assigning Rights

Most network environments govern the access of users tovarious locations on the file server disk as a part of the network

securi ty system. Ne two rk securi ty is necessary in a sharedenvironment to provide suitable levels of protection to otherpe op le's wor k, as we ll as priva cy. This access control ismaintained through a system of rights to directories and files,w hich are granted to users by a network supervisor.

With most PC-based network operat ing systems, r ights arepess imis tically gran ted. Use rs are given a m inim al set of rightsas a defau lt and m ust be explicitly gra nted subs equ ent rights. Ifthe user attempts to access a file and perform some operation

without the required rights for that operation, an error isgenerated from the netw ork op erat ing system to the applicat ion.This means that for an application to operate properly in anetwork environment , the user must be granted the appropriatelevel of rights.

W i th a CA-C l ipper-compi led p rogram , the minim um se t ofrights required to guarantee that the program will successfullyrun is as follows:

• O pen rights— the user has the right to op en existing files

• Read r ights—the user has the r ight to read from or executefiles

• Searc h righ ts— the user has the right to search the directo ry'sfile list

• W rite righ ts— the user has the right to write to existing files

Remember when the applicat ion at tempts to open a f i le inread-w ri te mo de and the user does not have wri te pr ivi leges tothat directory o r file, an error is gen erated . As a default,

CA-Clipper opens database and index f i les as read-wri te unlessspec i fied wi th the READ ON LY clause of the USE com man d.

N o t e : If the applica tion crea tes files for any reaso n, the user willalso require create r ights . This could include indexing, co pying,or writing output to a print file.

3-18 CA-Clipper




Setting Up Network Devices

Part of the resource a network offers is shared access to

peripherals and devices . For most appl icat ions these arenetwork printers .

In a network environment , output to a network printer iscaptured b y the netw ork shel l ( resident in the w orkstat ion 'smemory) and redirected to the network 's pr int ing system.Typically, captured output is spooled to a file until the print jobtermin ates . The sp ool f ile is then placed in a pr int queue andprinted when the network printer becomes ready.

With a CA-Clipper program, one of the workstat ion 's ports mustbe redirected to the specif ied netwo rk printer or queu e. This isusual ly do ne by execut ing a netw ork ut i l i ty pr ior to exe cut ingthe app lication. Th is can be don e either in the use r 's login sc riptor in the application batch file (discussed later in this chapter).

Refer to the "Network Programming" chapter in this guide formore in format ion on programm ing cons idera t ions for ne two rkprint ing. Refer to your network documentat ion for moreinformation about accessing and set t ing up network printers .

Progra mm ing a nd Utilit ies Gu ide 3-19



The Ap plica tion Batc h File

The Application Batch File

If your app l icat ion ha s specif ic invocat ion requirem ents , you cancreate a batch file to invo ke it . Th is batch file can be qu itesimp le, chang ing the directory to the appl icat ion ho m e directorythen invoking the appl icat ion. For examp le:

ECHO OFFREM Accounts Receivable ModuleCD \APPS\ACCOUNTARCD \

Addit ional ly, you can set the CA-Clipper-specif ic environmentvariables for the duration of the run then release them when theapplicat ion qui ts . For example:

ECHO OFFREM Accounts Receivable ModuleSET CLIPPER=//F:54 //E:2000SET TMP=C:\TEMP CD \APPS\ACCOUNTARCD \SET CLIPPER=SET TMP=

Ad dit ional ly, the appl icat ion batch f i le can run netw orkconfiguration util i t ies to redirect output to the network printer,

among other workstat ion specif ic act ions.

Dep end ing on the s tandards of the user 's s i te , such as corporateor company standards for invoking programs, you can put thebatch file in the user 's root directory, batch file directory, or\DO S directory. M ost importan t ly, the batch f i le m ust be in thePATH so i t can be invoked from anywhere on the user 's disk.

3-20 CA-Clipper

http://temp/

http://temp/



Chapter 4

Network Programming


CA -Clipper p rovides the fol lowing features that a l low you totake advantage of Local Area Network (LAN) capabil i t ies to

develop shared applicat ions:• Share d access allow s two or mo re users to open the sam e file

simultaneously

• Exclu sive access prev ents other users from ope ning the sam efile at the same time

• Log ical file lockin g preve nts two or mo re users fromupdating the same file at the same time

• Logical record locking preve nts two or mo re users fromupdating the same record at the same time

• M ultiple record locking allows a range of record s to belocked simultaneously

• Lock status chec king , built into both the file and recordlocking mechanisms, returns the current lock status as alogical value

• Reco rd and file lock release returns to shared access mo de

• Printer redirection allow s use of a shared netw ork printer

• Ne two rk error check ing tests the success or failure of certainoperat ions

This chapter discusses the com m and s and funct ions used toimplement these features in detail . It contains conceptualinformation as well as detailed instructions for developingapplicat ions in CA-C lipper to run on a LA N . For more specif icreference material on any of the com ma nds a nd funct ionsdiscussed in this chapter, see the Reference Guide.




In This Chapter

The following topics are covered:

• LA N requiremen ts for CA -Clipper

• Using shared mo de

• Locking

• Overlays on a netwo rk

• Up date visibility

• Netw ork print ing

N o t e : If you r application do es not require access to a shareddatabase f i le , even though yo ur com puter system has a LAN , theinform ation in this chapter do es not apply to you . By default, aCA-Clipper application assumes a single user and opens all filesin exclusive mode; therefore, no file sharing takes place and nolocking is necessary.

Important Even though your CA-Clipper application uses an RDDthat supports the database and index file formats of another softwareproduct, the application may not be able to share data simultaneouslywith an application written using that software product. Theinteroperability of two applications depends on the locking schemesdefined in the individual RDDs, and compatibility is not alw aysachievable. Refer to the Drivers G uide for more specific information.

4-2 CA-Clipper



LAN Requirements for CA-Clipper

LAN Requirements for CA-Ciipper

CA -Clipp er uses DO S cal ls exclusively for all n etwork-relatedoperat ions and, consequently, appl icat ions that are compiledwith CA-Clipper can run on any LAN designed to the DOSstand ard. You sho uld be fam iliar with the natu re and design ofyour LA N before at temp ting to develop applicat ions that use theCA -Clipp er netw ork features described in this chapter.

The requirements for running a CA-Clipper applicat ion on aLAN are as fol lows:

• The LA N must adhere to DO S 3.3 or higher funct ion calls

• Each wo rkstat ion mu st be running under DO S version 3.3 orhigher in order to use files in shared mode

Using Shared M o d e

When you wri te an applicat ion that wil l run on a LAN, youshould op en database f i les in shared mod e unless exclusivemode is required.

You can use either of these strategies:

• Cha nge the s tatus of the global SET EXC LU SIVE flag fromO N to OF F in the ma in routine for you r app lication. Thi swill cause database files to be opened in shared mode bydefau lt. It also m ean s that you m ust specify exclusive use ofdatabase f i les when you require i t (via USE.. .EXCLUSIVE).

• Spec ify shared access w hen you op en a datab ase file thatrequires i t (via USE.. .SHARED).

N o t e : The low-level fi le open funct ion, FOP EN Q, al lows you tospecify the open mode directly and is unaffected by SETEXC LUS IVE. See the Reference Guide for more information onthis function.

Program ming an d Utilities G uid e 4- 3



Using Shared Mode

When to Obtain Exclusive Use

Certain operations require exclusive use of a database file tofunct ion properly.

CA-Clipper enforces this requirement with an error message ifyou attempt to use any of the following operations with adatabase f i le opened in shared mo de:

• PACK

• REINDEX

• ZAP

If SET EXCLUSIVE is OFF, attempt to open the file with

USE.. .EXCLUSIVE before performing any of these operat ions.Because exclusive use is precluded if any other users are sharingthe file, i t may be necessary to provide logic for communicationamong workstations to request another user to close the file.

Other File Open Operations

In addit ion to USE and SET IN DE X, several other C A-Clipperoperations open one or more files in the course of operation and

determine the open mode (either shared or exclusive)autom atical ly. As a prog ram me r you do not have control overthis, but know ing i t helps you m ake the proper al lowance inyour network applicat ions.

There are two general rules that will help you to decide how agiven opera tion wo rks: if it writes to the file, the open m ode isexclu sive; if i t only read s the file, the open m od e is shared. Forexample, SAVE writes to a (.mem) file and opens it exclusively;RE ST O RE reads a (.mem) file and open s it shared . There fore,your prog ram s must ant icipate possible confl icts wh en workingwith .m em fi les and provide m echanism s for avoidance (forexample, using interworkstat ion communicat ion) or recovery(for example, using the error system).

4-4 CA-Clipper



Using Shared M o de

The following table shows the open modes for all operations thatautomatically open files. In cases where there are two possiblefile open operations, both files are shown; the ordering of the

files refers to the order in which they appear in the syntax.

Opera t ion F i l e l File2

A P P E N D F R O M Shared

COPY FILE Shared Exclusive

C O P Y S T R U C T U R E Exclusive

CO PY STRU CTU RE EXTE ND ED Exc lus ive

C O P Y TO Exclusive

CREATE Exclus ive

CR EA TE FRO M Exclus ive Shared

DISPL AY. . .TO FILE Exclus ive

INDEX Exclusive

JOIN Exclus ive

LA BEL FOR M .. .TO FILE Shared Exclus ive

LIST.. .TO FILE Exclusive

M E M O R E A D ( )Shared

M E M O W R I T Q Exclusive

REP OR T FOR M.. .TO FILE Shared Exclusive

RESTORE Sha red

SAVE Exclusive

S E T A LT E R N AT E Exclusive

SET PRINTER Exclusive

SORT Exclusive

TEX T.. .TO FILE Exclusive

TO TA L Exclusive

TYPE.. .TO FILE Shared Exclusive

U P D AT E Shared




Using Shared Mode

Retrying After an Open Failure

In network programming, the failure of a file open operationbecomes a normal possibility; therefore, you should always

check NETERR ) immediately after a USE to make sure the filewas successfully opened.

Opening Index Files For this reason, you should never include the INDEX clause in aUSE command when programming in a network environment.Although USE...INDEX is a single command, it performs severaldistinct open operations. Instead , open the index files with SETINDEX after checking NETERR ) to determine that the USEsucceeded. Using this method, you can prevent possible runtimeerrors and be guaranteed that the index files will be openedsuccessfully and in the same mode as the associated databasefile.

The following code illustrates the correct way to open databaseand index files in a network program:

USE MyFile SHAREDIF NETERRO // Returns true ( .Τ. ) if USE failed

? File not available in shared mode.BREAK

END IFSET INDEX TO Mylndexl Mylndex2

The NetUseO Function NetUse ) is defined in the sample program Locks.prg. Thefunction demonstrates a flexible and comprehensive file openingscheme that attempts to open a database file in either shared orexclusive mode and continues trying to open the file for a givenamount of time or until it succeeds.

The syntax for NetUse is as follows:

NetXJse {<cDatabase>, <10penMode>, <nSeconds> — lvalue

cDatabase> is the name of the database file to open;lOpenMode> is the open mode ; and nSeconds> is the number of

seconds to retry the operation—a value of zero retries forever.NetUse ) returns true .T.) if the file was opened successfully andfalse .F.) if it was not .

4 6 CA Clipper



Locking

The next example is very similar to the previous one, except thatit uses NetUse() to open the database file:

#define DB_SHARED .F.#define DB_EXCLUSIVE .T.

IF NetUse("File", DB_SHARED 5)SET INDEX TO Mylndexl, Mylndex2

ELSE? "File not available in shared mode."BREAK

END IF

Tip: To use any of the functions defined in Locks .prg(located in your \CLIP53\SOURCE\SAMPLE directory),

compile Locks.prg according to the instructions at the top ofthe program file and link it with your application. Note thatyou can use any function defined in this program file as is,or simply use it as a starting point for your own customizedversion.

N o t e : In a network environment, your application must alwaysanticipate that a file may not be available, regardless of the openmode. When exclusive use is requested, another user accessingthe file (in either shared or exclusive mode) would make the file

unavailable. When shared mode is requested, another user withexclusive use would make the file unavailable.

Locking

If you allow file sharing in your application, you must determinewhen file or record access by more than one user must beprevented. Then, you can incorporate lock functions into yourapplication with accompanying logic to control execution inaccordance with the lock results. Use these basic guidelines todetermine when locking is necessary:

• Locking is required whenever you are going to write to adatabase file

• Locking is optional at all other times

Programming an d Utilities Guide 4 7



Locking

There are two levels of locking: record and file. The one you usewill de pen d on the opera tion required . If you are upd ating on erecord at a time, a record lock will be sufficient; however, if youare performing a mass update, you will need to lock either the

entire file or all of the record s involv ed in the operation. If youneglect to obtain a lock before attempting to write to a sharedfile, the operation will result in an error message.

The following table summarizes the operations that require locksin a network environment:

O p e r a t i o n Requ i rement

@...GET Record lock

DELETE (single record) Record lockDE LE TE (mu ltiple record s) Exclu sive use , file lock, or

multiple record locks

RECALL (sing)e record) Record lock

RECALL (mult iple records) Exclu sive u se, file lock, ormultiple record locks

RE PL AC E (single record) Record lock

REPLACE (mult iple records) Exclu sive u se, file lock, or

multiple record locksU P D AT E Exclu sive u se, file lock, or

multiple record locks

N o t e : CA -Clipper d oes not require a lock for read-onlyopera t ions , such as COUNT, LIST, REPORT FORM, and SUM—even if they have multiple record scopes. The automatic buffermanagement technique buil t into CA-Clipper ensures that theseoperations have access to the most up-to-date information in thedatabase files; however, you may wish to obtain a file lock beforeperforming these operations to make sure that none of the datachang es during the process. W hethe r to lock the fi le depends onyour applicat ion requirements .

4-8 CA-Clipper



Locking

File Locking

The FLOCK() function attempts to place a file lock on the currentdatabase file and returns a logical value indicating the success orfailure of the lock.

FL OC K(), howev er, has the drawbac k that it only t r ies once tolock the file. Be cau se of the possib ility of a failure (a file lock w illfail if anoth er us er has a file or record lock for the sam e file), youwil l probably w ant to make several at tempts before ad mit t ingdefeat.

The FilLockQ Function The FilLock() funct ion, defined in the samp le prog ram

Loc ks.prg , allows yo u to retry the file lock for a specified timelimit. The syn tax for FilLock () is as follows:

FilLock( <nSeconds>) —> lvalue

<nSeconds> specifies the nu mb er of secon ds to retry the filelock— a value of zero retr ies forever. Like FLO CK (), Fi lLock()returns true (.T.) if the file lock was obtained and false (.F.) if itwas not .

Record Locking

Record locking is similar to file locking and is accomplished withRL OC K() or DB RL OC K(). RLO CK () at tempts to lock the currentrecord, releasing all other locks currently held, whereasDBR LOC KQ allows you to lock a range of records, cal led a locklist, by specifying a particu lar record to lock. Both functio nsmake a single attempt to lock the specified record and return alogical value indicating success or failure.

Like FLO CK () , howev er, RLOCK () and DBRLO CK () t ry to lockthe record on ly once. Bec ause of the possib ility of a failure (arecord lock will fail if another user has a file lock for the same fileor a record lock for the same record), you will probably want toma ke several at tempts before admit t ing d efeat .




Locking

The RecLo ck() Funct ion The RecLoc k() funct ion, defined in the samp le prog ramLocks.prg, allows you to retry the record lock for a specified timelimit. Th e synta x for Rec Loc k() is as follow s:

RecLock (<nSeconds>) —» lvalue

<nSeconds> specifies the nu m ber of secon ds to retry the recordlock— a value of zero retr ies forever. Like RLOC K() andDBRLOCK(), RecLock() returns t rue ( .T.) i f the record lock wasobtained and false (.F.) if i t was not.

Tip: RecL ock( ) , in i ts defaul t implem entat ion, does not al lowfor mu ltiple record locks. Slight m odific ation s to the sourcecode to al low a record number argument and to cal l

DB RLO CK () ins tead of RLOC K() , how ever, wi l l add th isfunct ional i ty.

Automatic Locking

When you append a blank record to a shared database (usingDBA PPEN D() o r AP PEN D BL AN K) , CA-Cl ippe r au toma ti cal lytries to lock the new record, setting NETERR() to indicate itssucce ss or failure. Un less the new record can be locked , it is notadd ed. Th us, there is no need to at tempt a record lock beforeedi t ing the new record, but i t is necessary to check NE TER R() sothat you wil l know whether the record was actual ly added.

The Ad dR ec() Function Ad dR ec() , defined in the sam ple program L ocks.prg, is s imilar toFilLock() and R ecLock () in that i t a l lows yo u to retry the a ppen dop eration for a specified tim e limit. This function illustrates howto prop erly test for a successful app end operat ion in a netw orkenviron men t . The syntax is as fol lows:

AddRec{<nSeconds>) —> lvalue

<nSeconds> specifies the nu m ber of secon ds to retry theapp end — a value of zero retr ies forever. Ad dRec () returns t rue(.T.) if the new record is added and locked and false (.F.) if it isnot.

4-10 CA-Clipper



Locking

Tip: Add RecQ, in i ts default implem entat ion, does not al lowfor multiple record locks. Slight modifications to the sourcecode to al low a logical argum ent and to cal l DB AP PE ND ()

instead of APPEND BLANK, however, wil l add thisfunctionality.

Unlocking

On ce a lock is in plac e, an application can w rite to the file. Ot he rusers7 attempts to lock the same record or file will fail , but theywill have read access to the data.

The lock remains in place until the application releases it by:

• Closin g the locked file

• Explicit ly releasing the lock (for exam ple, DB RU NL OC KQreleases a s ingle record lock , DBU NLO CKQ and UN LO CKrelease all locks for the current work area, andDB UN LO CK AL L() and UN LO CK AL L re lease a ll locks in a llwork areas)

• Issuing anoth er lock function (successful or not) for the sam efile

N o t e : DB RL OC K() wil l not release existing locks, unlessspecif ied without an argument.

• Termin ating the prog ram norm ally

Because eff icient netw ork ap plicat ions seek to minimize theduration of the locks they impose, you should release locks assoon as possible after they have served their purpose.




Resolving α Failure

Resolving a Failure

The code for opening files and attempting locks isstraightforward and, as suggested already, you may want to t rythese operations several times before giving up. If, however, afile cannot be opened or a lock cannot be obtained, theapplication has to abandon its original intentions and come upwith substitute plans.

It is essential to communicate any lock or open failure to theuser. You can make the communicat ion transient (a two secondduration, for example) or follow it by an INKEY(O) pause to besure the user sees it . It can be a sm all m essa ge disp layed in thecorner of the screen or a wh ole screen displayed betw een

SAVESCREEN() and RESTSCREEN() .

Offer Ch oices As part of the com mu nicat ion , you m ay also wan t to provideal ternat ives and make a branching choice based on the user 'sselection. A typical m enu m ight offer these choices:

• Retry

This choice simply allows the user to extend the lock or openeffort, without seeking to resolve the failure.

• Try sam e activity, different data

This choice makes sense for lock failures in manyapp lications . If the target record is not available, use anotherinstead. For exam ple, a data entry operator working on astack of credit adjustment slips will not mind putting Smith'sslip at the bottom of the pile and moving on to Jones andBrow n. W he n the operator gets back to Sm ith an hour later,that record wil l proba bly be free. There fore, ma ke the codebranch to the record selection entry point.

• Abo rt current act ivity and go back to higher men u

The cho ice implies aband oning not only the record inque stion, but the activity itself. For exam ple, the user leavesthe credit adjustment section of the program altogether andgoes back to the main menu.

C o m m u n i c a t e t h eFailure to the User

4-12 CA-Clipper



Overlays on a Network

Overlays on a Network

Linkers sometimes produce overlays containing compiledprogra m cod e. By default , a ll com piled CA -Clipper code isplaced in dyna mic overlays. Ad dit ional ly, s tatic overlaying ma ybe requested for C or Assembler code.

By default, overlays are appended to the end of the application's.EXE file (the code may be written to a separate overlay file byusing the INT O clause in the overlaying direct ive) . Duringexecution, the runtime system opens the .EXE file and readsoverlays as required.

W hen the runtime sy stem need s to read overlays, it opens the.EXE file for sha red , read -only acce ss. On a netw ork, this allowsmultiple processes to read the file at the same time.

On so me n etwo rks, how ever , a problem can arise if an at tempt ismade to run the .EXE when another process has opened i t toread overlays. The error occurs becau se the DO S EXEC function(used by C O M M A N D . C O Mto execute programs) opens .EXEfiles using a sharing mod e called ' 'comp atibi l ity mo de ." Onsome networks, this causes a sharing violation if the file is

already in use by another process, even if the other process hasspecified that it wishes to share the file.

If this conflict occurs, i t can usually be resolved by marking theaffected file read -only on the disk. A small utility prog ramR O . C O M , located in \CLIP53 \BIN, is supplied for this purpose.RO toggles the read-only status of a specified file.


http://command.com/

http://ro.com/

http://clip53/BIN

http://clip53/BIN

http://ro.com/

http://command.com/



Update Visibility

Update Visibili ty

When programming in a network environment, i t is important todetermine when database (and index) updates actual ly becomevisible, wh ich differs depending on the observer. This sectiondescribes the visibility rules for each of the following possibleobservers:

• Th e initiator

• The operat ing system and other processes

• The physical disk

N o t e : The rules specified in this section are for the DB FN TX and

DB FN DX database drivers . Rules for other drivers may differ.

The Initiator

The initiator of an operation is the process which causes anupd ate to occu r. All upd ates appea r to the initiator im me diatelyafter they are made.

The O pe rating System a n d O ther ProcessesUpdates are guaranteed to be visible to other processes (otherapplicat ions run ning on the netw ork) w hen the ini t iator wri testhe update to the operat ing system (al though they may becomevisible sooner). Writing to the operating system can be done inseveral ways:

Exclusive M od e If the file is ope n in exclusiv e m od e, the upd ate is not guara nteedto appear until the file is closed or a comm it operatio n (forexample , us ing DB Com mit ( ) or CO M M IT) i s per formed.

File Lock If the file is op en in sh ared m od e w ith a file lock , the up dat e isnot guaranteed to appear until the file is closed or one of thefol lowing op erat ions is perform ed: un lock, record lock, orcommit .

4-1 4 CA-Clipper



Update Visibility

Reco rd Lock If the file is open in shared m od e with a record lock or lock list ,the update is not guaranteed to appear until the file is closed orone of the fol lowing op erat ions is perfo rmed : unlock, comm it , or

any record movement operat ion (such as skipping to a newrecord or going directly to a specified record).

The Physical Disk

Writ ing an update to the operat ing system does not guaranteethat a physical disk write will take place, because the operatingsystem may hold recent ly wri t ten records in mem ory. Theserecords appear to other processes as if they were on the disk, butif a failure occurs (such as a hard wa re pro blem ), the records ma ynev er be physica lly written to disk. In this case , upd ates are lost,and processes to which the updates were vis ible may beproceeding with erroneous data .

To ensure that updates are wri t ten to disk, com mit the chang es( for exam ple , wi th DBC OM M IT() or COM M IT) or close thedatabase f i le (which automatical ly commits the changes) . Any ofthese actions sends a request to the operating system to performa sol id-disk wri te immediately.

Caution Even if you commit changes to disk, there is no guaranteethat a physical disk write will actually occur. Some cache programsand network server software will intercept the comm it request andpostpone the physical disk write. This is a violation of DO S protocounless the underlying system can guarantee that its method ofcommitting updates is as reliable as writing them to the disk controllhardware.

Prog ram min g a nd Utilit ies G uid e 4-1 5



Network Printing

Abnormal Termination

W hen an applicat ion term inates norm ally, a ll fi les are closed andall updates are committed to disk.

If the applicat ion terminates ab norm ally (for example, with anunreco verable datab ase error) , som e updates may be lost . Themissing upd ates ma y potent ial ly include every upd ate to a f ilesince updates to that file were last made visible to the operatingsystem.

If the operating system fails during an application, missingupdates may potentially include every update to a file since thelast point at which updates to that file were committed to disk.

Network Printing

A netw ork by nature is a system that provides shared access tocommon resources. Printers are among several hardwaredevices to wh ich a netw ork can provide shared access. From ageneral point of view, network operat ing systems provideservices to make access to shared printers as transparent aspos sible to the wo rkstatio n. Bec aus e of this, printing to a localprinter appears no different to an application than does printingto a netw ork printer.

The actual difference between printing to a local printer and anetwork printer is that the output to the printer port is capturedby the network shell and redirected to the network file server.As the output is received by the file server, i t is spooled to a filestored on the file server.

4-16 CA-Clipper



Network Printing

W he n a print job is com plete , the file is closed . If the ne tw orkprinter is busy, the spooled file is placed in a print queue andsent to the printer wh enev er i t beco me s ready. Netw ork p rint

queues are generally first in, first out, although most networkoperat ing systems provide print queue management faci l i t ies tochange the order of print jobs.

When sending printed output to a network printer from aCA-Clipper program, there are some considerat ions andapproaches to consider.

Setting Up the Network Printer

In order to print to a network printer, one of the workstationports mu st be redirected to the net wo rk printer. This is usuallydone with a network utility that configures the network shell.

This configurat ion can be accomplished:

• In the use r 's login script

• In the work stat ion AU TO EX EC .BA T fi le , but af ter the userhas logged into the n etwo rk

• In the application batch file

• By running the configurat ion ut i li ty under progra m control

Program Design Considerations

With most PC-based networks, a print job begins when theapplicat ion opens the PRN dev ice. Printed output is capturedand redirected to the spooler until the PRN device is closed bythe application. At that poin t, the print job is subm itted to the

print queue and is printed wh en the printer beco me s av ai lable.

In CA-Clipper, you can explicitly control this process with theSET PRINTER TO command. SET PRINTER TO speci f ied wi ththe device nam e beg ins the print job . After all of the print edoutput has been sent to the printer, SET P RIN TE R TO w ith noargument closes the print job and places the output in the printqueue.




Network Printing

For example, the following code fragment starts and ends a printjob wi th SET PRINTE R T O:

USE Customer NEWSET PRINTER TO LPTlSET PRINTER ONDO WHIL E EOF()

? Customer, AmountSKIP

ENDDOSET PRINTER OFFSET PRINTER TOCLOSE Customer

N o t e : Som e netw ork operat ing systems support a t ime-outfeature that terminates a print job if the network shell has notreceiv ed outp ut for a specified nu m ber of secon ds. Refer to your

network documentat ion for more information.

Printing to α File

One of the great problems of printing is the strong likelihoodthat something wil l hap pen during the print ing process thatcould abort a critical print job . In large scale installations withm any users and a large volum e of t ransact ions, a printerprob lem can have system -wide consequences. Accoun tingsystems may, for example, print a report of transactions as theyare posted at the end of an accou nting p eriod . If the report issent directly to the printer, a print job failure could compromisedata base integrity. In this instan ce, reprinting the report wo uldrequire a rollback of all posted transactions, and all print jobswould then have to be resubmit ted.

A better approach is to print everything to a file then, sometimelater, subm it the print file to the netwo rk prin ter. If there is aprinter or network failure before the report is successfullyprinted, the print file need only be resubmitted to the network

printer . On ce the report has be en successfu lly prin ted, the printfile can be deleted.

After p rinting to a file, you n eed to place the file in the printqueue. There are several approaches to this. Perhaps the easiestmethod is to use the COPY FILE command to copy the file to thePRN device.

4-18 CA-Clipper



Chapter 5

Programm ing in G raph ic M o d e


CA -Clipper 5.3 provides you with the capabil i ty of sw itchingeasily from text m od e to graph ic m od e. In fact, i ts GU I cont rols,

such as push buttons and check boxes, are designed to takeadvantage of graphic mode, thereby minimizing the codechan ges that are need ed to make the t ransi t ion to graphic m ode .

This chapter explains the benefi ts and techn iques of sw itchingprogramming modes. The fol lowing topics are discussed:

• Ove rview of graphic mo de

• Invoking graphic m od e

• Using graphic m od e

• Com pil ing and l inking

• Ma nag ing bi tm ap and font resources

• Troubleshooting

Prog ram min g an d Utilities G uid e 5-1



Overv iew o f Grap h ic M od e

Ove rv iew of G raph ic M o d e

As mentioned earl ier in the discussion of the input/outputsystem in the "Basic Concepts" chapter, CA-Clipper has theability to display output to the screen in one of two modes: textmode and graphic mode. Unlike text mode, which l imits yourdisplay options to the 255 characters in the ASCII character setand al low s you to place only on e character at one p art icularlocat ion on the screen, graphic m od e al lows you to use pixelcoordin ates for your screen displays. This mea ns you can drawsmo other l ines and ut i l ize bi tm aps for icons, toolbar but tons, andas wallpaper for the background of your screens.

Programming SimilaritiesIn some ways, text mode and graphic mode programming arevery sim ilar. For exam ple , the task of cha ngin g the size of awindow containing a TBrowse object involves the same basicapproach, no matter which mode you are using.

In ei ther mode, you would include the fol lowing steps:

1. Estab lish ho w the user w ill indic ate a desire to chan ge thewindow size, probably using some form of the INKEY()funct ion.

2. Rem ove the exist ing w ind ow frame and i ts contents by usingRESTSCREEN() to restore the previously saved background.

3. Redisp lay the wind ow frame us ing DISPBO X() .

4. Up date the TBro wse object 's coordina te instance variables .

5. Repa int the TBro ws e data using TBrow se:refreshAll() .

There are, however, many differences between programming in

the two mo des. In part icular, becau se graphic mode p resentsyou with more display options and flexibility, i t entails greaterprogram ming complexi ty than tex t mode .

5-2 CA-Clipper



Overview of Graphic Mode

Programming Differences

For example, consider the techniques needed to prevent output

from being displayed in a defined region of the screen. Ima ginea cascading window system with three windows, A, B, and C:

Β

c

Let us compare the differences between text mode and graphicmode techniques used to display information in window A whilei t is covered b y w indo ws Β and C .

T he Te xt M o d e Te c h n i q u e

Using text mode, and assuming you saved each window regionprior to paint ing the window boxes, you would probably do thefollowing:

1. Issue a DISP BEG IN() to act ivate video buffering.

2. Rem ove each screen by individually saving i t andimm ediately restoring i ts previous back grou nd. Forexam ple , to uncover window A you would remove wind ow sC and Β as follows:

cNewScrC := SAVESCREEN(nTop,nLeft,nBottom,nRight)RESTSCREEN(nTop,nLeft,nBottom,nRight,cOldScrC)cNewScrB := SAVESCREEN(nTop,nLeft,nBottorn,nRight)RESTSCREEN(nTop,nLeft, nBottom,nRight,cOldScrB)

3. At this point, A is the only visible w ind ow , m akin g itscontents easy to manipulate.

Program ming an d Utilities Gu ide 5 -3



Overview of Graphic Mode

4. After m aking the necessary display changes to wind ow A,save and redisplay windows Β and C:

cOldScrC := SAVESCREEN(nTop,nLeft,nBottom,nRight)RESTSCREEN(nTop,nLeft,nBottom,nRight,cNewScrC)

cOldScrB := SAVESCREEN(nTop,nLeft,nBottom,nRight)RESTSCREEN(nTop,nLeft,nBottom,nRight, cNewScrB)

5. Issue a DIS PE N D() to instantly flush al l of the bufferedscreen output to the screen.

Using the technique of buffering screen output by placing itbetween cal ls to DISPBEGIN() and DISPEND() ensures that theuser sees only the final screen and not the intermediate screenactivity along the wa y. Th e user is not awa re of the disp layingand redisplaying of win dow s Β and C. This provides a smoothvisua l effect. This buffering m eth od is available in text mo debecause display orders are fast and simple, and the memoryneed ed to save a full screen is small ( 4 - 8 KB ).

T h e G r a p h i c M o d e Te c h n i q u e

Th e situation is totally different in grap hic mod e. Instead ofremoving windows one by one unti l the desired window isuncovered, you use exclusion areas. An exclusion area is simp ly adefined screen region wh ere nothing can be wri t ten, a conceptthat is used in almost every graphical system, includingWindows .

In the example above, you would declare windows Β and C asexclusion areas to prevent data from being written to thesewin dow s. Then , wh en you mo dify information in wind ow A ,windows Β and C are not affected.

5-4 CA-Clipper



Invok ing Grap h ic M od e

Your code would be read as fol lows:

// Window Β coordinates

GSETEXCL(nTop, nLeft, nBottom, nRight)// Window C coordinatesGSETEXCL(nTop, nLeft, nBottom, nRight)// Manipulate or paint information in window A

// Remove the previous exclusion areasGSETEXCL(LLG_EXCL_KILL_ALL)

N o t e : GSE TEX CLQ is probab ly the mo st com plex funct ion inCA-Clipper graphic mode. Please refer to the Reference Guide forfurther explanat ion of GSETEXCLQ, as well as the other graphicmode commands and func t ions .

Now that you have had a brief introduct ion to graphic mode, le tus proceed to som e of the basics , including: invoking and usinggraphic mode, compil ing and l inking, and managing bi tmap andfont resources with graphic m od e ut i l i t ies .

Invoking Grap h ic M o d eFor compatibi l i ty with previous versions of CA-Clipper, textmode is the defaul t video mode, but switching from text mode tographic mo de is easy. Simp ly include the heade r fi le Ll ibg.chand use the SET VIDEOMODE command, as shown in th i sexample :


SET VIDEOMODE TO LLG_VIDEO_VGA_64 0_480_16// All output to the screen will now be in graphic// mode

Llibg.ch contains #defines for all of the constants designed foruse with the graphic mode commands and funct ions. Using SETVIDE OM OD E wi th t he LLG_V IDEO_V GA _640_480_16 cons tan tfirst clears the screen, then switches to a 640 χ 480 pixel screen inVGA mode with 16-color support .




Using Gra phic M od e

To swi tch back to tex t mo de , use the SET VID EO MO DEcommand aga in :


SET VIDEOMODE TO LLG__VIDE0_TEXT// Now all output will be in text mode

You can even switch just part of an application to graphic mode,as long as you use the CLS command before switching modesSee the SET VIDEOMODE command in the Reference Guide formore details.

Using G rap hic M o d e

Switching from text mo de to graphic mod e in exist ingCA-Clipper applicat ions should fol low the s teps enumeratedbelo w, while observin g the precautions discussed in the nextsect ion, ent i tled Shad ow ing Restr ict ions:

1. M ake sure that you are using only CA -Clipper funct ions forall screen displays and that other third-party products areman ipulat ing the screen funct ions (using the Gen eral

Terminal (GT) module) .2. Invoke graphic m ode as explained in the previous sect ion,

remember ing to p lace the SET VIDEOMODE command asearly as poss ible in you r application . For exam ple, if yo u areusing an INIT() function, put this command in the firstINIT() defined in your main program fi le .

3. Link the applicat ion with the LLIBG .LIB l ibrary, asexplained later in this chapter und er Com pil ing and Linking.

4. Run you r applicat ion. I t should funct ion in graphic mo de

the same w ay i t funct ioned in text mod e.

5-6 CA-Clipper




Shadowing Restrictions

Graphic mode is restr icted when displaying shadows aroundwin dow s. Ho w ever, i f you stay in text mo de, there is no suchrestr iction s ince screen saves are com patible w ith C A-C lippertext mo de and are hand led as character s t r ings.

For example, the fol lowing user-defined funct ion, MakeShade() ,remains val id in text mode:

MakeShade(nTop,nLeft,nBottom,nRight,nFore,nBack)cSave := SAVESCREEN(nTop, nLeft, nBottom, nRight)cSave := TRANSFORM(cSave, ;

REPLICATE( ' X + CHR(nFore + 15 * nBack), ;LEN(cSave) / 2))

RESTSCREEN(nTop, nLeft, nBottom, nRight, cSave)RETURN NIL

This shadowing technique, however, wil l not work in graphicm od e. First of all , a grap hic screen is saved in mo re than 150 K Bof VM M m em ory, w hereas i t is saved as a 4 - 8 KB ch aracterstr ing in text m ode . Secon dly, it is impo ssible to process a V M Mm em ory area with funct ions l ike TR AN SFO RM Q. Therefo re, i t isimposs ib le to handle shadows us ing SAVESCREEN() ,TRANSFORMS and RESTSCREEN() a s shown in t he p rev iousexample .

Instead, w hen you are using graphic m od e, i t is m uch quickerand more elegant to drawr a rectangle in XOR mode (that is,using GRECT() with the <nMode> param eter set toLLG _M OD E_X OR ) to achieve the shadow ing effec t . Toel iminate the shado w , just draw another ident ical rectangle ofthe same region in XOR mode.

N o t e : M aster ing XO R and SET mod es is indispensab le for a ful lunderstanding of graphical interfaces.




Using Graphic Mode

Enhancing an Application

Now that your application is working, i t is t ime to startenhancing it . The simplest thing to do is to replace the usualf rame parameters in DISPBOX() by LLG_BOX_GRAY_STD so asto get frames w ith a three-dim ensional (3-D) look.

Ne xt , mak e sure that you mo dify the TBrow se :footSep variable,replacing it with a null string (""). Because the lower edge ofyour frame is now made up of pixels instead of semi-graphic l inedraw ing ch aracters , you do no t have to wri te characters in thisarea.

Extend ed character specif icat ions for lef t and r ight box edges,

such as the following, are also no longer desirable and can beremoved f rom your code:

@ nRow, 0 SAY CHR(198)@ nRow, 79 SAY CHR(181)

The more modular your applicat ion, the easier and morecentral ized these modif icat ions wil l be.

Take advantage of the fact that you now have 30 l ines of text(norma l 640 χ 480 VG A m ode ) and not just 25. You r users wil l

appreciate i t . For exam ple, you ma y wan t to increase the s ize ofyou r TBro wse ob jects with the addit ional l ines avai lable. Youmay also want to move your message display area from 24 to 29and give i t a thin frame with a 3-D look using GFRAME().

You w i l l genera l ly use GFRA M E() to f rame the me nu,DISPBOX0 w i th LLG_B OX_G RAY _STD for the w indows o fscrol l ing menus, and GWRITEAT() to wri te characterstransparent ly pixel by pixel . Also , GW RIT EA T() and GLINE()al low you to s imulate top bar menus with accelerator keys ( i .e . ,the underl ining of the act ive character in each m enu ).

5-8 CA-Clipper




Tips an d Techniques

Below are a few tips and techniques for more sophisticatedprogram ming in graphic mode .

Push Buttons

Use push buttons whose size is an integer multiple of the fontsize and whose position is also an integer multiple of this size.This greatly simplifies the task of incorporating icons intoapplicat ions.

Bitmaps a n d Icons

Yo u can use icon (.ICO) files as easily as bitm ap (.BM P) files. Seethe GBMPLOAD() funct ion for more information.

X / Y a n d R o w / C o l u m n C o o r d i n a t e s

As a CA-Clipper developer, you are probably famil iar withfunct ions and commands that address the screen using row andcolumn coord ina tes (us ing ©. . .SAY, DISPBOXQ , and D EVP OS() ,for example) . When specifying text-based screen coordinates inthis manner, you have always designated—and wil l cont inue todesignate—the row fol lowed by the column.

Graphical environments , however, use Cartesian coordinates ,which are expressed as an X coordinate fol lowed by a Ycoordinate. Therefore, when using the graphic mode funct ionsto address pixel-based screen coord inates , you must use this newconvention wh ich is , unfortun ately, the opposi te of the

row/column order convent ion to which you have becomeaccus tomed.




Compiling and Linking

In some cases, the graphic mode functions also returncoor dina tes. W he n this is the case, the return coordin ates arestored as an array. The best way to access the elem ents in suchan array is usin g the relevant #defin es. For exam ple , to retrievethe text-based row and column coordinates , you would use:MSTATE(LLM_C00R_TEXT)[LLM_STATE_R0W]MSTATE(LLM_COOR_TEXT)[LLM_STATE_C0L]

To retr ieve the pixel-based X and Y c oordinates , you w ould use:

MSTATE(LLM_C00R_GRAPH)[LLM_STATE_X]MSTATE(LLM_COOR_GRAPH)[LLM_STATE_Y]

Compil ing and LinkingAs mentioned earlier, all of the constants utilized by the graphicmode functions are defined in Llibg.ch, so it is important thatyou includ e this f i le in your applicat ion— otherw ise, any funct ionor command cal l involving constants beginning with LLG_ orLLM_ cannot be compiled.

On ce your ap plicat ion is successful ly com piled, you can l ink i tusing any linker, including either the default, protected mode

linker, CA-Clipper/Exospace; the real mode l inker, Blinker; orany other linker. The graph ic mod e functions are defined in thel ibrary, LLIB G.LIB , wh ich is automatical ly l inked if you areusing CA-C lipp er/E xo spa ce. I f you are using any other l inker( including Blinker) , you m ust include LLIBG .LIB in your l inkerscript.

Important If you choose to ignore default libraries usingCA-Clipper-/Exospace (using the NO DEFLIB option) or use anotherlinker, make sure you link LLIBG.LIB before CLIPPER.LIB.Otherw ise, your application will not function properly in g raphicmode.

5-10 CA-Clipper



Managing Bi tmap and Font Resources


CA-Clipper 5.3 provides several utili t ies for managing anapplication's resources (such as bitmap and font files) using asingle bitmap library (.BML) file. This section describes all ofthese utili t ies and provides an overview of how .BML files areautomatical ly handled by your applicat ion.

RES2BML.EXE

Use RES2BML to create a library file to store the individualresources (such as bitmap and font files) used by yourapplication.

Storing resources in a single .BML file rather than individual fileshas the advantage of making your application easier to deliver toend users—instead of delivering a single .EXE file with 40 .BMPfiles, for exa m ple , you d eliver only two files: an .EXE and a.BML containing all the necessary .BMP files.

To invoke this utili ty, use the following syntax:

RES2BML <inputFileSpec list> <bmlFile>

<inputFileSpec list> is a list of file specifications to define theinput files, which are limited to .BMP, .FND, and .FNT fileform ats. Each file specification can conta in wild card ch arac ters,such as " ? " and "* ." If you specify mo re than one filespecification, separate them using a single space.

N o t e : In CL IPP ER .BM L, some bi tmap f i les have an extension of.BM U. The se files are simp ly renam ed .BM P files, and they wrorkproper ly wi th RES2BML.

<bmlFile> is the na m e of the resulting library file. The file nam ethat you choose should have the same base name as thecorresponding .EXE file, but with a .BML extension.

Important At runtime, the .BML file must be present in the samedirectory and must have the same base name as its corresponding .Efile. Otherw ise, the application will not be able to locate the .BML





For exam ple, if your executable f i le is M YA PP.E XE and you ha veseveral .BMP fi les with " M Y " as the pref ix, you wo uld type thefol lowing:

RES2BML MY*.BMP MYAPP.BML

Likewise, to include both bitmap and fonts in the resultinglibrary file, you would use syntax similar to the following:

RES2BML A*.BMP H*.FNT *.FND MYAPP.BML

BML2RES.COM

Use BML2RES to extract the original resource files from a .BMLfile previously created with RES2BML.


BML2RES <bmlFile>

<bmlFile> is the na m e of the library file wh ose contents you wan tto extract. All bitm ap and font files contain ed in this file will beextracted and recreated on disk.

BMLDIR.COM

Use BMLDIR to view the contents of a .BML file previouslycrea ted wi th RES2 BM L.


BMLDIR <bmlFile> [ | more ]

<bmlFile> is the na m e of the library file wh ose contents you w antto view . Use the vertical pipe and m ore filter if the entriesexceed the number of available rows on your screen and youwan t to pause betw een g roups of entr ies .

5-12 CA-Clipper

http://bml2res.com/

http://bmldir.com/

http://bmldir.com/

http://bml2res.com/




Using Bitmap and Font Library Files

The GBMPLOAD() and GFNTLOAD() func t ions a re des igned towork with resources that are stored in individual files or in a.BM L file . W hen y ou invoke ei ther of these funct ions, theappl icat ion automatical ly searches for the nam ed resource in thefol lowing order:

1. In a file with the sam e na m e as you r execu table but with a.BML extension

2. I n CLIPPER .BML

N o t e : The bi tmap l ibrary fi le , CL IPP ER .BM L, contains al lthe resources and fonts used by CA-Clipper to display itsuser interface com pone nts . (See App endix A fordescript ions of the bi tma ps an d fonts suppl ied inCLIPPER.BML. )

3. As a sep arate disk file

Important All .BML files and resources must be located in thedirectory where the .EXE is running .

This strategy is very powerful and easy to use. In thedevelopment phase, you can work with individual bi tmap andfont files. When you are ready to distribute your application, useRES2BML to create a s ingle .BML fi le f rom the separateresources. Because the graphic mod e funct ions are designed towo rk with both l ibrary and individual resource f i les , no sourcecode changes a re needed

Pro gram ming a n d Uti lit ies Gu ide 5-13



Troubleshooting

Troubleshooting

This section suggests ways to resolve certain problems that canoccur when you execute your CA-Clipper appl icat ion in graphicmo de. Exam ine this sect ion for solut ions to com mo n problemsbefore you cal l for Com puter A ssociates Technical Sup port .

Common Problems

Listed below are a number of common problems that you mayhave programm ing in graphic mode:

• "My application won 't go into graphic mode."

Either the application is not being linked with LLIBG.LIB orCLIPPER.LIB is before LLIBG.LIB in the l ink order.

This may also occur if your video card is not 100 percentVE SA 1.2 compatible . Please check your video cardma nufacture r 's specif ications. Also, other add-ons orcustom rout ines which manipulate the video output may becausing the problem, including:

- Non -VGA s tandardThe video card is not supported be cause i t is non-V GAstandard.

- VESA

Graphic mode is designed to work with 100 percentVE SA -com patible graphics cards. I f your graphics cardis not 100 percent compatible or only SVGA-compatible ,you may experience problems when switching to somevideo modes or even when displaying. We provide

UNIVESA, which is a TSR to help make your video cardVE SA -com patible . See Hard ware Compatibi l i ty la ter inthis section for further information.

5-14 CA-Cl ipper



Troubleshoot ing

"M y mouse wont load.

This may be caused when using an older mouse driver.Please see the MSTATEQ function for further information.

Why am I getting conflicts w ith INT10/INT25 when usingCA-Clipper Tools even though I do not link CTU SP?

This problem occurs only with a few CA-Clipper Toolsfunct ions— mainly the netw ork funct ions. These funct ionsrely on some data segments s tored inside the CA-Clipper GTmo dule , even though these data segm ents are not used. Asmost graphics libraries replace the GT module, this datasegm ent is no longer ava ilable at the requ ired location. It isnot important under real mode linking because the

CA-Clipper Tools functions will access irrelevant data.However, under protected mode, this inval id data accesscauses a GPF.

Can I define the button coordinates on the screen w ith pixelaccuracy, as opposed to an 8 χ 16 grid defined by regular textmode?

Yes , any bitmap (.BMP) or icon (.ICO) file can be displayedat the pixel level and, additionally, the .BMP file sizes are notlimited to 64 KB.

Can I save and restore numerous screen areas to memory for icoand overlaid windows?

The CA-Clipper VMM allows you to save whatever youwan t . Und er protected mod e, you wil l benefi t from very fastme mo ry handling. Ho we ver, saving a screen is a veryresource-greedy thing to do when in graphic mode.

Instead, you can implem ent an exclusion regions algori thmthat allows most of the overlaid window operations to beexecuted without any need for the SAVESCREEN() and

RESTSCREEN() func t ions .For example, imagine you have a window with a TBrowseobject and a second window which part ial ly overlaps theTBrow se. By issuing a GSE TEX CL () to the second w ind ow 'scoordinates , repaint ing the TBrow se in the fi rs t wi ndo w wil lnever a ffec t the "exc lude d" window . See The Graphic Mod eTechnique earlier in this chapter for details.




Troubleshooting

Software Compatibility

In regard to third-party software packages, you cannot mixmu ltiple graphic libraries in the sam e application. Ad d-onproducts that might conceivably cause com patibi l ity problemsare those that add or change CA-Clipper behavior with respectto terminal-handling functions.

You cannot use another library to switch your CA-Clipperapp lication to 640 χ 480 χ 16 VG A m ode an d use the graphicm od e GLIN E() function. Even thou gh it ma y result in a linebeing drawn on the screen, your graphic settings will not becorrect.

Graphic mode does not s imply switch the video mode when youcal l SET VID EO M OD E. A series of environm ent set t ings, such asSETMODE(), mouse s ize conversion, and so on, are updated.These values would not be properly set if you use another libraryto switch to graphic mode instead of cal l ing SET VIDEOMODE.Mixing two graphics libraries is thus very likely to causeproblems, and you wil l usual ly end up rebooting your PC

For libraries that claim to "do everything," our advice is lesssimp le. If the library is pro perly o rganiz ed, i t should be possib leto use all of the non-graphic portions, along with graphic mode,without problems.

In general , beware of shadowing funct ions developed forCA-Clipper using C or Assembly language. These wereintended for text mode in which a screen is described in terms ofchara cter /at t r ibu tes . In graphic mode , shadow ing is notaccomplished in the same way as it is in text mode (seeShadowing Restrictions earlier in this chapter).

5-16 CA-Cl ipper



Troubleshooting

Hardware Compatibility

Processors The graphic mo de l ibrary was deve loped in C and Assem blylang uag es. For exec ution spe ed, it uses instructions that are onlysuppo rted by 80286 and later processors . An executable f i lel inked with graphic mod e wil l , therefore, not work on com pute rsusing 8088 or 8086 processors.

VGA Drivers Gra phic m od e wo rks with vide o cards that either con form to orperfect ly emulate the VGA standard.

VESA Drivers Gra phic m od e also wo rks with VE SA vid eo mo de s. It is VE SA1.2 compatible , which means the video hardware must be

compatible with the VESA 1.2 s tandard. However, many videocards (both older and recent) are not fully compatible with VESA1.2—these may be compatible with VESA 1.0 or the SVGAstandard.

You need a ful ly VESA VBE-compatible video card in order touse the VESA modes. Graphic mode supports resolut ions of 640χ 480, 800 χ 592,1024 χ 768,1280 χ 1024, and provides colorsup por t for 16, 256, 32 K B, 64 KB , and 16 million colors. (On ly640 χ 480 resolut ion w ith 16 colors is supplied w ith CA -Clipp er.)No d river is required i f your video card is com patible with VE SAV B E . Othe rwise , you should use the driver supplied with yo urvideo card. The driver should be opt imized for your card by themanufac turer.

If no driver was supplied by the manufacturer, use UNIVESA,which is a TSR shareware program that is included withCA -Cli pp er. (If U N IV ES A is not able to install i tself, you r card isprobably not VESA-compatible .)

Wh en you load the UN IVESA dr iver, i t overcomes some VE SA

1.2 shortcomings in the hardw are with software algori thms. Thisal lows graphic m ode to see the video hardw are as ful lycompatible with VESA 1.2.

Program ming an d Utilities Gu ide 5- 17



Troubleshooting

UN IVE SA is universal , so it should run on all hardw are.However, sometimes you may be able to load UNIVESA andaccess new video modes and stil l get poor results whenswitch ing to high resolu tion mo de s. In this case, you should tryto use the VESA driver from the card manufacturer.

Memory Shortage

Graphic mode uses the VMM to al locate the memory i t needs,taking care to free that memory after each call .

H ow ev er, there are limits to wh at is possible in CA -Clip per. Forexa mp le, a 640 χ 480 screen w ith 16 colors takes mo re than

150 KB of me mo ry. If you have enou gh EM M me mo ry, savingthe screen wil l be fast ; but wh enev er the VM M n eeds to swap todisk, perform ance w il l suffer.

When you use TBrowse objects , GET commands, or any othertype of display within an application, the display time amountsto a small percentage of the total processing time. Increasing thisprocessing time a li t t le will not be noticed by your user.

5-18 CA-Clipper



Chapter 6

Introduction to TBrowse


TBrowse is one of several predefined classes included inCA-Clipper designed to give you control and flexibility in the

retrieval, display, and editing, the browsing, of tabular view s ofdata. I t provides a robust , open-archi tecture brow singmechanism that is not tied to the (.dbf), or any other, file format.

This chapter establishes criteria for effective use of the TBrowseclass . It starts with creation of a TB row se object and adescript ion of the TBrow se class , cont inues w ith informationabout the most common uses of TBrowse and TBColumn objects ,and concludes by out l ining problems and establ ishing guidel inesfor their resolution.

This chapter discusses the following topics:

• TBro wse overview

• Basic brow se operat ions

• Optim izat ion of the brow se

• Brow sing with Get

• Add ing color

• Con trolling the scope

N o t e : This chapter assum es that you are familiar with theconcepts and terminology associated with CA-Clipper 'spredefined classes as discussed in the "Basic Co nce pts" chap terof this guide .




TBrowse Overview

TBrowse Overview

To unders tand T Brow se , you mus t unders tand w hat it does not

do as well as what i t does. TB row se is a pass ive object in thesens e that i t nev er initiates an action. It nev er takes control fromthe programmer for more than a few moments , never, withoutexpl ici t direct ion, handles a s ingle keystroke, and never "ends."You sim ply s top using i t wh en you are done with it . TBro wse isa data source access tool that can browse any data that isexpressible in a table form .

TBrowse differs f rom the CA-Clipper funct ions DBEDIT() ,MEMOEDIT() , and ACHOICE() , in i t s degree of exclusive control.The funct ions con trol al l screen and data manip ulat ion withoutregard to the activation that calls them . TB row se, on the otherha nd , ope rates as a tool of the calling activation. Tha t activationcontrols and orders the action of the TBrowse object by sendingmessages to it .

TBrowse is not a replacement for DBEDIT() ( though, internal ly,DB ED IT() is wri t ten using TBrow se) . TBro wse is less limit ingand mo re pow erful than any of the funct ions. Due to the natureof objects under TBrowse, you can act ivate several s imultaneousbrow ses which can be suspen ded and restar ted at wil l . TB row se

can be read-only or interact ive.

6-2 CA-Clipper



Basic Browse Operations


Regard less of the nature of the data on which you use T Brow se,you should use the sam e general approach . The f i rs t exam ple isthe simplest of all cases , a read-o nly bro w se of a data base . Itstarts with creation of the TBrowse object and design of the mainTBro wse lo op, then continues through stabi l izat ion andkeystroke handling on a monochrome display.

Cre ating TBrowse O bjects

The browse is composed of two different object c lasses: TBrowse,

the main class, which controls the overall browse, andTBColumn, of which each column is an instance, and which is'owned' by the TBrowse object .

C re at e a TBrowse Th ere are two func tions for creating a TB row se object:Ob jec t TBrowseNew ( ) and TBrowseDB() .

TBr ow seN ew () creates a com pletely generic TBro wse object. Thefollowing code creates a new TBrowsc object and stores it in thevar iab le , oBrowse. The coordinates define the rectangular area of

the TBro w se object :oBrowse := TBrowseNew(<nTop>, <nLeft>, ;

<nBottom>, <nRight>)

TBro wse DB () has the same syntax as TBrow seNe wQ . I t creates aTBro wse object with defaul t code blocks to locate and p osi t ionthe data source within a database. In other w ord s, the TBro w seobject i t creates is customized for browsing a (.dbf).

Pro gram ming a n d Utilit ies G uid e 6-3




Add Columns Ne xt , add colum ns to the brow se by creat ing TBC olum n objects .This is a two-step proc ess. Firs t create the TBCo lum n o bject ,then add the column to the TBrowse object :

oCol := TBColumn New("Rec ord #", {|| RECN0()})oBrowse:addColumn(oCol)

This example, using TBrowseDB(), creates one object for everyfield in the database in the currently selected area:

// StockBrowseNew()/ /// Create a stock TBrowse object for the// current work area

FUNCTION StockBrowseNew(nTop,nLeft,nBottom,nRight)LOCAL oBrowse, n, oCol

// Start with a new browse objectoBrowse := TBrowseDB(nTop,nLeft,nBottom,nRight)

// Add a column for each fieldFOR η := 1 TO FC0UNT()

// Make a new columnoCol := TBColumnNew(FIELD NAME(η), ;

FIELDWBLOCK(FIELDNAME(η), SELECT()))

// Add a column to the browse objectoBrowse:addColumn(oCol)

NEXTRETURN oBrowse

Main Loop

The m ain loop of the brow se is very s traightforward; s tabil izethe brow se (ex plained bel ow ), get a keystroke , act on thekeystrok e, then repeat the process. I f the keystroke happ ens tobe an exit key (in this case , Esc ), exit the loop and return. W he nyou exit the loop, the reference to the TBrowse object, since itwas held in a local variable, falls out of scope, and the system

autom atical ly reclaims the space u sed by the object .

6-4 CA-Clipper




The relevant code looks like this:

// Define exit keyoBrowse:setKey(K_ESC, {| | TBR_EXIT})

// Main loop of the browse objectlMore := .T.DO WHILE lMore

// Stabilize the browseoBrowse:forceStable()

// Positioned at top or bottom of browseIF oBrowse:hitTop .OR. oBrowse:hitBottorn

TONE(125, 0)END IF

// Get a new keystrokenKey := INKEY(0)

// Act on the keystroke

lMore := (oBrowse:ap plyKey(nKey) = TBR_EXIT)

ENDDO

Stabil ization

To permit greater control , TBrowse does not update the screenimm ediately w hen m essages are sent to it . Instead, it waits u nt i l

the object is stabilized with TBro wse:stabi l ize() . W hen thatme ssage is received, the brow se is s tabi l ized in cremen tal ly,displaying on e change at a t ime. For examp le, w hen theTBr ow se object is created, it is not imm ediately d isplayed o n thescreen. Th e first t ime a TB row se object receives a stabilizemessage, i t displays the headers; then every time stabilize isreceived, i t displays one record until everything is finallydisplayed . (W hen everything is display ed, TBrow se:stabi l ize()returns t rue (.T.)) Mu lt iple brow ses are, therefore, displaye d "insync/ ' and the redraw of the screen can be interrupted by akeystroke.

In this examp le, w e do nothing du ring the s tabil izat ion pro cessexcept maintain a s imple loop that forces comp lete s tabi l izat ionby cal l ing TBrow se:forceStable() . Internal ly, this me thod cal lsTBrowse:stabilize() until i t returns true (.T.):






Handl ing Keyst rokes

The most efficient way to handle keystrokes is to useTBrow se:applyKey() . M any of the most comm only used

keystrokes are predefine d. For exam ple, K_ DO W N map s toTBrowse:down() , and K_PGDN maps to TBrowse:pageDown()(refer to the TBrowse class in the Reference Guide for a completel is ting of the defaul t keystroke m app ings) .

Using TBrowse:setKey() , however, you maintain total controlover these ma ppin gs. Yo u can add new o nes, as i l lustrated inthe code for the main loop which defines the K_ESC key in thism ann er, and you can mo dify or delete the values for predefinedkeystrokes to sui t your own needs.

TBrowse:applyKey() and TBrowse:setKey() el iminate the need toprocess keystrokes via a procedure or function that is necessarilyexternal to the TBrow se object , giving your browser a greaterdegree of encapsulat ion.

6-6 CA-Clipper



Optimization of the Browse


A minimum browse like the example is barely useful and youshould consider the values of constructing a more robustproduction browse. These additional operations optimize a

browse for single or multi-user environments and includereduction in response time, creation of calculated fields, pictureclauses and custom headers, explicit record pointer control, anduse of the TBrowse:cargo and TBColumnrcargo instancevariables.

Calculated Fields Picture Clauses and Custom Headers

This function adds a record number column to the passedbrowse and formats it with commas. It illustrates how to useTRANSFORMQ in a data retrieval block to apply a picture to acolumn:

// AddRecNo()//// Insert a column at the left that shows// current record number formatted with commas

PROCEDURE AddRecNo(oBrowse)LOCAL oCol

// Create the column object with custom header// Use TRANSFORM() to apply picture clauseoCol := TBColumnNew("Record #", ;

{ TRANSFORM(RECN0() , "999,999, 999") })

// Insert it as the leftmost columnoBrowse:insColumn(1 oCol)

RETURN

Programming an d Utilities Guide 6 7




Q uicke r Response Time

Often, you want to le t the user page through a database or othertable quickly. Previo us exam ples have forced the user to wait

unt i l the screen redraws before they can mo ve again. Thissignif icant ly s lows user operat ions.

Fortunately, you can easi ly reduce the response t ime byinterrupting the stabilize loop. You do this, as il lustrated in thenext example, by cal l ing TBrowse:stabi l ize() in the main loopinstead of relying on TBrowse:forceStable() . You should,however, use care with this approach.

Certain TBrowse operat ions and instance variables are val id onlywith a stable bro w se, wh ich you can test for using theTBrowse:stable exported instance variable, a lso i l lustratedbelow:

// Interrupting the stabilize loop

// Define exit keyoBrowse:setKey(K_ESC, {|| TBR_EXIT})

lMore := .Τ.DO WHILE lMore

// Stabilize the browse until it's stable or// a key is pressednKey : = 0DO WHIL E nKey = = 0 .AND. oBrowse:stableoBrowse:stabilize()

nKey := INKEY()ENDDO

IF oBrowse:stable// positioned at top or bottom of browse// (these values only valid if stable)IF oBrowse:hitTop .OR. oBrowse:hitBottorn

TONE(125, 0)END IF


END IF// Act on the keystroke

lMore := (oBrowse:applyKey(nKey) = TBR_EXIT)

ENDDO

6-8 CA-Clipper




Multi-User Issues

TBrowse buffers all cells for the currently displayed row

(whether the cells are visible or not). While this gives a goodperform ance bo ost , it me ans that wha t is on the screen may notma tch wha t is in the database. For exam ple, in a mult i -userapplicat ion another user may have deleted or otherwisemodif ied one of the displayed records.

Rather than verifying that everything on the screen is current(which might be impossible and would certainly be s low),mo dify the brow se to ensure that the current record is up-to-d ateusing TBro w se:refreshCu rrent() . Im med iately af terward s,s tabi lize the brow se. The fol low ing l ines of cod e, insertedimmediately before you get the keystroke in the previousexam ple, do just this. No te that the placem ent of this codewithin the IF oBrowse:stable. . .ENDIF construct is important ,because it ensures that the browse is stable; otherwise, thecurrent row is undefined.

IF oBrowse:stable

// Ensure that the current record is showing// up-to-date da ta (e.g., on a network).

oBrowse:refreshCurrent()oBrowse:forceStable()


END IF





Repositioning the Record Pointer

TBrowse is a general-purpose browser unaffected by theund erlying data format . W hile this is useful in ma ny cases, there

are times when it means that a li t t le more work is necessary onthe pro gram m er 's part . On e of these cases is w hen the recordpointer is reposi t ioned outside the control of TBro wse (whenseeking a new value, for example) .

When a TBrowse stabilizes, i t tries to leave the same cellhigh ligh ted as befo re. Tha t is, i t tries to keep the highlig ht at thesam e posi t ion within the brow se win dow unless i t is expl ici t lymo ved by an up or dow n message. The TBrow se posi t ions thedata source corre spo nd ingly . If there are not enoug h rows left inthe data source (that is, end of file is encountered while trying toadjust the database to match the window), the TBrowse movesthe cursor up w ard , leaving i t on the correct record, but with p artof the window unfi l led.

This behavior is appropriate for logical end of file, but a problemoccurs when something outside of TBrowse moves the recordpointer so close to the logical beginning of file that i t isimpossible to highlight the correct record while leaving thehighlight at its previou s posi t ion within the win dow . In thiscase, TBrow se leaves the highl ight in the sam e posi t ion w ithin

the window, even though that posi t ion no longer corresponds tothe sam e record as befo re. Tha t is, i t repo sitions the database asfar as it will go, then leaves the high light w her e it w as. Theresult is the highlight on a different record than the one justedi ted.

You can correct this behav ior by forcing a complete refresh(through T Brow se:refreshAll()) , and a ful l s tabi lizat ion.CA-Clipper then checks for reposi t ioning of TBrowse to adifferent record than before. I f so, CA -Clipp er assum es the old

record is some wh ere a bove the current record, and a ser ies of upmes sages are issued to the brow se to mov e the highl ight to theprop er posi t ion. Determ inat ion of proper posi t ioning of thehighl ight varies depen ding on what is being brows ed. You m usthave som e way of determining the exact row posi t ion. In thecase of databases, use the record number or the index key, if i t isunique.

6-10 CA-Clipper




This function is called from a keystroke h andler that promp ts fora key value to search for wh en you type Alt+ S. The fol lowingexample correctly repositions the highlight by using the record

number :// SearchBrowse()//// Search browse on key field with SEEK// and adjust highlightPROCEDURE SearchBrowse(oBrowse)

LOCAL cSaveScreen, xSearch, nRe c, GetList := {}// Ensure browse is stable before getting info// about current recordoBrowse:forceStable()// Get current key value and record numberxSearch := &(INDEXKEY(0))nRec := RECNO()// Put prompt online surrounding browsecSaveScreen := SAVESCREEN(oBrowse:nBottom + 1 , ;

0, oBrowse:nBottom + 1, MAXCOL())SETPOS(oBrowse:nBottom + 1, oBrowse:nLeft + 2)DISPOUT("[Search For ")@ RO W O , C OL O GET xSearch PICTURE "@K"DISPOUT(" ] " )READRESTSCREEN(oBrowse:nBottom + 1 , 0, ;

oBrowse:nBottom + 1, MAXCOL(), cSaveScreen)IF UPDAT ED() .AND. (LASTKEY() = K_ESC)

SEEK xSearchIF SET(_SET_SOFTS EEK) .AND. FOUND()

// Don't allow search to throw me to// end of fileGOTO nRecALERT(xSear ch + " not found.", {"OK"})

ELSE// Record pointer was moved. Save new// location, refresh browse, then move// highlight to proper position// Ensure I have a valid recordIF EOF()

GO BOTTOMEND IF

nRec := RECNO()oBrowse:refreshAll()oBrowse:forceStable()DO WHILE RECNO() = nRec

oBrowse:up()oBrowse:forceStable()

ENDDOEND IF

END IFRETURN





Using TBrowse:cargo and TBColumn:cargo

Som etime s i t is desirable to track mo re information about thebrow se or its colum ns than the brow se i tself tracks. To let you

do this , CA-Clipper defines the cargo exported instance variablein all of its classes. It is called " ca rg o " becaus e it is just "alo ngfor the r ide." Carg o can hold data of any type.

If you have c om plete con trol over the objects , you can u se cargoin any way you desire . This examp le makes the preprocessorcode easier to understand:

// These #defines use the browse's cargo slot to// hold the "append mode" flag for the browse.// Having #defines for these makes it easy to// change later.

#define TURN_O N_APP END_MO DE(b) (brcargo := .T.)#define TURN_O FF_AP PEND_ MODE(b ) (bicargo := .F.)#define IS_APPEN D_MODE(b ) (bicargo)

Dictionaries If, on the other ha nd , yo u are not in com plete contro l of theobjects (that is, you are writing general purpose routines forothers to use) , w e strongly reco m m end that you use cargo as adict ionary, as implemented in the Dict .prg sample program(located in you CA-Cl ipper SOU RC E\S AM PLE di rectory). Thisal lows several programmers to use cargo without confl ict , andwithout any change in the source code.

Dict ionaries pro vide a w ay of associat ing a key with a value, asin a real dictionary, where the word you look up (the key) isassociated w ith a part icular defini t ion ( the value) . No te that theentries in data dictionaries have no particular order.

6-12 CA-Clipper



Browsing with Get

This example uses a data dict ionary to s tore the append mode.Because the dictionary is created and ev aluated at runtim e, anynumber of modules can use the dict ionary without knowledge of

how other mod ules are using i t:// Using a dictionary/ /// Use a dictionary to hold cargo information.// Require s that Dict.obj be linked in to work .

// Create new dictionaryoBrowse : cargo := D ic tNe wO

// Turn on append mod eDictPut(oBrowse:cargo, "APPEND", .Τ.)

// Turn off append modeDictPut(oBrowse:cargo, "APPEND", .F.)// Check append modeDictAt(oBrowse:cargo, "APPEND")

Browsing with Get

Browsing is more than read-only screens and pulldown menus.You can, for instance, create a popup edit screen or edit the fieldsin place. Using the Get system, you have unprecedented accessto your data, but you are responsible for integrating the systeminto an applicat ion and control l ing movement through the datasource.

Though, at first, editing the browse fields / /i n -p l ace, / may seeman impo ssible task, it is actua lly quite easy. This discu ssioncovers two different methods.

The f irs t , and probably simplest method, employs cargo.

Prog ram m ing a n d Utilities G uid e o- l 3



Browsing with Get

This example, a modification of the basic TBrowse object creationcode , places the field name for the created objects into theTBColumnxargo ins tance var iab le :

// Inserting a column's field name into oCol:cargo

#define SET_FIELD_NAME(c, f) (c :ca rg o := f)#define GET_FIELD_NAME(c) (c:ca rgo )

// StockBrowseNew()//// Create a stock TBrowse object for the// current work area

FUNCTION StockBrowseNew(nTop,nLeft,nBottom, nRight)LOCAL oBrowse, n, oCol

// Start with a new browse objectoBrowse := TBrowseDB(nTop,nLeft,nBottom,nRight)

// Add a column for each fieldFOR η := 1 TO FC0UNT()

// Make a new columnoCol := TBColumnNew(FIELD NAME(η), ;

FIELDWBLOCK(FIELDNAME(η), SELECT()))

// Store the field name with the columnSET_FIELD_NAME(oCol, FIELDNAME(n))

// Add the column to the browse objectoBrowse:addColumn(oCol)

NEXTRETURN oBrowse

6-14 CA-Clipper



Browsing with G et

By placing this f ield name into TBColumnxargo instancevariable, the question of when to edit the field becomes a simplematter :

/ / DoGetO/ /// Get current cell using cargo macro method

PROCEDURE DoGet(oBrowse)LOCAL oCol, cField, nCursSaveMEMVAR GetList

// Ensure browse is stableoBrowse:forceStable()

// Get current columnoCol := oBrowse:getColumn(oBrowse:colPos)

// Get field name from columncField := GET_FIELD_NAME(oCol)

// Turn cursor onnCursSave := SETCURSOR(SC_NORMAL)

@ ROW(), COL() GET &cField PICTURE oCol:picture ;WHEN oColrpreBlock VALID oCol:postBlock

READ

// Restore cursorSETCURSOR(nCursSave)RETURN

Pro gram min g a n d Utilities Gu ide 6-15



Browsing with G et

A m ore eff icient wa y to accomp lish the same thing takesadva ntage o f the fact that the TBC olum n:block and the Getclass 's Get:block can be compatible . Using this me thod , you canmanipulate the Get direct ly:

/ / DoGetO/ /// Get current cell using GetNew( ) method

PROCEDURE DoGet(oBrowse)LOCAL oCol, oGet, nCursSave



// Create Get at current cell positionoGet := GetNew (ROW() , CO L ( ) , oCol .-block, ;oCol:heading, oCol:picture)


// And do READREADMODAL({oGet})


Determining Whether the Record Has M ov ed

As discussed earl ier under Reposi t ioning the Record Pointer,indexes can cause prob lems in s imp le code exam ples. I f youchange the key field of a particular record, i ts relative position inthe database m ight also chang e, requir ing yo u to refresh thedisplay.

It is relatively easy to determine if this is necessary by evaluating

the index ke y befo re and after the read . If i t ha s, refresh thescreen.

6-16 CA-Clipper



Browsing with Get

Here is the previous example, with the proper code added:

/ / DoGetO/ /

// Get current cell using Ge tN ew O method and// update TBrowse correctly whe n key field is// changed

PROCEDURE DoGet(oBrowse)LOCAL oCol, oGet, nCursSave, xOldKey, nRec


// Indexes key expression, macro returns the// value of the expression for the current// recordxOldKey := &(INDEXKEY(0))nRec := RECNO()


// Create Get at current cell positionoGet := GetNew(ROW(), COL() , oColiblock, ;

oCol:heading, oCol:picture)


// And do READREADMODAL({oGet})

// See if index key has changedIF (&(INDEXKEY(0)) == xOldKe y)

// Force refresh, and reposition highlight if// ne cessaryoBrowse:refreshAll()oBrowse:forceStable()DO WHILE RECNO() = nRec

oBrowse:up()oBrowse:forceStable()

ENDDOEND IF


Tip: To adapt this code to a mu lt i -user environm ent , apply arecord lock immediately after the first call to forceStable()and unlock af te r the cal l to RE AD M OD AL Q.




Adding Co lo r

Adding Color

Thou gh the previous examples have been for m onochrom edisp lays, the TB row se class also gives contro l over color. Thesimp lest way to add color to a TBro wse object is to SET CO LO RTO the desired s tandard and enhanced colors . The headers ,footers , and colum ns w il l be displayed in the s tandard color, andthe highl ight wil l be in the enha nced color. Ho w ever, a mo recomplex use of color requires an understanding of therelat ionships between the various exported instance variablesthat control color.

TBrowse:colorSpec

Just as CA-Clipper maintains a color table using SETCOLOR() todetermine the colors of display objects , TBrowse maintains acolor table using TBrowsexolorSpec for i ts own use.

When unspecif ied, TBrowsexolorSpec defaul ts to the value ofSETCOLOR() at the t ime the TBrowse object is created.

A typical TBrowsexolorspec assignment looks l ike:

oBrows e:colorS pec := "N/W, N/BG, B/W, B/BG, R/W"oBrowse:colorSpec += ", R/BG, G/W, G/BG"

TBro w sexolo rSpec , un l ike SET CO LO R() , impl ies no spec if icm ean ing by the order in w hic h colors are listed. Instead , all ofthe other color-related instan ce variables and m ethod s refer tocolors as indexes into TB row sex olo rSp ec. In the exam ple above,co lor one is N /W , co lor two i s N /B G , and so on .

In actual usage, colors are expressed as an array of up to foursuch indexes, cal led a color array. These are the norm al ,

hig hlig hted , hea de r, and footer colors for the particu lar cells youare w orkin g w ith. The array {3, 4, 3 , 3}, assum ing theTBrowsexolorSpec l is ted above, represents a normal color ofB / W , a highl ighted color of B /B G , and header and footer coloro f B / W.

6-18 CA-Clipper



Adding Co lo r

TBColumn:defColor

TBrowse lets you set column colors individual ly through theTBColummdefColor instance variable. The f i rs t , or normal , colorin the TBColumn:defColor color array determines the color ofthe data values; the highlighted color determines the color of thehighlight when it falls on this column; the third and fourth colorsdeterm ine the header and footer colors . TBC olum n:defC olorde fau l t s t o {1 ,2 ,1 ,1} .

This code displays every data type in a different color:

// FancyColors()//

// Display each data type in a differe nt colorPROCEDURE FancyColors(oBrowse)

LOCAL nCol, oCol, xValue

// Set up a list of colors for the browse to useoBrows ercolorS pec := "N/W, N/BG, B/W, B/BG, R/W"oBrowse :colorSp ec += ", R/BG, G/W, G/BG"

// Loop through the columns, choosing a// different color for each data typeFOR nCol := 1 TO oBrowse:col Count

// Get (a referen ce to) the column

oCol := oBrowse:getColumn(nCol)// Get a sample of the underlying data by// evaluating the code blockxValue : = EVAL(oCol:block)

DO CASECASE VALTYPE(xValue) == "C"

// Characters in blackoColidefColor := {1, 2, 1, 1}

CASE VALTYPE(xValue) =^ "N"// Numbers in blueoColrdef Color := {3, 4, 3, 3}

CASE VALTYPE(xValue) == "L"// Logicals in redoCol:defColor := {5, 6, 5, 5}

OTHERWISE// Dates and others in greenoCol :def Color := {7, 8, 7, 7}

ENDCASENEXTRETURN




Adding Co lo r

TBColumn:colorBlock

TBrowse lets you highlight the color of individual cells based onthe value retr ieved by TB Co lum n:block ( the data retr ieval block)using TBC olu m nxo lorB lock . This code block is passed the resul tof the data retrieval block and returns a color array.TBColumn:colorBlock overr ides the TBColummdefColor for thecolum n. This is valuab le in a num ber of s ituat ions, a few ofwhich are il lustrated in the examples to follow:

In this exam ple, negat ive num bers are displayed in red:

// FancyColors()/ /// Display negativ e number s in a different color

PROCEDURE FancyColors(oBrowse)LOCAL nCol, oCol, xValue

// Set up a list of colors for the browse to useoBrowse:c olorSpec := "N/W, N/BG, R/W, W+/R"

// Loop through the columns, set up default, and// force columns to display negative #s in redFOR nCol := 1 TO oB rowse:colC ount

// Get (a reference to) the columnoCol := oBrowse:getColumn(nCol)

// Get a sample of the underlying data by// evaluating the code blockxValue := EVAL(oCol:block)

// Default coloroCol:defCol or := {1, 2, 1, 1}

IF VALTYPE(xValue) == "N"// Negative numbers in redoCol :col orB lock := {|n| IIF(n < 0, ;

{3, 4 } , {1, 2}) }END IF

NEXTRETURN

6-20 CA-Clipper



Adding Co lo r

This example displays cel ls in random colors:

// FancyColors()/ /

// Display cells in random colorsPROCEDURE FancyColors(oBrowse)

LOCAL nCol, oCol

// Set up a list of colors for the browse to useoBrowse :colorSpe c := "B/W, W/B , R/W, W/R, " + ;

"G/W, W/G, GR/W, W/GR, W/BG, BG/W, N/W, W/N"

// Loop through the columns, setting up lines to// display in alternating colorsFOR nCol := 1 TO oBrowse:colCount

// Get (a referenc e to) the columnoCol := oBrowse:getColumn(nCol)// Default coloroCol:defC olor := {1, 2, 1, 1}

// Ignore the value of the cell and choose// color for column based on the time at// which the block is executedoCol:colorBlock := {|x| RandColor(6)}

NEXTRETURN

// RandColor()/ /

// Return color based on time

FUNCTION RandColor(nSets)LOCAL nSelector

// nSets is the number of color arrays availablenSelector : = (SECONDS() * 10) % nSets

RETURN {(nSelector * 2) + 1 , ;(nSelector * 2) + 2 }




Adding Color

Controlling the Highlight

By defaul t , TBro ws e turns the highl ight on and off. TBro wsegives you complete control over when and where the highl ightappears through TBrowse:autoLite , TBrowse:hi l i te() , andTB row se:de Hi lite(). If TB row se:au toL ite is true (.T.), the defaultset t ing, TBrow se au tomatical ly turns the highl ight on and off .

In the example under Reposi t ioning the Record Pointer, you cansee the highlight flicker as the necessary adjustment takes place.You can correct this by changing the searching function to turnoff automatic highlighting before and turn it on after themovement is done. The fol lowing code fragment i l lustrates:

IF SET(_S ET_SOF TSEEK) .AND. FOUND()

ELSE

nRec := RECNO()oBrowse:refreshAll()

// Turn off highlighting while movement is// taking placeoBrowse:autoLite := .F.oBrowse:deHilite()

oBrowse:forceStable()

DO WHILE RECNO() = nRecoBrowse:up()oBrowse:forceStable()

ENDDO

// Turn it back on now that we are doneoBrowse :autoLit e := .T.

END IF

6-22 CA-Clipper



Adding Color

TBrowse:colorRect()

TBrowse also includes a method, TBrowse:colorRect() , for

coloring any rectangular region. This meth od takes asparameters the four corners of the box (top, left , bottom, andright) in an array , and a color array. Th e coordin ates of the boxare relative to the browse window, so that 1,1 is the first cell ofthe f i rs t row current ly vis ible . The box " 1 , 1 , oBrow se:row Cou nt ,oBrowseicolCount" refers to al l current ly vis ible rows, thoughthe column numbers could refer to columns that are notcurrently visible.

Colors set with TBrow se:colorRect() remain in effect on a

particular row until that row's data is refreshed, either becausethe row scrolled off the screen or due to one of the refreshmethods . TBrowse:colorRect( ) over r ides TBCo lum nxolo rBlockand TBColumn:defColor.

You can use TBrowse:colorR ect() to highl ight an ent ire rowrather than an individua l column . This funct ion uses the passedcolor array to high light a row. If you ad d a call to the m eth odimmediately after the stabilize portion of the main loop (in anarea w here the brow se is guaranteed stable) , the row ma intainsthat color unt i l refreshed, imm ediately befo re applying the keyto the browse:/ / Hi l i teRowO

// Highlight current row with passed color array

PROCEDURE HiliteRow(oBrowse, aColors)LOCAL nCurRow

nCurRow := oBrowse:rowPos

// Color rowoBrowse:colorRect({nCurRow, 1, nCurRow, ;

oBrowse:colCount}, aColors)

// And make it happenoBrowse:forceStable()

RETURN




Control l ing the Scope

Controll ing the Sc op e

TBrowse lets you restrict a browse to a specific set of recordswithout the speed penalty inflicted by a fil ter or the need tocreate a tem po rary data base. In CA -Clip per, you restrict thebrow se by defining the l imits of cursor mov emen t within thedata source using the goTopBlock, goBottomBlock, andskipB lock instance variables of the TB row se class. Restrictingmovement this way is, effectively, the same as defining a fil ter orredefining the scope of your search, only much, much faster.

To define movements within your redefined scope to TBrowse,you m ust specify how to move direct ly to the top, how to mo vedirect ly to the bot tom, and how to move forward and backward

through records.

TBrowse:goTopBlock TB row se uses TB row sergo Top Bloc k to go to the top of the dataset being brow sed. TBro ws eDB () creates a defaultTBrowseigoTopBlock equivalent to:

oBrowse:goTopBlock := {|| DBGOTOP()}

TBrowse :goBottomBlock TBro wse uses TBro wse.go Bottom Block to go to the bot tom of thedata set being brow sed. TBro wse DB () creates a defaul tTBrowsergoBottomBlock equivalent to:

oBrowse:goBottomBlock := {|| DBG0B0TT0M()}

TBrowse:skipBlock TBro wse uses TBro wse:skipB lock to mo ve forward andback wa rd the specif ied numb er of records through the data set .TBrowse passes a posi t ive number to TBrowse:skipBlock tomove forward, and a negat ive number to move backward.

6-24 CA-Clipper




TBrowse:skipBlock returns only the number of rows i t actual lym ov ed . Th us , if the curren t row is two row s from the end of thedata set, and TBrowseiskipBlock is passed 4, i t returns 2,

indicat ing i t could only mo ve forwa rd two row s. TBro w seDB ()creates a defaul t TBrowse:skipBlock equivalent to:

// TBrowse:skipBlock created by TBrowseDB()oBrowse:skipBlock := {|nMove| Skipper(nMove)}

// Skipper()/ /// Handle record movement requests from the// TBrowse object

STATIC FUNCTION Skipper(nMove)LOCAL nMoved

nMoved := 0

IF nMove = = 0 .OR. LASTREC() = = 0// Skip 0 (significant on a network)SKIP 0

ELSEIF nMove > 0 .AND. RECNO() = LASTREC() + 1// Skip forwardDO WHILE nMoved < nMove

SKIP 1IF EOF()

SKIP -1EXIT

END IF

nMoved++ENDDO

ELSEIF nMove < 0// Skip backwardDO WHILE nMoved > nMove

SKIP -1IF BOF()

EXITEND IF

nMoved--ENDDO

END IF

RETURN nMoved





Viewing α Specific Key Va lue

You can look at all records associated with a particular key valueby defining the movements within the data set, then forcing theTBro wse : skip Block to remain within the key value . Definemovement to the top of the data set as seeking the particular keyand movement to the bottom of the data set as seeking the lasti tem matching the current key.

Firs t, wri te a funct ion to create a block for TBrow se:goTo pBlock.Note that this function creates a code block that can only refer toxKey, relieving us of the burden of ensuring that the key valueremains avai lable:

// FirstKeyBlock()/ /// Create TBrowse:g oTopBlock to seek the first// occurrence of the passed key

FUNCTION FirstKeyBlock(xKey)RETURN {|| DBSEEK(xKey)}

Nex t, wri te a funct ion to create a TBrow se:goBottom Block. Thisis more complex because the browse should move almostinstantaneously to the last matching key. Do this by seeking thenext key value, then skip back one record . Calculate the next keyvalue using the TBNextKeyO funct ion.

6-26 CA-Clipper




In the fol lowing example, LastKeyBlock() returns a block thatimplements TBrowse:goBot tomBlock:

/ / Las tKeyBlocM)//// Create TBrowse:goBot tomBlock to seek the last// occurrence of the passed key

FUNCTION LastKeyBlock(xKey)RETURN { || DBSEEK(TBNextKey(xKey), .T . ) , ;

DBSKIP(-l)}

// TBNextKey()/ /// Return value of next key in database

// WARNING Does not work on logical values or// floating point numbers

FUNCTION TBNextKey(xValue)LOCAL cType := VALTYP E(xValu e), xNext

DO CASECASE cType == "C"

// Find next value by incrementing the ASCII// value of the last character in the string

// NOTE: Assume last char is not 2 55 for// simplicityxValue := STUFF(xValue, LEN(xValue), 1, ;

CHR(ASC(RIGHT(xValue, 1)) + 1))

CASE cType == "N"// Since we can only handle integers,// increment value by onexValue++

CASE cType == "D"// Increment date by one dayxValue++

OTHERWISE

// Couldn't handle it

ENDCASE

RETURN xNext

Finally, write a function that returns the necessaryTBro wse :skipBlock. This funct ion is l ike the defaul tTBrowse:skipBlock described ear l ier, except that i t checks formoving out of range as well as for beginning and end of file.

Pro gram min g a n d Uti lit ies G uid e 6-27



Controll ing the Scope

One typical use of this function is zooming to child records froma browse of the parent database:

/ / KeySkipBlockO/ /

// Create TBrowse:skipBlock based on key valueFUNCTION KeySkipBlock(xKey)

RETURN {In M o v eI KeySkipper(nMove, xKey)}

// KeySkipper()/ /// Handle record movement requests from the// TBrowse object while staying within one key

FUNCTION KeySkipper(nMove, xKey)LOCAL nMoved

nMove d := 0

IF nMove = = 0 .OR. LASTREC() = = 0// Skip 0 (significant on a network)SKIP 0

ELSEIF nMove > 0 .AND. RECNO() = LASTREC() + 1// Skip forwardDO WHI LE nMov ed <= nMove .AND. EOF() .AND. ;

&(INDEXKEY(0)) == xKeySKIP 1nMoved++

ENDDO

// All above cases lead to skipping one extra

SKIP -1nMoved--

ELSEIF nMove < 0// Skip backwardDO WHI LE nMove d >= nMove .AND. BOF() .AND. ;

(INDEXKEY ( 0 ) ) == xKeySKIP -1nMoved--

ENDDO

/ / N o phantom BOF() record, else above loop// leads to skipping back one extra recordIF BOF()

SKIP 1END IF

nMoved++END IF

RETURN nMoved

6-28 CA-Clipper



Control ling the Sco pe

This examp le t ies the various code blocks an d funct ions definedso far in this section together, giving you a scoped browse basedon a key value that you pass as an argument:

// BrowseWhile()// Browse database while the key field matches// xKeyPROCEDURE BrowseWhile(nTop, n Left, nBottom, ;

nRight, xKey)LOCAL oBrowse // The TBrowse objectLOCAL nKey // KeystrokeLOCAL lMore // Loop controlLOCAL nCursSave // Save state

// Create another generic browseoBrowse := StockBrowseNew(nTop + 1, nLeft + 1 , ;

nBottom - 1, nRight - 1)

// Change the movement methodsoBrowse:goTopBlock := FirstKeyBlock(xKey)oBrowse:goBottomBlock := LastKeyBlock(xKey)oBrowse:skipBlock : = KeySkipBlock(xKey)

// Draw a box around the browse@ nTop, nLeft CLEAR TO nBottom, nRight@ nTop, nLeft TO nBottom, nRight

// Turn cursor off and save shape while browsingnCursSave := SETCURSOR(SC_NONE)

// Define exit keyoBrowse:setKey(K_ESC, {|| TBR_EXIT})

// Main loopiMore := .Τ.DO WHILE IMore


// Positioned at top or bottom of browseIF oBrowse:hitTop .OR. oBrowse:hitBottom

TONE(125, 0)END IF


// Act on the keystroke

IMore :- (oBrowse:applyKey(nKey) = TBR_EXIT)

ENDDO

SETCURSOR(nCursSave)

RETURN

Prog ram ming a nd Utilit ies Gu ide 6-29




Browsing S ea rch Results

Before the implementat ion of TBrowse, when browsing arandom collection of records (such as the results of a user 's

query), i t was necessary to create temporary databases or dealwith the s low display times of SET FILTER . Because T Brow segives you complete control over movement through thedatabase, you can execute fast browses of any arbitrary subset ofthe database.

To accomplish this, run the search through the database once,creating an array of the record numbers that satisfy the query.Use this array to control the brow se mov em ent . W hile thisimposes a limit of 4,096 matching records, this is usuallysufficient.

The fastest way to create the control array is to use theDB EV AL () funct ion. This funct ion receives a code blockequivalent to the FOR condition and returns a control array:

// ArrayFor()/ /// Create array of record numbers that match// passed condition

FUNCTION ArrayFor(bFor)LOCAL aRecs : = {}

DBEVAL({| | AADD(aRecs, RECNO())}, bFor)

RETURN aRecs

Using aRecs, the array returned by ArrayFor(), i t is easy tospec i fy TBrow se:goTopBlock and TBrowse .goBot tomBlock(assuming nCurRow is the curre nt row of the bro w se, as inLOCAL nCurRow := oBrowse: rowPos) :

oBrow se:go TopBl ock := {|| DBGOTO( ;aRecs[nCurRow := 1])}

oBrow se:go Botto mBloc k := {|| DBGOTO( ;

aRecs[nCurRow : = LEN(aRecs)])}

6-30 CA-Cl ipper



Control ling the Sc ope

TBrowseiskipBlock is also defined in terms of the array returnedby Array For ():

oBrowse:skipBlock := {|nMove| SkipFor( ;nMove, aRecs, @nCurRow)}

The function that TBrowserskipBlock calls to move through thedatabase uses the end and beginning of the array, rather than theend and beginning of the database:

// SkipFor ()/ /// Move through array-contro lled database

FUNCTION SkipFor(nMove, aRecs, nCurRow)LOCAL nMoved

nMoved := 0

// Put move into an acceptable rangeIF nCurRow + nMove < 1

// would skip past top...nMove := -nCurRow + 1

ELSEIF nCurRow + nMove > LEN(aRecs)// Would skip past bottom...nMove := LEN(aRecs) - nCurRow

END IFnCurRow + = nMovenMoved := nMove

DBGOTO(aRecs[nCurRow])

RETURN nMoved






Chapter 7

Introduction to the G et System


The CA-Clipper Get system is an integral interface toolconsis t ing of comm and s, objects (and their related data a nd

methods) , environments , and behaviors that implement dataentry and retrieval. It gives the dev elop er direct and specificcontrol over the interaction between the user and data, whilema king the retr ieval , display, man ipulat ion, and storage of dataeasy and f lexible . This chapter lays the grou ndw ork requ ired totake advantage of the Get system, after which, the reader shouldunderstand and be able to extend the system. The chapterassumes knowledge of the @.. .GET and READ commands, so thefocus lies instead on more advanced uses of the system.

This chapter starts with a discussion of the Get class, continuingwith the layers of the Ge t system . It con clud es with a discuss ionof pos sible modific ation s to the beha vior of the Get system . Th echapter contains many examples and recommendations.


• The Get class

• The Get system structu re

• Th e Rea d layer

• Extending the Read layer• Creat ing a new Read layer

• Th e Rea der layer

• Creat ing a new Reader layer

• The Get function layer

• Creatin g a ne w Get functio n layer




The Get Class

N o t e : This chapter assum es that you are familiar with theconcepts and terminology associated with CA-Clipper 'spredefined classes as discussed in the "Basic Concepts" chapterof this guide.

The Get Class

The Get class implements the formatting behavior associatedwith CA -Cl ipp er's Ge ts. Like all other classes, the Get class isdefined as a set of methods and exported instance variables, aswell as a function, GetNew(), used to create new Get objects.

This section discusses important behavior and uses of Get:blockand Geticargo and a few other features of the Get class inpreparation for deeper discussions of the Get system itself.Thro ugho ut the chapter, how ever, other instance variables andmethods not discussed in this section will be mentioned anddiscu ssed. If you nee d additiona l informatio n, refer to the Getclass in the "Language Reference" chapter of the Reference Guide.

Creating Get Objects

GetN ew() creates a new G et object . You supply parameters toGetNew() that specify the row and column position of the Get, aswell as a block that defines how the value of the Get should beretrieved and stored, the name to associate with the Get (usuallythe name of a variable or field being edited by the Get), a pictureclau se, and a color setting. The se are stored in the instancevar iables Get : row, Ge txol , Ge tb lo ck , Getmam e, Ge tp ic ture , andGe txo lorS pec , respect ively. No te that not all param eters arerequired, as il lustrated in this example:

LOCAL oGetoGet := Ge tN ew d, 2, FIELDBLOCK ("Zip") , "Zip")

7-2 CA-Clipper



The Ge t Class

Get:block

Getrblock holds a code block that stores the value passed, or

retrieves the value associated w ith the Get if no parameter ispassed . If the Get refers to a s imple variable (cVar in thisexample ) , the code block is s t raightforward:

oGet := G e t N e w d , 1, ;{|cNew| IIF(PCOUNT() = = 0, cVar, ;cVar := cNew)}, "cVar")

The block can also refer to a function call. For example , to createa Get object to modify the _SET_W RAP se tt ing , one wou ld dothe following:

cName := "_SET _WRAPoGet := G e t N e w d , 1, ;{|lNew| IIF(PCOUNT() = = 0, SET(_SET_WRAP) , ;SET(_SET_WRAP, lNew)}, cName)

D ue to the na ture of code blocks, arrays create a particularchal lenge. An array with a constant index works reliably:

cName := "aVar[1]"oGet := G e t N e w d , 1, ;

{|cNew| IIF(PCOUNT() = = 0, aVar[1j, ;aVar[l] := cNew)}, cName)

But when the index is a variable (for example , aVar[x\), it doesnot work because the code block then refers to a variable, x thatcan change before the b lock is executed . For example , at the t imethe block was c rea ted , χ may have a va lue of 3, making the blockrefer to 0 W r[ 3 ] . If χ is la ter chang ed to 1 , the code block refers toaVar[l]:

// This doesn't wor kcName := "aVar[ M + LTRIM(STR(x)) + ]oGet := G e t N e w d , 1, { | cNew | IIF(PCOUNT() = = 0, ;

aVar[x], aVar[x] := cNew)}, cName)

Programming and Utilities Guide 7-3



The Get Class

To solve this problem, the Get class makes special provisions forarrays. No rma lly, a G etb loc k for an array simply returns thearray reference. Ho wev er, s ince the code block must access theactual array element rather than the reference to the entire array,

and Get:subscript is not assignable, you must create the codeblock within a function:

cName := "aVar[" + LTRIM(STR(x)) + ]

oGet := Ge tN ew d, 1, AGetBlock (aVar, χ) , cName)

STATIC FUNCTION AGetBlock(aArray, x)RETURN { I xVal | IIF(PCOUNT() = = 0, a r r a y [ χ ] ;

aArray[ x] := xVal)}

This effectively hard-codes the array subscript, because the localvariable χ has g one out of scop e and can no longer be cha nged .

For more information, refer to the two sections, Arrays and CodeBlocks, in the "Ba sic Co nc ept s" chapter of this guide.

Setting and Retrieving Values

Note that while it seems logical to evaluate the Get:block to setand retrieve the value of a Get object, the way arrays are handledma kes this impract ical . Use the Get:varGet() and Get:varPut()methods instead.

// Retrieve the current value of the GetnVal := oGet:varGet()

//...and assign back one greateroGet:varPut(nVal + 1)

7 -4 CA-Clipper



The Get Class

Get:cargo

Sometimes it is desirable to track more information about the Get

than the Get object itself tracks. To let you d o this, CA-C lippe rdefines the cargo exp orted in stance var iable in all of its classes . Itis cal led "c arg o" becaus e i t is just "along for the r ide ." Carg o canhold data of any type.

If you have complete control over the objects, you can use cargoin any way you desire . This exam ple makes the prep rocessorcode easier to understand:

// These #defines use the GET's "cargo" slot to hold// the message displayed at the bottom of the// screen. Having #define s for these just makes it// easy to change later.#define SET_MESSAGE(g, msg) (g:cargo#define GET_ME SSAGE( g) (g:cargo)

msg)

Dictionaries If, on the other hand, you are not in complete control of theobjects (that is, you are writing general purpose routines forothers to use) , we strongly r ecom me nd that you use cargo as adict ionary, as implem ented in the Dict .prg samp le p rogram(located in your CA-Cl ipper SOU RC E\S AM PLE di rec tory) . Thisal lows several prog ram me rs to use cargo withou t conflict , andwithout any change in the source code.

Dictionaries provide a way of associating a key with a value, asin a real dictionary, where the word you look up (the key) isassociated with a particular definition (the value). Note that theentries in data dictionaries have no particular order.

This exam ple uses a diction ary to store help text. Bec ause th edict ionary is created and evaluated at runtim e, any num ber ofmodules can use the dict ionary without knowledge of how othermodules are using it:

// Use a dictionary to hold cargo information.// Requires linking the sample program Dict .obj .//// Create new dictionaryoGet:cargo := DictNew()// Assign message to Get objectDictPut(oGet:cargo, "MESSAGE", "Help Text")

// Print message from Get object at the bottom of// the screen@ MA X RO WO , 0 SAY DictAt(oGet:cargo, "MESSAGE")

Prog ram min g an d Utilit ies G uid e 7-5



The Get Class

Get Class Protocol

Once the object is created and the appropriate instance variablesare set, i t is read y for use. Yo u m ust first display the Get on thescreen using ei ther of two m etho ds, Get:display() orGet:colorDisp() , to accomplish this . Get:display() s implydisplays the Get in its current color (set through Get:colorSpec),while Get:colorDisp() sets the Get:colorSpec then displays theGet. The Ge t is initially disp layed in its unse lected co lor.

W hen you p erform actual data entry into the Get , you must f i rs tprep are the Ge t to accep t cha racters . Do this usingGe t:setFo cus (). This causes the Ge t object to create and initializeits internal state information, including the exported instance

var iab les : Get :buffer, Get :pos , Getd ecP os , G etx lear, andGe t:origina l. Th e conte nts of the editing buffer are thendisplayed in the GET's selected color.

Key strok es are intercep ted externa lly to the object. Data is putinto the Get using the Get: insert() an d/ or the G et:overStr ike()methods, and movement within the Get is accomplished usingany of the mo vem ent methods .

When editing is completed, the new value in the buffer is eitheraccepted by Get:assign() or discarded by Get:un do() . Thekil lFocus messa ge remo ves input focus from the Get . The Get isthen redisplayed in its unselected color and internal stateinformation is discarded.

This descript ion supplies al l the information necessary to fol lowthe exam ples given below . Und erstand that the Get class iss imply a tool used by the Get system to accomplish i ts goals—there is nothing about the Get class that t ies the two together.This will become clearer in the following discussion of the Getsystem.

7-6 CA-Clipper



The Get System

The G e t System

The Get system is an effective way to accept data input from theuser. It is flexible and open enough to allow modifications thatgreat ly enhance the power of the system.

The Get system is com pose d of several layers . M oving dow n thechart, the layers increase in both complexity of use and inprogram mer cont ro l . As wi th al l a reas of program ming, thehighest possible layer should always be used. This ensures m axim umprogrammer product ivi ty and system rel iabi l i ty.

Read Layer

Reader Layer

R E A D

j

Ge t Function Layer

G E TA P P LY K E Y Q G E T D O S E T K E Y Q G E T P R E VA L I D AT E Q G E T P O S T VA L I D AT E O

The Read Layer The top layer, the Read layer, is comp osed of the famil iar@. . .GET and REA D com ma nds . This i s where the bulk ofCA-Cl ipper programming i s done .

The Reader Layer The next layer, the Read er layer, controls the beha vior of one Ge tat a time. This layer is implemented by default through the

funct ion GE TR EA DE R() , bu t can be ex tended through addi t iona lcus tom readers.




The Read Layer

The G et Function Layer Th e bo ttom lay er, the Ge t fun ction layer, separates the behavio rof a single Get down into four distinct actions: prevalidating theGet , handling SET KEYs, applying keystrokes to the Get , andpostval idat ing the Get .

T h e G E T P R E VA L I D AT E ( ) , G E T D O S E T K E Y ( ) , G E TA P P LY K E Y ( )and GETPOSTVALIDATE() func t ions per form the defaul timp lem entat ion, respect ively. This layer can also be extendedthrough custom Get funct ions.

The Read Layer

One way to see the relationship between layers is to analyze theimp leme ntat ion of the Read layer. This system is wri t ten alm ostent irely in CA -Clipp er. The f i le Getsys.prg ( located in yourCA -Clipp er SO UR CE \ SYS directory) contains the source cod efor the system.

A quick look at this source, or at the commands in STD.CH,shows that a screen of Gets is represented internally as an arrayof Ge t objects. Th ese Gets are stored in the pub lic array GetListby defa ult. This array is alw ays prese nt, just as thou gh the first

line of all your programs is:PUBLIC GetList := {}

As you c an see if you look at i ts #com m and defini t ion inST D.C H , @.. .GE T adds a Get object to the GetList array, assignscertain instance variables based on various keywords, thendisplays the newly created Get object with code similar to thefol lowing:

AADD(GetList, GetNew(...))ATAIL (GetL ist):c aptio n := ...ATAIL (GetL ist): capRo w := ...ATAIL (GetList) -.capCol := ...ATAIL(GetList):display() // Display newly created

// Get object

7-8 CA-Clipper



Extending the Read Layer

READ is implemented through the func t ion READMODAL() .As you can see by s tudying the source code in Getsys.prg,REA DM OD AL () i s passed the GetLis t a rray to process and

returns a logical value that indicates wh ether a ny of the Getswere updated .

READMODAL() f i rs t ini t ia l izes al l of i ts variables andimplements some Summer '87 compatibi l i ty behaviors . I t thenenters a loop to proce ss all of the Gets. W ithin this loop , itnotifies the system that this is the "active" Get object (making itavai lable through the GETACTIVE() funct ion) and passes controlto the Reader layer using the defaul t reader, GETREADER() or acustom reader as defined through the Getrreader code block.


W ith und erstandin g of the basic Rea d layer, it is possible tomake signif icant enhancements to the system without modifyingit.

Nested ReadsThe abi l i ty to nest reads, a mo st desired enh ancem ent , is easywi th CA-C l ipper. Because the RE AD com ma nd s imply passesan ar ray named GetLis t to READMODAL() , you can use adifferen t varia ble, G etList, in other func tions . If yo u call afunc t ion f rom a VA LID or WH EN clause or f rom a SET KE Yproc edu re, and then define a new array, GetList , local to thatfunct ion, the @.. .GE TS and R EA D s there wil l refer to the localGetList.





This GetList fal ls out of scope w hen the funct ion end s, returningcontrol to the previous READ and i ts GetList :

// Creating nested reads

PROCEDURE Main()LOCAL cName := SPACE(10)@ 10, 10 GET cName VALID SubForm(cName)READRETURN

FUNCTION SubForm(cLookup)LOCAL GetLis t := {} // Create new GetListUSE Sales INDEX Salesman NEWSEEK cLookupIF FOUND()

// Add Get objects to new GetList@ 15, 10 GET Salesman@ 16, 10 GET Amount// READ from new GetListREAD

END IFCLOSE Sales// Release new GetListRETURN .T.

Using GETACTIVEO

Much of the power of the new Get system lies in its directmanipulation of a Get object after i ts retrieval with the

GE TA CT IVE () funct ion. This funct ion lets you not only retr ieveand change the current value of the Get, but access all theinformation stored in it .

C ha ng in g Ge ts Through SET KEYs

A perfect exam ple of direct object manipu lat ion is changing thevalue of a Get through a SET K EY . W hile you can do this usingthe KE YB OA RD com m and to s tuff the keyboard buffer or byapplyin g the mac ro operator to the resul t of RE AD VA R() ( if theGet is being done on a field, private, or public variable), i t ismuch cleaner to just send messages to the current Get object.

7-10 CA-C' ipper




This examp le exam ines the current content of the Get . I f the Getis of character data type, i t converts the contents to mixed caseusing the sample funct ion Proper() when the user types Ctr l+K.

Proper() is defined in String.prg, which is located in yourCA-Cl ipper S OU RC E \ SAM PL E di rec tory :

// Convert ing character input to mixed case// Must be linked with String.obj to work

#include "Inkey.ch"

. .<statements>

SET KEY K_CTRL_K TO GetCapFirst

. <statements>

@ 1, 1 GET cTestREAD

SET KEY K_CTRL_K TORETURN

// GetCapFirst(}// Capita lize the first letter of every word//

STATIC PROCEDURE GetCapFirst()LOCAL oGet, cString

// Grab the current Get objectoGet := GETACTIVE()

// Get the current value of the GetcString := oGet:varGet()

IF VALTYPE(cString) == "C"// Convert and put the value backoGetivarPut(Proper(cString))

END IF

RETURN





Improving Help Rout ines

You can also improve help systems by storing the help text (or anind ex to the help text) in G etx arg o. No tice how d ictionaries are

used to reduce potential conflicts between this and any othermodules that implement enhancements to the Get system:

// Storing Help Text in Get:cargo// Dict.obj is necessary for the following example.

PROCEDURE ReadTest()LOCAL cVarlLOCAL GetList := {}

cVarl := SPACE(30)

CLS@ 3, 0 SAY PADCC'GETs w/ Help Text in " + ;

"Get:cargo", MAXCOL())@ 4, 0 SAY PADCC* (<F1> for he lp)" , MAXCOL () )

// Put the help text in the cargo// dictionary manually© 7 , 0 SAY "Variable 1" GET cVarlIF ATAIL(GetList):cargo = = NIL

ATAIL (GetList): cargo := D ict New OEND IF

DictPut(ATAIL(GetList):c argo, "Help Text", ;"Help for variable one.")

READ

RETURN

// HelpO// The system automa ticall y assigns Fl to this// procedure , returning help from wherever you are

PROCEDURE Help(cProc, nLine, cVar)LOCAL oGetLOCAL cMsg := "No help ava ilable for this item"

// Retrieve help text from Get:cargo dictionary// In a more robust version of this system,// some sort of index into a help file would be

// stored rather than the help text itself. This// would allow easier editing of the help text// and permit runtime modification of it.IF (oGet := GETAC TIVE( )) = NIL

cMsg := DictA t(oGe t:car go, "Help Text")END IF

DispMsg(cMsg)

RETURN

7-12 CA-Clipper




The f i rs t concern many people have when seeing this is thediff icul ty of addin g the help text. Fortun ately, CA -Clip per alsoprovides a graceful way to do this . By defining a command that

adds a HELP clause to the s tandard @.. .GET command, theinterface is made much cleaner:

// Adding a help clause to the @...GET Command// Helpget.ch

command @ <row>, <col> GET <var> [<clauses, ...>] ;HELP <help> [<moreClauses, ...>] ;

=> @ <row >, <col> GET <var> [<clauses>] ;[<moreClauses>] ;;IF ATAIL(GetList):cargo = = NIL ;; ATAIL (GetList): cargo := Di ctN ew O ;;ENDIF ;

; DictPut(ATAIL(GetList) :cargo, "Help T ext", <help>)

This command, l ike the earl ier code in ReadTestQ, checks to seeif Getxargo is NIL before making i t a dict ionary because thiscom m and 's defini t ion lets you u se it with other extensions to theGE T com m and . I t is very plausible that som e other extensionhas a lready m ade Ge txa rgo a d ic tionary. I f so , the com m andjust inserts the ne w entry into the existing dictio nary . IfG etx arg o is not NIL , and i t is not a dict ionary, the com m and wil lcrash at runt im e.

Prog ram ming a n d Utilit ies Gu ide 7-13




To use this com m an d, include the header f ile and simp ly add theHELP clause to any exist ing Gets , as shown below:

// Using the Help Clause

#include " HelpGet.cn" PROCEDURE ReadTest()

LOCAL cVarlLOCAL GetList := {}

cVarl := SPACE(30)

CLS@ 3, 0 SAY ΡADC("GETS w/ Help Text in " + ;

"Get:cargo", MAXCOL())@ 4, 0 SAY PADC("(<F1> for help)" , MAXCOL())

// Put the help text using new command@ 7, 0 SAY "Variable 1" GET cVarl PICTURE "@ " ;HELP "Help for variable one."

READ

RETURN

Using C o d e Blocks for WHEN /VALID

Because the @.. .GET command accepts a code block as a legalparameter for either clause, it is easier to manipulate a GET fromwith in a W H EN or VA LID c lause than from a SET KEY .

Dynamic P ic tu res

The fol lowing example changes the PICTURE clause of a Geton-the-f ly in the WHEN clause:

// Dynamically changing the PICTURE clause of a Get

PROCEDURE Main()

LOCAL GetList := {}LOCAL cName := SPACE(20)LOCAL cIDType := "I"LOCAL cSSNo := SPACE(9)

SET CONFIRM ONSET SCOREBOARD OFF

7-14 CA-Clipper

http://helpget.cn/

http://helpget.cn/




CLS@ 3, 0 SAY PADC("Member Information")

@ 5, 0 SAY "Name " GET cName

@ 6, 0 SAY "O om pan y or I individual" ;GET cIDType PICTURE " " VALID cIDType $ "CI"

// Change picture based on whether this is for a// person or company@ 7, 0 SAY "SS# or Tax ID# " GET cSSNo ;

PICTURE StartPic(cIDType) ;WHEN {|oGet| ChangePic(oGet, cIDType)}

READ

RETURN

// StartPic()

// Determi ne what the initial value for the pictu re// should be.

STATIC FUNCTION StartPic(cIDType)

IF cIDType == "C"RETURN "@R 99-99999-99"

ELSE// Default valueRETURN "@R 999-99-9999"

END IF

// ChangePic()// Change picture on-the-f ly from SS# to Tax ID or// vice versa (to be called from WHEN c lause) .

STATIC FUNCTION ChangePic(oGet, cIDType)IF cIDType == "C"

oGet:picture := "@R 99-99999-99"ELSE

// Default valueoGet:picture := "@R 999-99-9999"

END IFRETURN .T.





Processing the Entire GetList

While modifying a single Get is useful, there are times when it isdesirab le to mo dify all of the Ge ts. On e might wan t to chang etheir colors or m ov e them as a unit across the screen. Becau seyou can dynamical ly modify almost everything about a Get , suchchan ges are surpris ingly easy.

First wr ite the functions to proc ess the entire GetL ist. Thefunctions below mo ve the Gets a specified num ber of rows andco lum ns, and chang e the colors of the Ge ts. Both force the Getsto redisplay th emse lves:

// Moving rows and columns and changing colors/ /

// MoveGets(<aGet s>, <nRows>, <nCols>) --> <aGets>// Move Get array to new location and redisplay

FUNCTION MoveGets(aGets, nRows, nCols)LOCAL nGet

FOR nGet := 1 TO LEN( aGets)aGets[nGet]:row += nRowsaGets[nGet]:col += nColsaGets[nGet]:display()

NEXT

RETURN aGets

// ColorGets(<aGets>, <cColor>) --> <aGets>// Change colors of all Gets in Get array// and redisplay

FUNCTION ColorGets(aGets, cColor)AEVAL(aGets, {|oGet| oGet:colorDisp(cColor)})RETURN aGets

7-16 CA-Clipper



Creat ing a New Read Layer


While the previous examples demonstrate that many addit ionscan be made without modifying the Read layer, sometimes i t isnecessary or cleaner to replace the default Read layer.

Basic Guidelines

How do you know whether to extend the Read layer or to createa new one ? Th ere is no absolu te rule, but there are som e basicguidel ines. Create a new Read layer und er the followingcircumstances:

• The new feature wo uld , otherw ise, require adding a funct ionto the VALID or WHEN clause of every Get .

• The new feature requires act ions betw een each Get .

Extend the default Read layer, if either of the following is true:

• The new feature only requires mod ifying the Get at the t imeit is created (for exam ple, s toring informa tion in Get xar go orone of the other instance variables).

• Th e ne w feature does not affect the orde r in w hich Gets aretraversed, or wh at tasks are carr ied out betw een G ets . Thistype of feature is usually added by making a modification atone of the lower layers (leaving the Read layer intact).

N o t e : O ne set of mo dification s to the Rea d layer is generallyincompatible with any other set (that is, both can exist in thesame applicat ion but cannot be used simultaneously) .Combining them requires creat ing a third Read layer thatincorporates ideas from both implementat ions.





Important Implementation Rules

If you d etermine that a new Read layer is necessary , be mind fulof seve ral things. First and forem ost is the followin g rule,importan t in all aspects of CA -Clipper prog ramm ing: avoidchan ging the d efault behav ior of the system .

In the case of the Get system, this means:

• Do not m od ify Ge tsys.prg or redefine any of the functionscontained within it .

• Do not redefine the basic RE A D com man d. You can addclauses and map the new command to a different Read layer.

• Do not redefine the basic @.. .GET comm and ; add clausesthrough a new command defini t ion.

• If you add a clause to the @.. .GET com ma nd , map the newcom ma nd to the basic @.. .GE T c om ma nd, i f a t a ll possible.

In addition to the above rules, if i t is necessary to store anyinformation with individual Gets, store it as a dictionary entry inGe txa rgo .

If you follow these rules, your Read layer has a much better

chance of working with extensions you intend to use with thedefau lt Read layer. It also lets yo u revert to the default Rea dlayer i f you have problem s with your code. Mo st important ly,your code wil l be much more maintainable by otherprogrammers (or by you at a later date) because it will beobvious where you have made modificat ions to the system.

7-18 CA-Clipper




Implem entation Steps

Creating a Read layer that follows the above rules is relativelystraightforward:

1. Determ ine wh ere any ini t ial izat ion code should be located.It is important that your Read layer be reentrant (that is, yo urread function can be called from within itself via a VALID orWHEN clause) . Therefore, take care that you save andrestore any filewide statics as needed.

Your initialization code will therefore be split between yourread function and the static function ClearGetSysVars(),defined in Getsy s.prg.

2. Crea te your new read function based on READ M OD AL Q,mak ing sure to renam e it . After making the ap propriatemod ificat ions, you hav e defined the interface.

3. Ad d any necessary support ing functions, declaring as publicany functiors that will be called by the user (either directlyor through a command), and declaring as static all otherfunctions.

4. Create a head er f ile to define the com ma nd s that implem entyour new Read layer.

READ VALID

The first example of a custom Read layer lets you control exitfrom the Read with the VA LID clause. This is accom plished bywrit ing a new function, ReadValid() , based on the s tandardREADMODAL() funct ion as defined in Getsys.prg.

ReadVal id( ) accepts al l parameters required by R EA DM OD AL ,

as well as an addit ional param eter— a cod e block that executesw he n the user attemp ts to leave the Rea d. If the cod e blockreturns false (.F.), the user is left on the same Get; otherwise theRe ad is exited. No te that the cod e block is passe d both theGetList and a logical value that indicates whether any of the Getsin the Read were changed.

Prog ram min g a n d Utilities Gu ide 7-19




Because the addition of this capability does not require anyini t ial izat ion and ad ds no new "st ate s" to the Read layer, youcan com pletely ignore the reentrancy issue, which great lysimplif ies the implem entat ion. The code show n below for

Re ad Valid () is an excerp t— any cod e not sho w n is the sam e asR E A D M O D A L ( ) :

// Restricting a read based on a VALID clause/ // / ReadValidO

// Read until condition is true

FUNCTION ReadValid(GetList, ..., bValid)

LOCAL nLastPos

WHILE IsnPos == 0

// Save current positionnLastPos := snPos

// Move to next Get based on exit conditionsnPos := Settle(aGetList, snPos)

// If I am about to exit, check to see if// VALID condition is true

IF snPos = = 0// VALID clause is passed current GetList,// whether Read has been changed/ /IF EVAL(bValid, aGetList, UPDATED())

// If it isn't valid, don't movesnPos := nLastPos

END IFEND IF

ENDDO

RETURN UPDATED()

7-20 CA-Clipper




A new com man d, REA D VA LID , makes i t easy to use th is newRead . No tice that the block ify result m arke r is use d, allowin gthe code block to be either an expression or a block:

// Translation Rules for READ VALID/ /// Valid.ch// READ VALID#command READ VALID <valid> SAVE => ;

ReadValid(GetList, <{valid}>)

#command READ SAVE VALID <valid> => ;ReadValid(GetList, <{valid}>)

#command READ VALID <valid> => ;Read Valid (Get List, <{valid} >) ;GetList := {}

You need only #include Valid.ch and add the VALID clausewh ere desired to use the new R ead layer. A simple exam plefollows:

// Using the New Read layer

#include "Valid.ch"

MEMVAR GetList

PROCEDURE Main()LOCAL cVarl, cVar2, cVar3cVarl := cVar2 := cVar3 := SPACE(20)

CLS@ 10, 10 SAY "Variable 1" GET cVarl@ 11, 10 SAY "Variable 2" GET cVar2@ 12, 10 SAY "Variable 3" GET cVar3// The following insures that none of the Gets// are left empty, and is equivalent to:/// / READVALID ( EMPTY(cVarl)) .AND. ;// ( EMPTY(cVar2)) .AND. ( EMPTY(cVar3))/ /R E A D VA L I D {|aGets, 1Updated| ;

NoneEmpty(aGets, lUpdated)}RETURN

// NoneEmpty()

// Retur n .T. if none of the Gets is empty

STATIC FUNCTION NoneEmpty(aGets, lUpdated)LOCAL nGet

// See if there are any empty GetsnGet:=ASCAN(aGets,{|oGet| EMPTY(oGet:varGet())})// nGet will equal 0 if there were no empty GetsRETURN nGet = = 0





Gets With Messages

A sl ight ly more complex Read layer example displays a messageon the screen for eve ry Get. In this section , the R ead M essag e()funct ion is implemented, again based on the s tandardREA DM OD AL () func t ion as def ined in Getsys .prg .

N o t e : This is presented as an exam ple of how to custom ize theGet system . A m uch easier way to display a me ssage for a Get isto use Get:message (which can be assigned using the MESSAGEclause of the @.. .GET command) in associat ion with the MSGclauses for the RE AD com ma nd.

Implementing ReadMessage() requires that you define a means

for specifying and storing the message as well as for actuallydisplaying it . As discussed earlier in the context ofimp lemen ting context-sensi t ive help , the easiest w ay to do this isto store the message as a dictionary entry in Get:cargo.

In the fol lowing e xam ple, the Read layer retr ieves the m essagefrom the Getrcargo dictionary and displays it as specified by theSET M ESS AG E TO com ma nd, sav ing and restor ing tha t sec t ionof the screen. Here ag ain, only an excerpt of ReadM essageQ isshow n, ind ica t ing where i t d i ffe rs f rom REA DM OD AL () :

// Retrieving and displaying a message/ /

#include "Set.ch"

// ReadMessage()/ /FUNCTION ReadMessage(aGetList, . . .)

LOCAL cMsg, lCenter, nRowLOCAL nSaveRow, nSaveColLOCAL cSaveScr

// Retrieve settings from SET MESSAGE TOnRow := SET(_SET_MESSAGE)IF nRow = = NIL

nRow := 0END IF

7-22 CA-Clipper




lCenter : = SET(_SET_MCENTER)IF lCenter = NIL

lCenter : = .F.ENDIF

WHILE/ /

// If a message is supplied and messages are// enabled, display itcSaveScr := NILIF nRow > 0 .AND. oGet:cargo = NIL

// Retrieve message from dictionary

cMsg := DietA t(oGet :carg o, "cMessage")IF cMsg = NIL// Save message row and cursor settingscSaveScr := SAVESCRE EN(nRow , 0, nRow, ;

MAXCOL()-1)nSaveRow := ROW()nSaveCol := COLO

IF lCenterSETPOS(n Row, ((MAXCOL()/2) - ;

(LEN(cMsg) 2DISPOUT(cMsg)

ELSESETPOS(nRow, 0)DISPOUT(cMsg)ENDIF

// Restore cursorSETPOS(nSaveRow, nSaveCol)ENDIF

ENDIF

// Read the Get

snPos == 0Get next Get from list and post it

// If screen line was saved, restore it

IF cSaveScr = NILRESTSCREEN(nRow, 0, nRow, MAXCOL() - 1,cSaveScr)

ENDIF// Move to next Get based on exit conditionsnPos := Settle(aGetList, snPos)

ENDDO

RETURN UPDATED()





Two new commands , @. . .GET MYMSG and READ MYMSG,make it easy to access this new Read layer:

// Creating commands to access the new Read layer/ /

// GetRead.cn // Translation rule for @...GET MYMSG#command @ <row>, <col> GE T <var> [<clauses, ...>] ;

MYMSG <msg> [<moreClauses, ...>] ;

=> @ <row>, <col> GE T <var> [<clauses>] ;[<moreClauses>] ;;IF ATAIL(GetList):cargo = NIL ;;ATAIL (GetList): cargo := Dic tNe wO ;;ENDIF ;

;DictPut( ATAIL(Ge tList):ca rgo, "cMessage", <msg>)

// Translation rule for READ MYMSG

ttcommand READ MYMSG SAVE => ReadMessage(GetList)#command READ SAVE MYMSG => ReadMessage(GetList)

#command READ MYMSG => ;ReadMe ssage( GetLis t) /GetList := {}

To use this new Read layer, add the MYMSG clause to any Getsthat shou ld have a me ssage . SET M ESS AG E TO sets the row forthe mes sages and w hether they should be centered. Final ly, usethe READ MYMSG command ins tead of READ. This exampledemonstrates:

// Using the new Read layer

PROCEDURE Main()LOCAL GetList := {}LOCAL cVarl, cVar2, cVar3

cVarl := cVar2 := cVar3 := SPACE (20)

SET MESSAGE TO (MAXROW() - 1) CENTER

CLS@ 10, 10 SAY "Var 1" GET cVarl MYMSG ;

"Enter Variable 1"@ 11, 10 SAY "Var 2" GET cVar2@ 12, 10 SAY "Var 3" GET cVar3 MYMSG ;

"Enter Variable 3" PICTURE "@ " ;VALID ( EMPTY(cVar3))

READ MYMSG

RETURN

7-24 CA-Clipper

http://getread.cn/

http://getread.cn/



The Reader Layer

The Reader Layer

As flexible as the ability to create new Read layers is, i t allows nocontrol over individual Ge ts . You gain control over anindividual Get through that GET's reader. This is how the newGUI- l ike commands ( such as ©. . .GET CHECKBOX and ©. . .GETLISTBOX) are implemented .

A reader intercepts the keystrokes and applies them to the Get; i tis completely responsible for implementing the behavior of thatpart icular Get . You can see this mo st c lear ly by exam ining thedefaul t reader, GETREADER(), as def ined in Getsys.prg.

GETREADERQ communica tes wi th the Read layer th rough thecurrent GE T's exi tState instance variable . This te lls the Rea dlayer how the Get was exi ted so it can determ ine wh ich act ion i tshould take next . Getexi t .ch defines the possible values forGet:exi tState . GETREADER() then passes through three phases:preval idat ion, assignment , and postval idat ion.

Prevalidation The GE TPR EV AL IDA TE () func tion per forms the preva l ida tionstep to evaluate whether the Get fulfil ls the requirements set inthe WH EN claus e. If this step fails, the Ge t is not entered andGet:exi tState is set to GE_WHEN.

Assignment In the assignm ent pha se, INKEY(O) intercepts keystrokes, thenGETAPPLYKEYQ acts on the ASCII value of the keystroke.When a user strikes an exit key, Get:exitState is set to somethingother than GE_NOEXIT and control passes to the postval idat ionphase.

Postvalidation The GE TPO STV AL IDA TE() func t ion per forms the pos tva l ida t ionstep to evaluate whether the Get fulfil ls the requirements set inthe VALID clause. I f the requirements are met , execut ion passes

back to the Read layer. I f they are not met , the assignm ent ph aseis reentered.




Creat ing New Reader Layers


Thou gh GET REA DER () implem ents a ll o f the s tandardCA-Clipper Get behaviors , you can add new behaviors thatfulfil l special needs.

Basic Guidelines

As with the decision to extend the default Read layer or to createa new one, i t is not a lways clear when you should implement afeature through a new Read layer and when you shouldimplem ent i t through a new reader. This indecis ion is especial lystrong whe n the feature involves taking some act ion before

and/or af ter every Get .

The message Read layer created earlier in this chapter is anexam ple of this ; you could h ave imp leme nted i t as a readerrather than as a Rea d layer. Unfo rtunately, it wou ld then hav ebeen incom patible with other readers . Since i t is not u ncom m onto use several readers at a t ime, this is a larger drawback thanincompatibili ty with other Read layers.

N o t e : Ad ding som e features requires creat ing new behavior atall layers. In mos t cases , the chan ge is so drastic that i t coun ts asa new form s ystem a nd is no longe r part of the Get system . Inthese cases , you shou ld consider creat ing a completely new formtool rather than drastically mod ifying the existing system . Thecreation of new form systems is outside the scope of this chapter.

7-26 CA-Cl ipper




Important Implementation Rules

Once you decide that creating a new reader is the correct thing to

do, there are a few rules you sh ould follo w. As in creation of aRead layer, the default behavior of the system shou ld neve r bemo dif ied. W hen creat ing a new reader this mean s:

• Do not m odify Ge tsys.pr g or redefin e any of the functio nscontained within i t , including the GETREADER() andGETAPPLYKEY() func t ions .

• Do not redefine the basic @.. .GE T com m and ; again, you canadd clauses through a new command defini t ion.

• I f a c lause is added to the @.. .GE T comm and , the new

comm and should m ap to the suppl ied @. . .GET com ma nd, i fat all po ssible .

To function well, your reader must adhere to the protocol laidout by the defaul t reader, GETR EA DE RQ . I t mu st also s tore datain a way that will not harm other extensions that may be storingdata. This means that the reader will:

• Use Get .exi tState as i ts me ans of com mu nicat ing with thecontrolling Read layer.

• Use GE TP RE VA LID AT E() to ensure that the Get can beentered.

• Use GE TPO STV AL IDA TE O to ensure that the Get can beexited.

• Use GETA PPLYK EY() for all k eystrokes, or def ine a uniqu e"app ly key " funct ion that handles al l keystrokes. Thisenables you to use the new reader in non-m odal formsystems.

• Con form to al l of CA -Clippe r 's def ined edi t ing keystrokesunless there is a compelling reason to do otherwise.

• Ha nd le all possib le valid picture clauses for the data typebeing handled.

Prog ram min g a n d Util it ies Gu ide 7-27



Creating New Reader Layers

• Store any data that m ust acco m pan y the Get as a dictionaryentry in Geticarg o. This requires use of the functions foundin the sample program Dict .prg suppl ied with CA-Clipper.

• Ch eck Get:carg o, wh en storing such data, to see if i t is NIL .If i t is NIL , create and ass ign a dictionary to the instancevariab le. If i t is not NIL , assu m e that G etx ar go is already adictionary and add the entry.

By following these rules, you ensure that your reader iscomp atible with the broadest possible range of Read layers , newform tools, and other readers.

Incremental Date Get

Our first example of a custom reader is one in which a date ischang ed by increm enting i t one day with the plus key (+) anddecrementing it a day with the minus key (-). All normal editingkeys are sti l l allowed. This example, following our guidelines,creates two funct ions, DateGetReader() and DateGetApplyKeyO,to implement this reader.

DateG etRead er() is ident ical to GE TR EA DE R() except that i t callsDateGetApplyKeyO ins tead of GET APP LYK EY() . The codeshow n below is an excerpt— any code not shown is the same asGETREADER() :

#include "Getexit.ch"

// DateGetReader()/ /// Replac ement for GETREADER(). Logic is identical,// except DateGetApplyKey() processes keystrokes

PROCEDURE DateGetReader(oGet, . . .)

// Apply keystrokes until exitWHIL E oGet:e xitSta te=GE _NOEXI T .AND. IslKillRead

DateGetApplyKey(oGet, INKEY(0, . T . ) , . .. )ENDDO

RETURN

7-28 CA-Cl ipper




Because this reader requires special handl ing for only two k eys,GE1 AP PLY KE Y() can hand le mo st of the keystrokes. Th us,DateGetApplyKey() intercepts the plus and minus keys and

implem ents special handl ing for them , passing control toGETAPPLYKEY() for a l l other keystrokes. This is therecommended way to add correct support for a l l the defaul tedi t ing keystrokes:

// DateGetApplyKey()/ /

// Replacement for GETAPPLYKEY()// Performs inc r/decr on a date get for '+' and '-'// keys, standard behavior otherwise.

PROCEDURE DateGetApplyKey(oGet, nKey, .. .)LOCAL cKey := CHR(nKey)

DO CASECASE cKey == '+* .AND. oGet:type == 'D'

oGet:buffer := TRANSFORM(oGet:un Transform() ;+ 1, oGet-.picture)

oGet:ch anged := .T.oGet:display()

CASE cKey == .AND. oGet:t ype == 'D'oGet:buffer := TRANSFORM(oGet:un Transform() ;

- 1, oGet:picture)oGet:chan ged := .T.oGet:display()

OTHERWISE

GETAPPLYKEY(oGet, nKey, .. .)

ENDCASE

RETURN

Pro gram min g a n d Utili ties G uid e 7-29



Creating New Reader Layers

To use this new reader, you must create a new com man d thatinclud es sup port for i t. In particular, the key to gettingREADMODAL() to cal l the new reader instead of the defaul treader is to assign the new reader, as a code block, to the Get

object 's reader instance variab le. This is accom plished using theSE ND clause of the @.. .GET com m and . Notice that thiscommand is implemented in a way that adheres to theguidelines, calling the default implementation of @...GET in itsdefinition:

// Trans latio n rule for @...GET DATECHANGE/ /// Dateget.ch

// @...GET DATECHANGE

#command @ <row>, <col> GET <var> [<clauses, . . . > ] ;DATECHANGE [<moreClauses, . . . > ] ;

=> @ <row>, <col> GET <var> [<clauses>];SEND reader:={|get, . .. | DateGetReader(g et,.. .)};[<moreClauses>]

This exam ple dem ons trates the ease of using the new reade r. Itincludes the header f i le and uses the O. . .GET DATECHANGEcommand to create the Gets:

// Using the new reader

/ /

#include "Dateget.ch"

PROCEDURE Main()LOCAL dOne, dTwodOne := CTOD("3/17/65")dTwo := CTOD("5/20/91")

CLS@ 10, 10 GET dOne DATECHANGE@ 11, 10 GET dTwo DATECHANGE

READ

RETURN

7-30 CA-Cl ipper



The Get Function Layer

The Get Function Layer

As you have already seen, the usual way of manipulat ing the Getfunction layer is by defining a new reader which calls yourfunctions instead of the default ones. For example, in theprevious example, you saw how to intercept keystrokes at theReader layer and manipulate them using your own apply keyfunction.

The example , however, used the defau lt GETA PPL YK EY() toimplem ent the m ajori ty of i ts keystroke behavior, wh ich is notalways the case. Sometimes it is necessary to create a new applykey function from scratch. To do that, i t is im portan t to kn ow

exac t ly what GETAPPLYKEYQ does .

GETAPPLYKEY() goes through several s teps to implement thekeystroke behavior associated with Gets:

• Ch ecks and executes SET KE Ys, i f appropriate

• Che cks m ovem ent keys and sets Get :exi tState to GE _U P,GE_ DO W N, GE_TO P, or GE_B OT TO M , if app rop r ia t e

• Ch ecks other keys that exit Ge ts and sets Get.exitS tate toGE_ENTER, GE_ESCAPE, or GE_WRITE, i f appropr ia te

• Che cks and acts upon special purpo se keystrokes l ike Inser tand Ctr l+U (undo), i f appropriate

• Discards all inval id keystrokes, or inser ts /ove rstr ikes theminto the Get, based on the state of the insert flag

N o t e : To gain a com plete and thorough und erstanding ofGETAPPLYKEY(), or any of the other Get funct ions, the bestthing to do is study the source code provided in Getsys.prg.

Prog ram ming a n d Utili ties Gu ide 7-31



Creating New Get Function Layers

Creating New Get Function Layers

Creating a completely new apply key routine that does not useGETAPPLYKEY() is a complicated task and should not beunde rtaken l ight ly. You shou ld do this only wh en you m ustdefine ent i rely new beh aviors that are not "natu ral ly" supportedby the Get c lass (for examp le, redefining cursor mo vem ent ,creating new picture template characters, or inserting charactersfrom the right instead of the left) .

To create a reader that requires this type of support, start bycreat ing a new module that contains a renamed copy ofGET REA DER () and GET AP PLY KEY () , as wel l as the s ta ticfunct ion Show ScoreB oard() and i ts associated defines. (Once

again, the source code for all these functions can be found inGetsy s.prg.) Th en throw out mo st of the cod e, and rewrite fromscratch. W ork ing from the copies of these functions ensures thatyou have covered all of the default keystrokes.

There are many pitfalls in creating this type of reader, including:

• Fai lure to accom mo date al l possible picture clauses,including those produced by the picture funct ion "@R."

• Failure to correctly han dle num eric Gets with no picturespecified . In most cases it is easiest to han dle this bycalculating the picture and, if there is not one defined,assigning it upon entry to the reader.

• Use of cursor mo vem ent and edi t ing metho ds provided bythe Get class. These methods are specific to the definedpicture s and beha vior s associated with the default reader. Ifyou can use these methods, you probably should not becreating a Get function layer.

• Failure to obe y G etx lea r and clear the Get befor e acceptingmore keystrokes.

• Failure to correctly han dle floating point num ber s. Thisincludes failure to truncate insignificant digits andcom parison of float ing point num bers exact ly withoutrounding to a specific precision.

7-32 CA-Cl ipper



Chapter 8

Introduction to the Menu System


The CA-Clipper Menu system is a powerful tool that a l lows youto create s tandard m enu s consis t ing of a me nu bar withpul l-down menus and bui l t - in mouse support . The system letsyou define al l types of s tandard i tems, such as menu commands,toggles , cascading m enu s, and separators . I t a lso le ts you d efinestandard features for menu i tems, such as shortcut andaccelerator keys , toggle and cascading m enu ind icators , and theability to disable an item.

The Menu system consis ts of several predefined classes:TopBarMenu, PopUpMenu, and Menul tem. Col lec t ive ly, theseclasses provide you with a great degree of control and flexibili tyin creat ing and edi t ing custom-designed menus. This chapter

discusses these classes in some detail and establishes the criteriafor effect ive use of the Men u system.


• Me nu te rminology

• Ov erview of class com pon ents

• Relat ionships betw een m enu classes

• M enu propert ies

• Act ivat ing the m enu

N o t e : Th is chap ter assum es that you are fam iliar with theconcepts and terminology associated with CA-Clipper 'spredefined classes as discussed in the "Basic Concepts" chapterof this guide.




Menu Terminology

Menu Terminology

A menu is a user-interface element that presents a l ist of choices.Menus usual ly appear in an appl icat ion 's menu bar, whichgenerally appears across the top of the screen.

Typical ly, wh en a menu is selected in a me nu bar (with themo use or keybo ard) , it displays a me nu of items (menucommands, separators , other menus, and so on) . However, i tcan also immediately perform an act ion (for example, an Exitmenu that qui ts the appl icat ion when selected) .

Menu separa tor

The sample menu shown below i l lustrates some of thecomponents avai lable to you using the Menu system:

M e n u n a m e

Menu bar

- Menu commands

Pul ldown menuCascad ing menu

In this i l lustration, the menu bar is created using theTopBarMenu class . The Edit pul l -down menu and the Edit Findcascading menu are created using the PopUpMenu class . Allmenu commands, including the menu separator, and al l menunames shown on the menu bar are defined using the Menultemclass.

The Menultem class al lows you to associate a menu i tem withei ther a m enu ba r or m enu , def ine propert ies for the menu i tem(such as accelerator and shortcut keys), and associate an action

with the menu i tem (such as displaying a menu or performing anoperat ion against a database) .

8-2 CA-Cl ipper



Overview of Class Components

This example illustrates one way to design a menu, but there arema ny other way s. For exam ple, it is not necessary to have amenu bar.

You can use the PopUpMenu class to define a pop-up menubased on some other user action. This chapter concentrates onthe standard menu setup described here to il lustrate variousfeatures of the M enu system.

Tip: Regardless of the nature of the me nu you w ant tocreate, the most important guidelines to follow are ease ofuse and consis tency.

Ov erview of Class C om po nen ts

Each class in the Menu system defines a class function, as well asmeth ods and instance variables that you wil l use wh en wri t ingcode to bui ld and manipulate menus.

Class Functions

You create menu bars , menus , and menu i tem s using funct ionsassociated with each individual class . These funct ions, wh ich arediscussed in more detail later in this chapter, are TopBar(),PopUp( ) , and Men ultem () . Each creates an object and sets upsome basic, required properties for the object by assigningargum ent values to instance variables . For exam ple, Top Bar()assigns values to TopBarMenu:row, TopBarMenuilef t , andTopBarMenu:r ight to define the locat ion and width of the menu

bar. M enu ltem () , am ong other things, assigns a men u name orcode block to the Men ultenr.data instance variable to determ inethe action to take when the item is selected.




Overview of Class Components

Instance Variables

You define other, opt ional propert ies for menu objects byassigning values to instance variables . For examp le, you candisable a menu i tem by assigning false ( .F.) to Menultem:enabledor specify colors for a m en u bar or men u using the colorSpecinstance variable , avai lable for both TopBarMenu andPopUpMenu objec ts .

Methods

You establ ish the relat ionships between individual componentsof the overal l menu system using methods defined for the

various menu classes . For example, the addl tem() method,def ined for bo th the Top BarM enu and PopU pM enu c lasses , addsan i tem to the end of a menu bar or menu.

M etho ds are also used to m ake the object perform act ions. Forexam ple , TopBarM enu:d isp lay( ) ac t iva tes a men u bar byshowing i t on the screen.

Final ly, methods supply information about the current s ta tus ofobject . For example, MenuItem:isPopUp() te l ls you whether them enu i tem is associated w ith a m enu ( in which case i ts datainstance variable is a PopUpMenu object) or an act ion ( in whichcase its data instance variable is a code block).

Many, though not a l l , of the instance variables and methodsassociated with the Menu system classes are discussed and usedin exam ples throu ghou t this chapter. For a com plete lis t andexplanation, refer to the entry for the individual class in theReference Guide.

8-4 CA-Clipper



Relationships Between Menu Classes


Using the sample menu illustrated earlier, you can easily see therelat ionships betw een the three men u classes.

TopBarMenu

TopBarMenu defines the menu bar, which controls the overal lm enu . To create a top bar me nu , you use its class func tion,TopB ar() . This funct ion creates a com pletely generic menu barby defining the location of the menu bar (that is, i ts row andstar t ing and ending column posi t ions) .

For example, the following code creates a menu bar and stores itin the variable oTopBar. W hen displayed, the me nu bar wil l beplaced on the top row and take up almost the entire width of an80-column screen:

// Create a menu bar at the very top of the screenoTopBar := TopBar(0, 1, 7 8)

Menultem

Once the menu bar is established, the next step is to define amenu i tem for i t, wh ich you do by f i rs t creat ing a M enu ltemobject then addin g it to the men u bar. In this cod e, a m enu ba ritem na m ed Exit is add ed that term inates the app lication. TheMenultem() class funct ion and the TopBarMenu:addltem()methods are used, which have been mentioned already.

oTopBarraddltem(Menultem("Exit", {|| ShutDown()}))





PopUpMenu

It is not typical, however, for an item on a menu bar to bedirect ly associated with an action as in this example. Instead,

menu bar items are usually associated with a pull-down menu.The menu item is still added using the constructionTopBarMenu:addItem(MenuItem()), but you specify the name ofa PopUpMenu object instead of a code block.

To accomplish this, you must first create the pull-down menu.Use the PopUpO function to create a generic PopUpMenu object,associate the menu with the menu bar, then add items to themenu in the same manner as you added them to the menu bar.This example illustrates:

#include "Inkey.ch"

// Create a new menuoPopUp := PopUp()

// Associate oPopUp with oTopBar menu bar item, FileoTopBar : addltem (Menultem ( 1 &File" , oPopUp) )

// Add some items to the newly created menuoltem := Menultem("&New", {|| MyCreateFile()}, ;

K__CTRL_N, "Create a new file")oPopUp:addltem(oltem)

oltem := Menultem("&Open...", {|| MyOpenFile()}, ;K_CTRL_0, "Open a file")

oPopUp:addltem(oltem)

// Add Save menu itemoltem := Menultem("&Save", {|| MySaveFile()}, ;

K__CTRL_S, "Save a file")oPopUp:addltem(oltem)

The resulting menu looks like this:

C t r l + NC t P l + O

C t r l S

8-6 CA Clipper




More on Me nu Items

This code is fairly straightforward, but there are some interesting

features about the Menultem() funct ion that should be noted.The fol lowing l ines of code, excerpted from the previousexample, are used to demonstrate:

oTopBar:addltem(Menultem("&File", oPopUp))oltem := Menultern("&New", {|| MyCrea teFi le() }, ;

K_CTRL_N, "Create a new file")

Acce le ra to r Keys

One of the things you may notice is that the name, or caption, ofthe both menu i tems contains an & character ("&File" and"& N ew "). The & causes the let ter imm ediately fol lowing i t inthe caption to become the accelerator key for the menu item.Accelerator keys are accessed different ly depending on whetherthe m en u item is defin ed as part of a m en u bar or m en u. Forme nu bar i tems, you mu st press the let ter in com binat ion withthe Alt key (for exam ple, Alt+ F opens the Fi le me nu). For m enuitems, simply press the letter i tself (for example, once the Fileme nu is open , press Ν to select the Ne w co mm and ). Thu s, inthis example, pressing Alt+F, Ν would be a quick way to execute

the F i le New com man d.

Tip: Althoug h accelerator keys are not unde rl ined as theyare in Windows applicat ions, you can display them using adifferent color. See Specifying Colors later in this chapter formore information.

N o t e : Within a me nu bar or me nu , accelerator keys mu st beuniq ue. Us e the first letter in the men u item's caption u nless

there is a conflict, in which case you can resort to a secondarylet ter within the capt ion. For exam ple, use "&P rin t" and "P &ri ntSetup" to dis t inguish two common commands on the Fi le menu.





Ac t ion vs . Menu

A menu item can be associated with an action or it can openanother men u from which the user mak es a choice. All menu

items, how ever, eventual ly lead to an action. The Me nultem ()functio n prov ides for this flexibility by allow ing you to specify acode block or the nam e of a Pop Up M enu object as i ts secondparameter.

The most common scenario is i l lustrated in the example in whichthe menu bar item is associated with a menu and the individualm en u items are associated w ith actions. In this case, w hen theuser chooses Fi le from the men u bar, the men u associated w ithoPopUp is activa ted.

When the user chooses the New command, the code block {I IMyCreateFile()} is evaluated, resulting in execution of thefunct ion, MyCreateFile() .

Shortcut Keys

Besides associating an accelerator key with a menu item, you canassociate a key combination, called a shortcut, that executes amenu item directly, regardless of whether its associated menu is

active at the time the key com bina tion is presse d. N ote,however, that shortcut keys are limited to menu items that aredirect ly associated with a Po pU pM enu object and are notavai lable for TopBarMenu menu i tems.

The shortcut key can be any combination of an Alt, Ctrl , or Shiftkey and another key on the keyboard, all of which are defined ascons tants in Inkey .ch. Yo u specify the shortcut key, if any, usingthe third param eter of M enu ltem () . In this exam ple, K_ CTR L_Ndefines Ctrl+N as the shortcut key.

N o t e : No two m enu i tems associated with the same menu barcan have the same shortcut key. Also, since shortcut keysperform an imm ediate act ion, they should be used caut iously.For exam ple, you wo uld prob ably not wan t to assign a shortcutkey to a m enu c om ma nd w hose end result is a destruct ivedatabase operation, such as pack or zap.

8-8 CA-Clipper



Menu Properties

Status Messages

You can also define a message to display wh en a menu i tem is

selected using the fourth param eter. In this exa m ple, themessage "Create a new f i le" is displayed when the Fi le Createmenu command has focus .

Menu Properties

Earlier in this chapter, i t was mentioned that the propertiesassociated with menu components are defined using instance

variables and that the various class functions provided amechanism for assigning initial values to certain instancevariab les wh en you first create an object of that class. This w asillustrated in the previous section, although not explicitly, usingthe Menultem() class funct ion.

The general syntax for this function is as follows:

Menultem( <cCaption>, <expData>, [<nShortcut>] ,[<cMessage>] , [<nld>]) —> oMenuItem

Each pa rameter m aps direct ly to an instance variable of theMenultem class as shown below:

A r g u m e n t I n s t a n c e Va r i a b l e

<cCaption> Menu l t emxap t ion

<expData> Menul tem:data

<nShortcut> MenuI tem:shor tcu t

<cMessage> Menul tem:message

<nld> Menu l t emdd

Program ming an d Utilities Gu ide 8- 9



Menu Properties

In addition to assigning these initial instance variables duringobject creat ion, you w il l often man ipulate instance variablesdirect ly in your applicat ions. For examp le, you m ay want to addcolor to both the men u bar and i ts associated pul l-down me nus,

and you do this using the colorSpec instance variable. Mo reimportant ly, you may want to manipulate menus on an i tem-by-i tem basis , including enab ling /dis abl in g an i tem or placing acheckmark next to an item to indicate that i t is selected.

The next examp le bui lds on the previou s one. I t demonstratesusing various instance variables to create a more effective andvisual ly appeal ing m enu . After the code lis t ing, theenhancements are discussed in more detai l .

#include "Inkey.ch"#include "Button.ch"

// Create a menu bar at the very top of the screenoTopBar := TopBar(0, 1, 78)

// Add color to the menu baroTopBar:colorSpec := "B/W,GR+/RB,R/W,G/RB,N+/W,W+ / B"

// Add color to menu immediately after creating itοPopUp := PopUp()oPopUp:colorSpec := "B/W,GR+/RB,R/W,G/RB,N+/W,W+/B"

// Associate menu with oTopBar menu bar item, FileoTopBar:addltem(Menultem("&File", oPopUp))

// Add some items to the newly created File menuoltem := Menulte m("& New", (|| MyCr eateF ile() }, ;

K_CTRL_N, "Create a new file")oPopUp:addltem(oltem)

// Disable the Save menu choice immediately after// creating itoltem := Menultem("&Save", {|| MySaveFile()}, ;

K_CTRL_S, "Save a file")

oltem:enabled := .F.oPopUp:addltem(oltem)

8-10 CA-Clipper



Menu Properties

// Add a separator and other menu items, such as// Print and ExitoPopUp:addltern(Menultem(MENU_SEPARATOR))

// Create an Edit menu, attach it to menu bar, and// add some items to it, such as Undo, Cut, and Copy

// Add a separatorοPopUp:addltern(Menultem(MENU_SΕΡARATOR))

// Add Edit Go menu item, whi ch will result in a// cascading menuoPopUpl := PopUp()oPopUpl:colorSpec := B/W,GR+/RB, R/W, G/RB, N+/W, W+/B

oltem := Menultem( &Go , oPopUpl)// Add some items to the Go cascading menuoltem := Menultem ( &Go To... , {|| MyGoT oLine( )}, ;

K_F5, Go to a specific line number )oPopUpl:addltem(oltem)

// Change the style of the Go cascading menuoI tem:style := CHR(251) + >oPopUp:addltem(oltem)

// Add another separator

oPopUp:addltem(Menultem(MENU_SΕΡARATOR))// Add one final menu item to the Edit menu

// Create a third menu called Options and attach it// to the menu barοPopUp := PopUp()oPopUp:ColorSpec := B/W, GR+/RB, R/W,G/RB, N+/W, W+/BoTopBar:addltem(Menultem( Ôptions , oPopUp))

// Add the first item to the Options menu

oltem := Menultem ( AutoSave , {|| MyAuto Save() }, ;, Toggle auto save preferen ce )

// Place a check mark next to this new itemoltem:checked := .T.oPopUp:addltem(oltem)




Menu Properties

N o t e : Yo u could turn this cod e into a functio n and simp lyreturn oTopBar to the calling routine w hich wo uld , in turn,displa y and activate the entire m enu system . This techniq ue isdiscussed later in this chapter under A ctivat ing the Menu and

il lustrated in the sample p rogram M enu.prg , located in yourCA-Cl ipper SOU RCE \ SAM PLE di rec tory.

Specifying Colors

The colorSpec instance variable is defined for both theTopB arMen u and Po pUp M enu c lasses , a l lowing you to def ineseparate colors for the m enu bar and each pul l-down men uassocia ted with it . In this exam ple, the sam e color string is used

for the menu bar and all other menus in the system:<oMenu>:col orSpec := "B/W,GR+/RB, R/W,G/RB,N+/W,W+/B"

colorSpec uses posi t ional param eters to identify areas of a m enufor w hich yo u can specify colors. If you do not explicitly assign avalue to colorSpec, the default colors are determined bySETCOLORQ, as indicated in the table below:

Position Defines Color for SETCOLORO Default

1 Unselected me nu i tems Unselected2 Selected me nu i tem Enha nced

3 Accelerator key forunselected menu i tems

Background

4 Accelerator key forselected menu i tem

Enhanced

5 Disabled m enu i tems Standard

6 Men u border Border

8-12 CA-Clipper



Menu Properties

Menu Separators

The Menultem:caption instance variable has already been

discu ssed in this chap ter. In particu lar, you hav e seen how itdefines the text associated with a menu item and how it can beused to define the accelerator key for a menu item.

This example in t roduces another use for M enul tem xap t ion ,which is to define a horizontal l ine to separate menu choices intological grou ps. For exam ple , in the File m en u, the Printcommand is separated from the New, Open, and Savecommands .

To define a separator, use the constant valueM EN U_ SEP AR AT OR (defined in the header f ile , But ton .ch)where you would normally specify a menu capt ion:

oPopUp:addltem(Menultem(MENU_SEPARATOR))

The m enu separator is not selectable and cannot have an act ion,message, shortcut, or id associated with it .

Toggles

Some menu i tems represent a f lag, or toggle, that somehowaffects the beh avio r of the overall system . Op tions Au toS ave issuch a menu i tem, determining whether changes being made bythe user are automatically saved periodically by the system.

This type of menu item is either on or off, a condition usuallyindicated by the presence or absence of a checkmark (see MenuItem Indicators below for more information) to the left of them enu i tem. You specify that a me nu i tem is on (checked) byassigning a value of t rue ( .T.) to Menultemxhecked:

oltem:checked := .T.

By defaul t Menultemxhecked is false ( .F.) , which means thatmenu i tems are not checked.




Menu Properties

You can build program logic that changes the status ofMenultemxhecked and controls behavior based on i ts currentstatus. This techniq ue is not il lustrated in the exam ple be caus eall of the action code blocks are over-simplified; however,

mo difying the example s l ight ly can easi ly show how i t might bedone. The code block in the example for Option s AutoSave lookslike this:

{ MyAutoSave()}

Changing it as follows has two effects: switchingMenultemxhecked to i ts opposi te value and cal l ing theSetAutoSave() funct ion using this new value:

{|| oltem:checke d := oltem:checked, ;SetAutoSave(oltem:checked)}

SetAuto Save() is a s tandard s et / ge t funct ion that returns thecurrent set t ing when cal led without an argument and changesthe current setting when called with an argument:

FUNCTION SetAutoSave(lNew)STATIC lSetAutoSave := .T.LOCAL lOld

IF lNew = = NILRETURN 1SetAutoSave

ELSEIF VALTYPE(lNew) == "L"lOld := lSetAutoSavelSetAutoSave := lNewRETURN lOld

END IF

To control logic in other parts of the application based on thisset t ing, s imply cal l SetAutoS ave() witho ut an argu men t:

IF SetAutoSave()// Code to do auto saving on periodic basis

END IF

Final ly, to make the menu defini t ion more dynamic, you wouldcal l this funct ion to determine the original Menultemxheckedstatus instead of assigning the constant value of true (.T.) as inthe original exam ple:

oltem:checked := SetAutoSave()

8-14 CA-Clipper



Menu Properties

Disabling Menu Items

Menu items that are not meaningful to the current state of the

app lication are usua lly disab led. For exa m ple , the File Sav e andFile Print menu items might be disabled initially because there isno open file to save or print.

Assign false (.F.) to the Menultem:enabled property to disable amenu i tem:

oltem:enabled := .F.

By defaul t , men u i tems are enabled ( that is , M enultem :enabled istrue (.T.)).

In the examp le, the value of the Menu ltem:ena bled f lag is s im plyset to a cons tant valu e of false (.F.), but in a real men u you w ou ldseldom d o this . Instead, you w ould m ake the ini tia l valuecontin gent on som e other logical setting. For exa mp le, theUSEDQ function (which determines if there is a database file inuse in the current work area) is a valid indicator for whether theFile Save and Fi le Print comm and s shou ld be avai lable each t im ethe menu is displayed:

oltem:enabled := USED()

Cascading Menus

A cascading menu, or submenu, is any men u selection that resultsin the display of another men u. Subm enu s s implify the top-levelmenus by limiting the number of items that are initiallydisp layed . This allows the user to see the mo st imp ortantcommands while browsing through the menus without beingdistracted by the details of submenus.

This is well- i l lustrated in the exam ple. The Edit menu h as a Gocom m and that resul ts in a subm enu. Thu s, wh en the user seesthe main m enu , i t is imm ediately a pparent that the m enusupports database navigat ion. The detai ls of Go To, Go Bottom ,and Go Top, however, are hidden within the submenu.




Menu Properties

The example code shown earlier did not give all the details thatare shown below:

// Add Edit Go menu item, which will result in a// cascading menu

οPopUp1 := PopUp()oPopUpl:colorSpec := "B/W,GR+/RB,R/W,G/RB,N+/W,W+/B"oltem := Menultern("&Go", oPopUpl)

// Add some items to the Go submenuoltem := Menultem( "&Go To.. .", {|| MyGoToLine()}, ;

K_F5, "Go to a specific line number")oPopUpl:addltem(oltem)

oltem := Menultern("G&o To Top", {|| MyG oTo p() }, ;K_CTRL_HOME, "Go to top of file")

oPopUpl:addltem(oltem)

oltem := MenuIte m("Go To &Bottom", ;

I I MyGoBot tom() }, K_CTRL_END, ;"Go to bottom of file")oPopUpl:addltem(oltem)

Menu Item Indicators

Most, but not all , of the information that appears as part of amenu i tem is defined through i ts MenuItem:caption instancevariable. For exam ple, whe n you define a shortcut key, the keynam e is automatical ly displayed to the r ight of the men u i tem ,

without explicitly including it in the caption.

On the other hand, if you want to indicate that additionalinforma tion wil l be required wh en a men u i tem is selected (forexample, the user may be required to fil l in a dialog box), youmust include the ellipsis (. . .) as part of the caption:

oltem := Menultem ( 1 &Open..." , {|| MyOpenFile () } , ;K_CTRL_0, "Open a file")

8-16 CA-Clipper



Act iva t ing the Menu

Two items that are automatically included as part of a menuitem's display are the checkm ark V ) used to indicate thatMenultem:checked is true (.T.) and the solid arrow (•) used to

indicate that a me nu item results in a sub me nu . The re is nev er aneed for any code that writes these characters as part of themenu display, but you can control which characters are used viathe Me nultem rstyle instance variable. M enu ltem :style is a stringcontaining exactly two characters: the first is the character todisplay i f M enu ltem xh eck ed is t rue ( .T.), and the second is thecharacter to use if a submenu results.

In the example code, this is demonstrated for the Go submenu, inwhich the Menultem:checked character is left at i ts default value

while the submenu indicator is changed to the greater thansymbol (>):

oItem:style := CHR(251) + ">"

Activat ing the Menu

Use the MHNUMODAL() funct ion to display and act ivate themenu bar, as shown below:

oMenuBar := Menu_Create()DO WHILE MENUMODAL(oMenuBar,1,24,1,79,"R/W") <> 999ENDDO

This assumes that a TopBarMenu object , oMemiBar, is return edby the function Menu__Create(). This is the first argument forM EN UM OD ALQ . The remain ing arguments spec ify the pos i t ionof the menu bar item that is selected when the menu is firstactivated (1), the row and left and right column positions of themessage l ine ( 2 4 , 1 , 79), and the color specification for messages( " R / W " ) .

N o t e : M essag es are define d for each men u item using theMenultem:message instance variable.




Act iva t ing the Menu

Because MENUMODAL0 takes only a single menu event fromthe user then term inates, i t is necessa ry to put the fun ction call ina continuous loop, as in the example. The function returns theMenultemiid of the selected menu item, so you can set up a

condition for breaking out of the loop based on the menu's exitoption.

In this case, i t is based on the File Exit menu command:

oltem := Menultem("E&xit", {|| .T .} , ;K_ALT_F4, "End of application", 999)

Menultemdd is specified as the fifth, and final, Menultem()param eter. No te that no two men u i tems associated with thesame menu bar can have the same id.

8-18 CA-Clipper



Chapter 9

Error Handling Strategies


Earl ier versions of CA-Clipper responded to runt ime errors bypassing control to one of six routines you could write in

CA -Clipper . Error creat ion, how ever , wa s st i ll done by codedeep in the heart of CA-Clipper so that you could only respondto a prede fined set of errors . You r encounter w ith errors w aspurely react ive and, while you could customize the react ion, youcould only do i t global ly. You cou ld not instal l and rem ove errorhandling code on the fly.

In CA-Clipper appl icat ions, the l ine between internal and yourown error handl ing code has blurred to the vanish ing point . No tonly can you custom ize the response to an error, you cancustomize the error. The mechanisms for custom errors andCA-Clipper errors are the same, and you are free to create andhandle your own errors in emulat ion of system errors .

The first part of this chapter is intended to give you some insightinto theoret ical error hand l ing s t rategies without giving you anyspecif ics on how you would implement those s t rategies inCA -Clippe r. Th e idea is to give you an understan ding of thebasic design of the error system before the implementat iondetai ls are d iscussed.

Nex t , you are introduced to the specific CA-C lipper languag eelements designed to implement the descr ibed error handl ingstrategies . Each element is presen ted fol lowed by an exam plethat shows how best to use it .




Overview of Except ion Handl ing Concepts

This chapter is theoretical in nature and is not intended as atutorial on how to use the CA-Clipper error handling system noris i t intended to compare the error handling systems of previousversions to the new system. I t does, howeve r, provide an in-

depth analysis of error handling strategies, as well as severalexam ples w hich, i f s tudied careful ly, can be used as models foryour own error handl ing implementat ions.

This chapter introduces you to the CA-Clipper error system,star ting with an overview of general except ion handling theorythen progressing through the role of exceptions in modularappl icat ions. The fol lowing m ajor topics are discussed:

• Ov erview of except ion hand ling concepts

• CA-C l ipper except ion mechanism s

• Error objects

• A base line strategy

• Ne twork processing

Overv iew of Except ion Handl ing Concepts

Error processing works well with modular archi tecture, whereapplicat ions are broke n into com pone nt modu les . Self-contained, independent modules avoid interappl icat iondepe nden cies and unforese en side effects . CA -Clipperarchi tecture promotes use of the modular model .

A module can be a simple function, but more often it is amulti-function subsystem defined in a single source file. In orderto scope variables and functions to that fi le, the module util izesSTA TIC declarat ions. The re is , typical ly, a logical coherencyam ong the funct ions you include in a subsystem. They al l servesome common purpose, which is your rat ionale for assigningthem to a module.

9-2 CA-Cl ipper




Other modular languages use different terminology, but theconcep t is the sam e: port ions of an applicat ion with com mo nfunctionality are combined in units. Among these units there is

specific division of labor and allocation of respo nsibility. Acom plete app licat ion is a joining of these su bassem blies .

In a modular applicat ion, interact ion between modules is formal ,almo st contractual , as i l lustrated b elow .

Software Element

There is an implied contract between a cl ient module and acontractor mod ule. The cl ient assigns the contractor bothresponsibi l i ty and authori ty for perform ing the special ized jobfor wh ich i t wa s d esigned.

Each mo du le has specific r ights and obl igat ions. The cl ient mus tsupp ly the contractor with the necessary input param eters , orraw m aterials , in prop er form and num ber. In return, thecontra ctor owe s the client the results of ope ration s. Thecontractor can expect prop er input , and the cl ient can exp ectproper output .

Client

Contractor





Error Scoping

Loc alization is the key to effective error proc essing. A m odu lewith responsibility for some well-defined part of theapplication's functionality should also take responsibility forpossible malfunct ions. The contractor should process departuresfrom norm al funct ional i ty. A "depa rture from no rm al" is cal ledan exception, bec au se it is excep tional to expec ted behav ior.

Processing enc om pas ses both sides of a runtim e error: generating(detecting, raising, asserting) and responding (reporting,handling) . Runtime errors do not merely occur in CA-Clipper—they are explicitly created . The proce ss of detecting an errorcondition and displaying an alert message is called raising an

error.

An applicat ion shou ld include excep tion handling as part of itsprimary functionality rather than patch it in as an afterthought.The right place for code that handles errors pertaining to acertain modu le of an application is normally within that samemo dule. This is cal led localization of error proc essing.

In-module coding is not the only way to localize error handling,even thou gh it is the most com m on w ay. Yo u can also localize to

sub-modular or supra-modular s t ructure. Such local izat ion can,with proper coding, span a function, a statement, or a statementsequence, or the error handling can be invoked over severalmodules through calling routines or other activations.

9 -4 CA-Cl ipper




Error processing, l ike other aspects of CA -Clipp er, conform s tolexical scop ing. Tha t is, error handlin g proce dur es are part ofthe context of the software elements in which they are written, sothey have similar scoping. The illustration below shows threesoftware elements, layered like an onion:

Outer layers contain or call inner layers, and some error-proc essing cod e lies within each layer. An error raised by theinnermost layer falls in that element's context and receivesimm ediate processing by the error handling code scoped to thatlayer. The error also falls within the context of all surro und inglayers and, if not resolved within the inner layer, can be passedto the error handling code scoped to the outer layers. Note thatthe contexts surrounding an error depend on the callingsequ ence on any particular activa tion. Later, if a different set ofcallers invokes the same inner element, the same error will havea different overall context.

What this does is localize the error handling to the place closestto its raising. It frees clients from inv olvem ent w ith acontractor 's difficulties. Should the contractor successfullyrecover, the cl ient proceeds una wa re that an incident occ urred.The author of the error handler is l ikely to intelligently interpretthe error and respond approp riately.




Overview of Exception Handling Concepts

Raising Errors

Errors have their roots in assertions . An assertion is an inlin e testof run tim e adh erence to specification. It can be as simp le as anIF statem ent who se control condition returns true (.T.). Failureof the IF test constitutes an excep tion. Assertio ns have thefol lowing general pseudocode form:

IF .NOT. AsItShouldBeREACT

ENDIF

N o t e : W heth er all excep tions are errors, or only som e, is ama tter of opin ion. If und er some circu msta nces it is okay for thecondition to be false, but you code the assertion just because you

still want to know about it , you probably would not label theexception erroneous.

Upon error detection, the reaction is to launch into errorproc essing . This usually m ean s transfer of control to applicationcod e designed for that pu rpo se. Execu ting that code is calledhandling the error.

You can see that errors are not self-generating or self-defining.The y do not just happe n. Errors are reports of poss ible, thoug hexceptional , behavior. Error hand ling is premeditated.

The following pseudocode illustrates use of assertions in thecontra ctual context. The assertions verify con form ity tocontra ctual respon sibilit ies. In this simp lified case, the mo du le isa fun ction that derives square roots. The function has the rightto insist on only non-negative numbers and has the obligation toreturn a correct value—one that returns the square whensquared.

9-6 CA-Clipper




An assertion at the top ensures that the function complains if i treceives invalid input. Another at the bottom enforces validoutp ut, testing it inde pen den tly of the deriva tion algorithm . If

that algorithm involves generating a mathematical series whoseterms should converg e, another assert ion could sound an alarmif they began to diverge:

FUNCTION TakeSquareRoot(nSquare)// Precondition: at this point nSquare had// better be non-negative

IF (nSquare >= 0)REACT

END IF

. <statements>

// Postconditio n: at this point nRoot * nRoot// had better yield nSquare

IF (nRoot * nRoot = nSquare)REACT

END IF

RETURN nRoot

It is natural to expect these errors. You should anticipate them,then insert appropriate assertions in your code. Otherwise, youmay encounter s t range resul ts without knowing why.

Unanticipated errors can cause unpredictable program fai lures .An error is far preferable.




Overview of Except ion Handling C on ce pts

Handling Errors

As a cont ingency, an appl icat ion should general ly provideexcept ion han dling code . Such code should be s t rategical ly setaside in error handlers where i t wil l be avai lable when needed.On one h and , it is separate from the main co de; on the other, it isintegra l to the applicatio n. It is as imp ortan t to an a pplica tion'sdes ign as fire stairs are to a bu ildi ng 's desig n. It m ay get less usethan the main hallway, but i t is no less essential.

The location of this code within the source is less important thanits availab ili ty to the app lication at run tim e. W he nerror-handling code is encountered during runt ime, the maincode is abandoned as i l lustrated below:

Main Code

At the discret ion of the error hand ler, control may or ma y notreturn to the main cod e. I f i t doe s, the main code mu st bewritten to retake control gracefully (retry, default handling, orsubst i tut ion opt ions precoded) .

When the error-handling code gains control , there are only twotheoret ical opt ions: re try or term inate . Gen eral ly, re trying m eansfinding som e wa y to procee d. This may am ount to a s imp le,brute force retry, but i t is usual ly m ore elab orate , includingat tempts to ident i fy and rem edy the cause of the error condit ion.

Exception Code

9-8 CA-Clipper



Overv iew o f Excep t ion Hand l ing C onc ep t s

The retry need no t be perform ed by the error handler. I f theerror-originating code is written to retry on its own (equippedwith a loop, for exam ple) , the error hand ler can s ignal the

original cod e to give it a try. Th is necessitates a pr otocolwhereby the originating code indicates its readiness to retry ifasked, and the error handler asks by returning someprede te rmined va lue .

Variat ions on the theme are defaul t handl ing and subst i tut ion.Sup pose that error-generat ing code is wri t ten so i t can p rocee deven i f the error condit ion is not remo ved . I f i t comm unicate sthat fact w hen cal l ing an error han dler, the error handler has theoption of returning control to the original code for continuation.Similarly, if the original code's purpose is to derive a value but i tis written to accept a substitute value if derivation is impossible,an error handler has the option of returning a substitute value tothe main code (for example, zero to a routine that tries to divideby zero ) .

Terminat ion also has a broader meaning than just hal t ing andreturning to the operat ing system . M ore general ly, i t m eansterminat ing the at tempt to perfo rm the current operat ion andsignaling failure to the original invoker (client), with or withoutprior c lean-up (for example, c losing f i les) . The invoking process

then decides w heth er i t can tolerate the fai lure and w hat ,accordingly, to do next . This is som etimes cal led p ropag at ingthe error to the client or outer context.




CA-Clipper Except ion Mechanisms

CA-Cl ippe r Excep t ion Mechan i sms

CA-Clipper imposes no error-processing protocol onapplications but gives you the tools to do so in your own way.These tools, and their practical application, are the focus of thissection.

In CA-Clipper, there are two mechanisms for processingexcept ions, the SEQUENCE construct , and a posted code block(the error block). W ith these me chan ism s as tools , you can bui lddifferent approache s to error hand l ing. You can, if necessary,use these tools to emulate the fixed, more rigid behaviors ofo ther program ming languages .

The tw o mec han isms differ in the locat ion of error-handling codeand how i t is cal led. In the SE QU EN CE construct , error-hand ling code is inl ine (part of the RA M image of the loadedapplicat ion) and is cal led by issuing a BR EA K statemen t . In theerror block approach, i t is stored in memory (as a code block)and is t r iggered using EVAL().

In general , use SEQUENCE for appl icat ion-specif ic except ions(for example, "debi ts do not equal credi ts ' ' , " inventory isnega t ive" , "m y boom erang w i ll no t come ba ck") , and e rror b lockfor generic, low-level exceptions that usually deal with thecomputer and could ar ise across appl icat ions (for example,"device not ready", "disk ful l" , "s tack overf low").

9-10 CA-Cl ipper




The SEQUENCE Construct

The basic form of a SEQUENCE construct is shown below:

BEGIN SEQUENCE

. <statements>

RECOVER USING ---

. <statements>

Between the BEGIN SEQUENCE and RECOVER s ta tements i sthe main code; between RECOVER and END is error-handlingcode . The error-handling code is cal led a RECOVER statementblock.

A BREAK statement permits the RECOVER statement block togain control . W ithout on e, the block never executes; instead,control jumps past the END statement when the RECOVERstatement is encountered .

BREAK represents the concrete react ion (pseudocoded usingREACT earlier in this chapter). Any assertion in the main codeshould, when violated, provide a BREAK, abandoning the maincode and passing control to the RECOVER code.

END




CA-Clipper Exception Mechanisms

BREAKs can be nested, as shown below:

E N D

fϊ

Here an assert ion passes control to the RECOVER code whetherappearing in the main code itself; one activation removed, as inU d f l ( ) ; or two act ivat ions removed, as in Udf2() .

9-12 CA-Clipper




You can also nest SEQUENCE constructs , as shown below:

B E G I N S E Q U E N C E

IF .NOT. A -O K

BREAK

ENDIF

UDF1Q

R E C O V E R U S I N G

E N D

F U N C T I O N U D F I Q

B E G I N S E Q U E N C E

U D F 2 Q

IF .NOT. A -O K

BREAK

ENDIF

R E C O V E R U S I N G

E N D

RETURN NIL

F U N C T I O N U D F 2 Q

IF .NOT. A -O K

^ BREAK

ENDIF

E N D

RETURN NIL

Here, Udfl() contains i ts own SEQUENCE construct , so theassert ions in Udfl() or Udf2() now cal l the RECOVER code localto the context of Udfl(), not that of the original outer sequence.To return the error to the outer sequence would require aBREAK s ta tement i ssued wi th in Udf l ( ) ' s RECOVER s ta tementblock.

This il lustrates the practical side of error contexts in CA-Clipper.BEGIN SE QU EN CE s ta tements de l imi t context boundar ies .Each t ime you encounter a new BEG IN SEQ UE NC E s ta tement ,you cross into a new context, with its own local (thoughoptional) RECOVER statement block. You exi t that context whenyou leave the main code sequence (whether enter ing or jumpingthe RECOVER statement block) .





Activ ation boun dar ies do not, necessa rily, define contexts. Forexample, the same function can be part of different contexts atdifferent tim es. If Ud f2() is invo ked by an other caller, i t is partof that caller 's context. Since you can bracket any code you likewith a SEQUENCE construct , CA-Clipper le ts you definecontex ts quite flexibly. Co ntexts lie w herev er you put yourSEQUENCE cons t ruc ts .

The fol lowing example shows the suggested general form ofsuch a s tatement block. A CA SE statement responds to whatevererrors the programmer ant icipated when wri t ing the program.W here control passes next is governed by wh ether a QU IT,BR EA K, or RE TU RN appears . I f you supply no such code,control passes through the END SEQUENCE statement to

whatever code fol lows.// General form of SEQUENCE construct// and RECOVER clause

BEGIN SEQUENCE

IF lProblemlobjError := ErrorNew()

<stuff objError>

BREAK obj rrorENDIF

IF lProblem2objError := ErrorNew()

<stuff objError>

BREAK obj rrorENDIF

9-14 CA-Clipper




RECOVER USING WhatItsAllAbout

DO CASECASE <obj-related condition>

<handling>CASE ...

<handling>BREAK WhatltsAllAbout // Optional propagation

CASE ...<handling>

OTHERWISE

BREAK WhatltsAllAbout // Optional prop agation

ENDCASE

END SEQUENCE

Th ere are several special cases you should con sider. Anapplicat ion that does not use SEQUENCE constructs has DOS asi ts implici t outer context . A BR EAK anyw here in the applicat ionleads to the DO S prom pt. On e with a s ingle SEQ UE NC Econstruct surrounding the ini t ia l main menu module has thatmodule as outer context , with any BREAK returning there l ikeRET UR N TO MA STER . (Dot .prg in your CA-Cl ipperSO UR CE \ SA M PL E directory i l lustrates this case.)

Ult imately, you can bracket s ingle s tatements with a SEQUENCEconstruct , with RE CO VE R code for that s tatement alone. I f thats tatement is an invocat ion of DBEDITQ, ACHOICEQ, orMEMOEDITQ, s trategical ly dis tr ibuted BREAKs in the cal leduser funct ion can be used to exploi t the RECOVER code.Otherwise, there may be no apparent opportuni ty for a BREAK.How, for example, would you issue a BREAK statement from"w ith in" a USE com ma nd ? In cases of system errors raisedwithin the s tatement , however, you can accomplish this usingthe posted code block and indirect breaking mechanism

discussed below.




CA-Clipper Exception Mechanisms

The Posted Error Block

The error bloc k is a code blo ck writte n to han dle errors. It isdis t inguished by being posted, or installed in a designa tedm em ory location . Installation and later retrieval is don eexclusively through the ERRORBLOCK() funct ion.

ER RO RB LO CK () views the block as data , not code. (Thehallmark of code blocks is that they are hybrid: data thathapp ens to contain cod e, or code that can otherwise be hand ledl ike data .) ER RO RB LO CK () co ntains, in effect , a static variable,or slot for storing data accessible to itself alone, butERRORBLOCK() i tself is global ly accessible .

Because ERRORBLOCK() can instal l any code block, any part ofthe applicat ion can dynam ical ly install i ts own new code.

The posted co de block is s t rategical ly important becauseCA-Clipper 's uncondit ional behavior when rais ing an error is toretr ieve i t with ERRORBLOCK(), then execute i t with EVAL().W hen y ou post an error block, you are specifying code forCA -Cli pp er to execu te next time there is an error condition. Yo uget to wri te CA-Clipper 's response. Also, ERRORBLOCK() andEVAL() let you make your applicat ion 's response the same asCA-Clipper 's when one of your assert ions is violated.

To illustrate, consider a deliberately erroneous call to a systemfunct ion, say VA L(99). You kn ow VA L() 's job is to return anumeric from a string of numerals, so it requires a character typeargum ent . Thu s, the expression VAL(9 9) produces the followingscreen output:

Error BASE/1098 Argument error: VALCalled from MAIN(l)

Errorsys.prg ( located in your CA-Clipper SOURCEXSYS

directory) contains the source code for the standard errorhand ling rout ine provided as part of CA-C lipper. I f you look atthis source cod e, you w il l see a procedu re nam ed ErrorSysQ,which is executed automatically at the outset of everyapp lication. It conta ins a single line:

ERRORBLOCK({|e| DefError(e)})

9-16 CA-Clipper




This l ine of code creates a code block that cal ls a funct ion na m edDefErro r() (also defined in Errorsys.prg) an d cal lsER RO RB LO CK () to instal l that block at runt im e. Then , w henCA -C lipp er raises any error, a call is issued to D efErr or(). If youlook at the source for DefError() (also defined in Errorsys.prg),you can ident ify the code responsible for the error m essage . (Theparam eter that is passed to DefError is an Error object, w hichwill be discussed later in this chapter.)

The VA L() funct ion do es not cal l DefError() direct ly. I t doe s,however, fetch and execute the current ly posted error block incase of an error, as do all other run tim e errors. It doe s not kn owor care about the code block 's con tents , w ho po sted i t , or h ow

long ago.

If the default posted block is stil l in place, DefError() will get acal l . I f , ho w ever, you replace the block , you replace the errorbehav ior. For exam ple, i f you w ri te a funct ion that r ings the bel l ,you would install i t as follows:

ERRORBLOCK({|e| MyBellRinger(e)})

Then, a call to VAL(99) w ould r ing the bel l .

This exam ple uses the basic error block form . TheERRORBLOCK() funct ion instal ls the code block passed to i t ,retaining the old bloc k by assign ing it to a varia ble. Yo u th enhave the opt ions of executing the previou sly instal led block andreinstalling it once your subsystem is no longer in control:

// ERRORBLOCK() --> {|e| <SomeExp>}bOldBlock := ERRORBLOCK({|e| MyErrHan(e)})// ERRORBLOCK() --> {|e| MyErrHan(e)}// bOldB lock --> {|e| <SomeEx p>}

This error block retains, and later executes , i ts p redecess or:

bOldBlock := ERRORBLOCK({ |e | MyFunc (e ) ;EVAL(bOldBlock, e)})

This technique is the basis for error block chaining. The instal ledbloc k 's execution of its predec essor as i ts "f inal ac t" is equiv alentto termina t ing and p assing control to the predecesso r.

Pro gram min g an d Utilit ies G uid e 9-17




N otice the im plica tions . Th e cod e block is built at com pile time.I ts instal lat ion an d prede cessor 's assign men t to bOldBlock, and itsexecution , take place at runt im e. W hile the block contains areference to a variable called bOldBlock, nonexistent at bui ldtime, that is not a problem as long as bOldBlock exists atevaluat ion. De pend ing on i ts s torage class , bOldBlock ma y orm ay not exist a t any given mo me nt during runt ime. Declar ing i tas s tat ic ensures permanent avai labi l i ty, as demonstrated below:

STATIC bPrevHandler

. <statements>

bPrevHandler := ERRORBLOCK({|e| NewHandler(e, ;bPrevHandler)})

. <statements>

FUNCTION NewHandler(objError, bMyAncestor)IF CanHandle

. <error-handling statements>

ELSERETURN EVAL(bMyAncestor, objError)

ENDIF

9-18 CA-Clipper




SEQUENCE vs. Error Block

With SEQUENCE and with error block, you can create twoparal lel chains of com m and : a group of code blocks that E VA L()one another in a chain; and a series of nested SE QU EN CE S thatBR EA K from innerm ost to outermost . I t is natural to ask abo utthe interrelatio nsh ip. (See A Baseline Strategy later in thischapter for mor e information.)

Error code embodied in an error block, can transfer control toerror code in the current RE CO VE R statement block. H ow eve r,s ince code blocks cannot execute s tatements such as BREAK,there is an equivalent BREAK() function that you use for this

purpose.

The fol lowing example shows how a system-level runtime errorcan lead to RE CO VE R code . The error originates in code w herea surround ing REC OV ER statemen t block is pend ing. Like allsystem errors, i t executes the installed error block; however,because the error block cal ls the BREAK() funct ion, RECOVERcode can receive control:

bOldBlock : ERRORBLOCK ({ | e j IIF ( <lAssert> , ;BREAK(e) , <exp>), <exp>})

. <statements>

FUNCTION SomeSubsequentFunc()BEGIN SEQUENCE

. <statements>

VAL(99)// Error arises here

RECOVER USING e

. <recovery code>

END SEQUENCE

RETURN NIL

Pro gram min g a n d Utilities G uid e 9-19




Call ing procedures differ between error blocks and RECOVERclauses. The difference is that you can RET UR N from the formerbu t not the latter. A n error bloc k executes throug h the EVA L()function, and RECOVER executes af ter a BREAK from within a

BEG IN SEQU EN CE s ta tement . Therefore , EVA L() le ts youRETURN as from any other funct ion cal l , whereas BREAK doesnot. Th e BREAK'S location is not sav ed as a return point forfuture reference. A RETURN from RECOVER goes to the mostrecent calling function , not the BR EA K location. This me ans thatin order to return to a chosen point from a RE CO VE R, you mu stwr ite code loops. It also m ean s that the discussion of errorprotocols below applies only to code block error hand lers , notRE CO VE R clause error handlers.

There are several directions for the error block to go when called.• I t can RE TU RN to the offending code, but this must be done

with care to avoid produ cing u nexpected resul ts .

• It can go to its pred eces sor error block , by EVA L().

• I t can branc h to the SEQ UE NC ES in the main applicat ioncode us ing BREAK.

• It can QU IT.

9-20 CA-Clipper



Error Objects

Error Objects

Once you understand the mechanics of invoking error code, youmust decide how to use it . That decision depends on the error 'scharacteristics, and the vehicle for characterizing it is the Errorobject.

An Error object is a package of information with several items,cal led instance variables, in each packag e. M ost of these i tem ssimply describe the error, but others tell the error handler aboutthe error-generat ing cod e itself . The error-generat ing codesupplies this package to the error-handling code. In aSE QU EN CE construct , the error object is passed as part of the

BR EA K and received by REC OV ER U SIN G. In an error block , i tis the e parameter that is passed to the code block.

The Error object 's role is that of go-between in communicationbetween the error-generat ing and error-handling code.Communicat ion is ini t iated by the former and can become atw o-w ay dialog if the latter return s. All this imp lies a third ste pin the error-g enera ting proce ss. As m ent ione d earlier, errors aregenerated by assert ions, which have a two-stage detect-reactform:

IF .NOT. AstShouldBe // detect exceptionCALL HANDLER // BREAK or EVAL(ERRORBLOCK())ENDIF

The third step is preparation of an Error object:

IF .NOT. AsItShouldBePREPARE ERROR OBJECTCALL HANDLER WITH ERROR OBJECT

ENDIF

Preparing the object amo unts to call ing the ErrorN ew() funct ionto generate an empty object, then assigning values to its instancevariables.




Error Ob jec ts

When your error handler gains control, i t has the Error object onw hich to bas e a particu lar respons e. Typica lly, i t uses a CA SEstatement. The CA SE condit ions are based on information aboutthe error conv eye d in the instance variables. This is called

specialization of error handling, and it is the means by which anError object is passed amo ng error h andlers .

The typical CASE statement provides local ized handling for themod ule that contains it and is probably most frequently invokedby errors that originate with in the m odu le. The cases are writtenaccordingly, w ith those errors in m ind.

For exam ple, in an accoun ting m odu le, you are likely to f indboth assert ions and error handler code that address knownpossibi li t ies l ike "invento ry fel l below zer o" and "d ebits andcredits un eq ua l." Th ese reflect the specialized conven tions ofthat module's world and the errors they define, but the errorhandler can also receive incoming Error objects for errors that fitnone of the cases.

These objects normally originate in a called module thatpro pag ated th em to this error hand ler. The y fall into the errorhandler 's OTHERWISE category, where the error handler canfurther process them. In a RE CO VE R USIN G clause, processingamounts to issuing a BREAK <objError> where <objError> is thesame Error object the handler originally received.

In this way, an error raised but not handled to containment in aninner mo dule is passed back up thro ugh higher con texts , each ofwh ich screens i t and has the opportun ity to respond . Ult imately,it reaches the outermost context, the application's initialproce dure. The re, i t experiences a hard landing to the DO Sprompt i f not bracketed by an outermost SEQUENCE construct .On the other hand, if i t finds a considerate containing sequencein the main p rogr am (a good p ract ice) , a graceful an d

informative message can soften the blow.

9-22 CA-Clipper



Error Objects

A Mode l Example

Reconsider VAL(99) for a moment as an i l lustrat ion of the Errorobject 's role in rais ing an error. Yo u now k now that wh en theerror block is cal led in response to the VA L(99 ) runt im e erro r,the param eter passed is an Error object . You can intercept andstudy i ts contents by wri t ing a diagnost ic U D F that displaysinstance variables , plus a two l ine main pro gram that f i rs tinstalls a block to cal l you r UD F then issues VA L(99 ). W henVAL(99) fails, i t hands control to the block, which hands it to theUDF, which displays the information on the screen.

In this example, a pseudocode of CA-Clipper 's VAL() funct ion

demonstrates that you can reproduce system error behavior inyour own code:

// Pseudocoded CA-Clipper VAL() function

FUNCTION VAL(p)LOCAL objVErr

// Assertion to verify type consistencyIF VALTYPE(p) = "C"

// Make Error U\ jectobjVErr := ErrorNew()

// Stuff Error objectobjVErr:argsobjVErr:canDefaultobjVErr:canRetryobjVErr:canSubstituteobjVErr:descriptionobjVErr:filenameobjVErr:genCodeobjVErr:operationobjVErr:osCodeobjVErr:subcodeobjVErr:subsystemobjVErr:triesobjVErr:severity

02

1"VAL"01098"BASE"

"Argument error

{p},F..F..T.

// Transfer control and ship objectRETURN EVAL(ERRORBLOCK() , obj VErr)

ENDIF

<the string-to-numeric conversion code>

RETURN <numeric result>

Program min g an d Utilities G uid e 9- 2 3



Error Objects

The System Error Line-Up: Error.ch

"Arg um ent E rror" i s a com mo nplace , p red ic tab le e rror becauseany function can receive bad parameters from its caller. In fact,this error (along with many others) is so reliably expected, thatthe CA -Clipp er runt im e support system raises i t , expl ici t ly. Theheader f i le Error.ch ( located in your CA-Clipper INCLUDEdirectory) assigns a dis t inguishing (version-dependent) code toeach of these ant icipated errors and a correspond ing (version-independent ) name.

The a nt icipated errors in Error.ch have fair ly obviou s name s l ikeEG_ ARG , EG_ NO VA R, and EG_ OPE N. EG .A RG i s t he one ju s tdem onstra ted; refer to a non-ex istent variable to raise an

EG_ NO VA R; and USE a made -up f i l ename to r a is e EG .O PE N .The names are shorthand for corresponding generic codes, oneof which appears in Error:genCode, which Error handlers canquery to ident ify wh ich type of error was raised.

To mak e the pseudoco de above vers ion- independent , you w ould#include Error.ch and assign ErrorigenCode as fol lows, insteadof assigning the value 1:

objVEr r:genC ode := EG_VAR

As indirect ly sug gested in the exam ple cod e, i f you raise you row n errors you mu st be thorou gh. Certain ap plicat ion-levelerrors you specif ical ly foresee wil l be the ones for wh ich youplace assert ions in your cod e and w hich yo u depict in their Errorobjects.

9-24 CA-Clipper



Error Objects

Carrying Error-Processing Protocols

Error object instance variables supply inform ation about not onlythe error, but also the cod e that raised it . After dealing with theerror, the handler can return control to the failed code for furtherpurpo ses, but i t general ly has no internal know ledge of this code.Therefore, it is up to the failed code to tell the error handlerwhether it is prepared to regain control, and, if so, to what returnvalues it will respond.

That is the purpose of ErrorxanDefault , Error:canRetry, andErroricanSubst i tute . The fai led code may or ma y not beequippe d to: procee d despite the error condit ion; perform a

retry; or accept a substitute for a value it failed to derive.Respect ively, the three instance variables s ignify whethe r thecod e is so equip ped . If i t is, i t per form s the defau lt, retry, orsubst i tut ion, contingen t on regaining control from an errorhandler and on the value the error handler returns to it . In thissense, the Error object is a protocol carrier.

A look at the pseudo -VAL Q show s that i t is uneq uipped to retryor defau lt, but VA L() can subs titute. By settingError:canSubstitute to true (.T.), the VAL() code is saying, "If youreturn control and a value, I will return that value to my caller."If, for exam ple, you post a code block that returns "W ack yWacky," then wri te a program to print VAL(99) , it prints" Wa c k y Wa c k y. "

ERRORBLOCK({|e | SomeHandler(e)})

FUNCTION SomeHandler(objMyErr)

. <statements>

IF objMyErr:canSubstituteRETURN "Wacky Wacky"

ENDIF

. <statements>

The pseudo-VAL() shows how to wri te code that can subst i tute:i t em bed s i ts cal l to the error block in a RE TU RN statement .Shou ld the error block ever return to VA L() (w hich is opt ional ,as demonstrated in DefError()) , the value returned by the blockbecom es the va lue re turned by E VALQ .




Error Ob jec ts

Similarly, there are conventions for holding a retry dialog (viaErron canR etry) or for plow ing ah ead in spi te of the errorcondit ion (via Erro rxa nD efau lt) . No te that even though thesetwo conv entions can be used together, nei ther of them can be

used in conjunction w ith the subst i tut ion con vention discussedpre viou sly. In othe r w ord s, if Error:ca nSu bstitute is true (.T.),both Error:canRetry and ErrorxanDefault must be false ( .F.) .

Retry is possible if the operation that fails is surrounded with aloop ing structu re to let i t go ba ck and repeat. This e xam pledem onstrates a basic retry s tructure:// Error handling protocol conventions/ /lFirstTry := .T.lRetry := .T.

DO WHILE lRetry

. <body of operation>

IF .NOT. AsItShouldBe // Your assertionIF lFirstTry

obj := ErrorNew()obj:canRetry := . T.obj:ca nDefaul t := .Τ.obj:canSubstitute := .F.obj:trie s := 0lFirstTry : = .F.

ENDIFobj:tries++// Raise the errorlRetry := EVAL( ERROR BLOCK (), obj)IF lRetry

LOOP // Causes retryELSE

. <default code> // Time for plan Β

ENDIFELSE

lRetry := .F. / / N o violation, no retryENDIF

. continuat ion code>ENDDO

9-26 CA-Clipper



Error Objects

If ErrorxanRetry is true (.T.), the error block can seek to retry theoriginal code. On the other han d, the error code may go throug ha few motions, perhaps altering the original error condition, then

return its request for another try.

When it tries the second time, the code encounters the errorcond ition once again. This time, instead of creating a new Erro robject, i t increments the tries instance variable of the existing oneand raises the error again. This can happ en any num ber oftimes . Th e error bloc k can test for a specified limit and retu rnfalse (.F.) in order to invoke plan B.

If default response is indicated, <default code> has severaloptions: it can drop out of the IF construct and execute thecontinuation code>; it can exit, short-circu iting the continuationcodo; or i t can disrupt continu ed f low with a QU IT, BR EA K, orRETURN. The possibi l i t ies are numerous and ent irely user-definable.

N o t e : The EG_ PR INT error code ( indicating that print ing hasfai led) only sets ErrorxanRetry.




A Baseline Strategy

A Baseline Strategy

A hallmark of CA -Clipper 's error mechan isms is versat il i ty. Themechanisms are general ized, so you can adapt them to emulatevarious approaches to error handling. Typical ly, CA-Clipperdoe s not pro vid e a particular appro ach. Instead , it prov idestools to imp lemen t an approach of your choosing. Therefore, forcode integri ty, you should adop t certain conventions. Here aresome suggest ions:

• To provid e mo re than 'say so and quit7 response to errors,replace DefError() by posting a generic error block thatBREAKs rather than quits .

Retain the initial, special case code for zero division and

network processing that appears in CA-Clipper 's DefError() .During programming, the s tandard DefError() may bedesirable, but a user in the middle of a completedapplication, is less appreciative of cryptic error messages ona DOS screen.

• Place subs tantive proc essing of application-sp ecific errorsyou raise in RE CO VE R clauses. Deal with them in theapplication, not in the error block.

• Instead of direct ly invoking RE CO VE R using BR EA K in your

assert ions, do so indirect ly through EVAL(ERRORBLOCK(),<object>). This will w ork only after following the firstguideline, which is to post a generic error block thatBREAKs .

Allow subsystems to install their own error blocks freely, whileassuring that such a subsystem :

• Preserves a copy of the predece ssor block upon entry.

• Res tores (reinstalls) that bloc k upo n exit.

• Pro vide s a call to the pred eces sor w hen don e, in case there isan error along the way (that is, to chain).

9-28 CA-Clipper



A Baseline Strategy

The block should customize low-level handling, notsubstant ively handle applicat ion-level exceptions. For example,i t ma y keep track of mo re information b efore using BR EA K, or i t

may intercept additional errors for 'say so and quit ' treatmentinstead of using BR EA K. For applicat ion-level processing, youshould use the REC OV ER clause local to the error, therebyheading back up the chain of error blocks to reach the top one,which BREAKs.

Prov ide OTHERWISE BREAK <objError> for those situation s in aREC OV ER clause you cannot handle through a CA SE opt ion .That way, you guarantee that an unrecognized error eventual lyreaches the outermost context .

Provide an outermost RECOVER that graceful ly QUITs. I t takesover the job of DefErrorQ, which has been replaced with a blo ckthat BR EA Ks. CA -Clipp er 's AL ER T() funct ion is designed foruser interface und er error condition s. It is sensitive to thepresence or absence of the CA -Clippe r full-screen 1/Ο system . Ifthe ful l-screen system is not present and norm al I /O iscom prom ised, AL ER T() prod uces a TTY -style display. Do notuse ALE RT() in other set tings, where i t ma y not p roduceexpected screen output .

Finally, keep the Erro r object nea r at ha nd throu gho ut. Allassertions should build Error objects in the first place, andsubsequ ent error code invocations shou ld pass it a long u singEVAL() or BREAK.

These conventions make the applicat ion 's error behavioruniform . W hen an error occurs, whether user-defined or thesystem's, just call the current error block and you are finished.




A Baseline Strategy

A Comprehensive Example

The fol lowing applicat ion is a bare-bones demonstrat ion of theerror hand ling principles described in this chapter. The ex amp leis not al l - inclusive but shows ho w co ntrol f lows amo ng the errorhand lers . The error handlers are , essent ial ly, em pty (forexample, the outermost RECOVER clause does not contain"gracefu l" QUIT code) .

VA L(99 ), in subsy stem 2, funct ions as a practice error.DefErro r() is supp lanted, in subsystem 1, by a replacement thatBR EA Ks. Each subsystem instal ls , then remo ves, i ts own errorhand ler. Up on instal lat ion, the predecessor block is alwayssaved. The se error hand lers chain. Fol low ing execution, each

calls i ts predecessor.

You can discover some useful behaviors by compil ing andexecuting variat ions of this exam ple. For examp le, you canmove VAL(99) among the subsystems and change the mix ofsubsystems that do and do not install their own error handlers inthe chain.

Notice that the block tr iggered by VAL(99) is a lways the mostrecently installed, not necessarily the one that appears in thesam e subsystem as the VA L() cal l. Instal ling a code blockglobalizes it , even though, as here, i t may call static functions.Similar ly, when the error block chain BREAKs, not ice whichRE CO V ER c lause is called. It is the one that belo ngs to theinnermost SEQ UE NC E sur rounding the BRE AK , not necessar ilythe one that app ears in the same su bsystem as the BR EA K.

9-30 CA-Clipper



A Baseline Strategy

W h e n the VAL (99) in subsys tem 2 leads to the BRE AK tha tappears in subsys tem 1, it is the REC OVE R c lause of subsys tem2, not of subsys tem 1, that takes over. Rem ove the B R E A K and

watch DefError() kick back in:// Error subsystem architecture

// First subsystem (.prg)FUNCTION Main()

STATIC bOldHandler// First HandlerbOldHandler : = ERRORBLOCK({|e| Hndlrl(e, ;

bOldHandler)})CLEAR SCREEN

BEGIN SEQUENCESecondEntryPoint()

RECOVER? "Recovery in Main"END SEQUENCEERRORBLOCK(bOldHandler)RETURN NIL

STATIC FUNCTION Subl()RETURN NIL

STATIC FUNCTION Sub2()RETURN NIL

STATIC FUNCTION Hndlrl(obj, handler)? "UDF called by First Handler"BREAKRETURN EVAL(handler, obj)

// Second Subsyste m (.prg)FUNCTION SecondEntryPoint()

STATIC bOldHandler// Second HandlerbOldHandler : = ERRORBLOCK({|e| Hndlr2(e, ;

bOldHandler)})

BEGIN SEQUENCEThirdEntryPoint()? VAL(99)

RECOVER? "Recovery in SecondEntryPoint"

END SEQUENCEERRORBLOCK(bOldHandler)RETURN NIL


STATIC FUNCTION Hndlr2(obj, handler)? "UDF called by Second Handler "RETURN EVAL(handler, obj)

Programming a n d Utilities G u id e 9 31



A Baseline Strategy

// Third Subsystem (.prg)FUNCTION ThirdEntryPoint()

STATIC bOldHandler// Third HandlerbOldHandler := ERRORBLOCK({|e| Hndlr3(e, ;

bOldHandler)})BEGIN SEQUENCE

RECOVER? "Recovery in ThirdEntryPoint"

END SEQUENCE

ERRORBLOCK(bOldHandler)RETURN NIL

STATIC FUNCTION Subl()RETURN NIL


STATIC FUNCTION Hndlr3(obj, handler)? "UDF called by Third Handler"RETURN EVAL(handler, obj)

What Belongs in RECOVER?

Final ly, consider applicat ion errors and respo nses to them.These are the condit ions yo u put in your assertion IFs and you rR E C O V E R C A S E s .

• Determ ining w hat is an error, and an ap propriate respo nse, issubject ive. The error condit ion should be judg ed genuinelyexceptional , and the response should not be overly complex.Ensu re that the responses ant icipate specif ic problem s and aredel iberately calculated to address those problem s. On e responsemay propagate the error, other responses may unwind a ser ies ofdiscrete events that cou ld not be collectively comp leted . If you rRECOVER code cal ls dedicated funct ions, consider making themstatic since they have no outside applicability.

9-32 CA-Clipper



A Baseline Strategy

There is a high degree of subjectivity in error processing.Suppose you have a loop to obtain and process numbers from asource (perhaps i t takes an average) . Some may be i l l - formed

(contain character values outside the legal range accord ing totheir representat ional form at) . Is that an error? I t dep ends w hyyou need the nu m bers and the derived resul t . Som e resul ts aregood on ly if a l l prescribed inp uts are goo d. Others can tolerate apercentage of throw-away inputs .

A ban k, calculat ing n ext year 's interest rate on a cus tom er 'svariable mo rtgage m ust factor in al l 52 week s of thecontractual ly specif ied government index values. Omission orinaccurac y of a s ingle value inval idates the wh ole resul t. O n the

other hand , tabulat ion of survey respon ses m ay require a resul taccurate within a certain margin of error. That ma y bestat is t ically obtainab le even if 10% of gathered resp onses areomit ted.

The fol lowing pseudocode character izes such typicalsubjectivity:

FUNCTION GatherValues()

BEGIN SEQUENCEDO WHILE

<obtain next value>IF <ill-formed>

BREAK indication-of-errorENDIF<process value>

ENDDORETURN result

RECOVER USING indication-of-errorCASE this-particular-error

<clear up>QUIT

END SEQUENCE

Beyon d rais ing the error, even if that is necessary , QUIT m ay beoverki l l . That requires a subject ive decision too. You r sourcemig ht be an interact ive user or a m ainfra me tape. I f a user ty pes" T " instead of "6," i t is worth request ing the number again, but i fa tape has an unread able scratch and 100 retr ies have alreadyfailed, another request is futile. The correct response iscontext-dependent .




A Baseline Strategy

W hatever yo ur respon se, keep i t in bou nds. Do not let errorcode prol iferate into a paral lel appl icat ion. Rem em ber,localiza tion is the key. Als o, do not use the error system toprocess conditions that are not errors (that is, conditions that arenot gen uin ely excep tional.) By definition , errors areabnormali t ies .

The fol low ing exa mp le i l lustrates the difference betw een trueerrors and other con dition s. It sho w s two opera tions , either ofwhich could be accomplished using the error system ortradition al con trol structu res. Th e first adv anc es a day -of-the-we ek array. I t experiences a system error whenev er the currentday is Saturd ay. The second divides two numb ers. I texperiences an error whenever the divisor is zero.

Either function could raise the error, address it reactivelythrough RECOVER, or avoid the error by ant icipat ing thebo un da ry. W hile recov ery is preferre d for division by zero, i t isdiscou raged for day of the wee k. Th e former is a mathem aticalaberra tion; trying it is a m istake . Th e latter is a no rm al bo un da rycondit ion:

// Abnormalities only, pleaseSTATIC TheDays := {"Sunday", "Monday", "Tuesday", ;

"Wednesday", "Thursday", "Friday", "Saturday"}STATIC i := 0

FUNCTION Ne xtD ayOLOCAL retvalBEGIN SEQUENCE

retval := TheDays[++i]RECOVER USING --

retva l := TheD ays[ i := 1]ENDRETURN retval

Since, however, this is not really an error condition, i t ispreferable to code the NextDayO funct ion as fol lows:

FUNCTION NextDay()LOCAL retvalIF i = 7

retval := TheDays[++i]ELSE

retval := TheD ays[ i := 1]ENDIFRETURN retval

9-34 CA-Clipper



A Baseline Strategy

N ow , the Divide() funct ion is shown bo th wa ys, but in this casethe f i rs t , which uses a SEQUENCE construct to handle the error,is preferable:

FUNCTION Divide(x, divisor)LOCAL retvalBEGIN SEQUENCE

retval := x/divisorRECOVER USING --

retva l := 0ENDRETURN retval

// Alternative, if division by zero was not// considered an errorFUNCTION Divide (x, divisor)

LOCAL retval

IF divisor = 0retval := x/divisorELSE

retval := 0ENDIFRETURN retval

The responses in RECOVER represent conscious ant icipat ion of aspecific set of error possibilit ies, as discussed above andil lustrated in the fi rs t exam ple. The y are not haphaz ard orcatch-all .

Prop agat ion is a comm on option for errors that fal l into theOT H ER W ISE category. I t is a lso a possibi l i ty for those that donot , once desired processing is complete .

Error response can un w ind; this is the basis for t ransact ionprocessing.

The fol lowing exam ple out l ines unw inding . I t a lso show s thetechnique for re -execut ing the SEQU EN CE s ta tement b lock anddemonstrates the SEQUENCE construct as the enclosure for

coherent , logical uni ts of act ivi ty, not random statement groups.The act ivi ty is foreseen to have certain, predictable outc om esthat cal l for remedy, and the RECOVER clause addresses those.




A Baseline Strategy

This exam ple at tem pts to perfo rm an ent ire group of updates ona databa se. If a pro blem arises, say with the fourth upd ate, theRECOVER code undoes the successful updates and star ts over:

// Unwind ing and restarting/ /#command RESTART SEQUENCE => LOOP

DO WHILE .T.BEGIN SEQUENCE

. <do 3 out of 5 things>

IF <can't do 4th>BREAK--

ENDIF

. <do 5th>

RECOVER USING--

. <undo those 3 things>

IF HaveAnotherGo// Restarts SEQUENCE block as a wholeRESTART SEQUENCE

ENDIF

END SEQUENCEEXIT

ENDDO

Assuming that the instal led error block eventual ly BREAKs, asdiscussed previously, your f ive updates are guaranteed i f youdrop out the SE QU EN CE c onstruct . This is because an errorinternal to any of the update operat ions (for example, REPLACE)tr iggers the error block, which wil l BREAK to the RECOVERcode becau se al l upd ate operat ions are bracketed in theSE QU EN CE construct . Thu s, the explici t BR EA K for the fourthupd ate sho wn in the exam ple is not the only wa y to invoke therecovery m echan ism. In the event of a BR EA K from the errorblock , you wou ld back al l successful upd ates out of the database(the error block helps you identify them) and try again.

9-36 CA-Clipper



Network Processing

Network Processing

The CA-Clipper funct ion NETERR() funct ions different ly fromearl ier versions of CA -Clipp er. Tw o events that in versionSummer '87 automatical ly set NETERR() to t rue ( .T.) , no longerdo so. They are fai lure of a US E com m and due to an "a ccessdenied" from the underlying DOS fi le open cal l and fai lure ofAPPEND BLANK due to the "phantom" record be ing locked byanother works ta t ion , perhaps by s imul taneous APPEND BLANKattemp ts . (The phantom record is just beyo nd the last record.)

Whi le USE and APPEND BLANK do prese t NETERR() to fa l se(.F.), upon failure they merely call the current error blockwithou t fur ther at tent ion to NE TER RQ . Set t ing NET ERRQ totrue ( X ) is left to the error block — the com m and s themselve s nolonger contain code to do so. The default error block, DefErrorQ,takes care of this, so you do not see a difference in the waynetwork code operates from one version to another:

// For network open error, set NETERR()// and subsystem defaultIF (e:genCode = = EG_0PEN .AND. e:osCode = = 32 .AND.

e:canDefault)NETERR(.Τ.)

RETURN .F.ENDIF

// For lock error during APPEND BLANK, set NETERR()// and subsystem defaultIF (e:genCode = = EG_APPENDL0CK .AND. e:canDefault)

NETERR(.Τ.)RETURN .F.

ENDIF

N o t e : Former ly, you could not se t NE TER R() , bu t in CA -Cl ipperyou do it by passing a true (.T.) or false (.F.) argument to thefunction.

If you su pplant D efError() , you should inclu de s imilar code in i tsreplacement; otherwise, network act ivi ty that hinges onNETERR Q w i ll change behavior.




Network Processing

Also note tha t because USE and APPE ND BLA NK haveindicated their readiness to regain control with e:canDefault true(.T.), Deffirror() returns false (.F.) in order to allow the originalope ration s to attem pt default pro cessing . In both cases, theoriginal operation does nothing visible (that i t , the file is notop ene d and the record is not add ed) . It prob ably do es lit tle butreturn, but that allows mainline code to retain control andcon tinue . De fErro r() 's returning false (.F.) me rely allows theoperation, and by extension, the ensuing code, to run tocomplet ion.

On another network issue, CA-Clipper now dist inguishesbetween the two causes (rooted in the DOS function that opensfiles) of "acces s den ied " that can occu r w hen ope ning a file. On e

failure is the result of other workstations' use of the file; theother , of attributes of the file itself. The D OS file open fu nctionreturns the same error code in both cases, namely 5, obscuringany dist inct ion between causes; howev er, a secondary error codeis avai lable from D OS w hich does m ake the dis t inct ion.CA-Clipper obtains this secondary code and returns it inErr on osC od e. In a clash w ith other wo rkstatio ns, the result iscode number 32, ent i t led "sharing violat ion," as opposed tonum ber 5, "acces s denie d." In a netw ork, 32 indicatesinter-workstation contention while 5 reflects rights and attributesissues.

Equipped with tools and understanding, you can now enhanceyou r app lications w ith error proce ssing. Yo u will not seek tom ake them error-proof, but to ma ke them error-systematic . Youcan raise abno rmal co ndit ions as errors , as supplied C A-Clipp erfunct ions do. You can provide local ized, special ized handling inrespo nse. The app roac h is user-d efinab le and the tools belon g toyou.

9-38 CA-Clipper



Network Processing

Transact .prg The exam ple below i l lustrates the use of CA -Clipp er errorfeatures in a netw ork environ men t , including theimplementat ion of the t ransact ion/rol lback concept and therestar t / retry of a block of s tatem ents .

The i l lustrated t ransact ion suppo ses a one-to-m any relat ionshipbetw een two data f i les . The t ransact ion consis ts of applyingdeletes to all of the child records that correspond to a givenpare nt record. (In this case , all the invo ices associated withcus tom er Jone s.) If the deletion of any child record fails, rollbac kis the reversal (that is, RECALL) of those deletions thatsucceeded.

The installed error block em bod ies the recom men dation thaterror block code eventually lead to a BREAK, so that local codecan be accompanied by recovery specific to local activity.Because of this, all errors reliably transfer control to thatrecovery. (The error block show n here accom plishes thisartificially. M oreo ver, i t is the highe st-level bloc k in a possib lechain that would perform the BREAK upon which this codewould rely.)

Note that there is separate recovery for the startup code and forthe mu ltiple-d elete cod e. If an error arises in either co ntext,execution of the local ized REC OV ER code is due to the sam eerror block, wh ich eventual ly BRE AK s. On ce posted, the errorblock does not "belong" to the routine that posted it but to allroutines that execute it while it remains installed:

// Transact.prg/ /// Compile with /N/W/A// Must be linked with Locks.obj to run

#include "Error.ch"

PROCEDURE Main()

LOCAL aDels, cName, aNots, objErr, cMsgFIELD LastName

// Artificial but prototypicalERRORBLOCK({|e| BREAK(e)})

// Open files, set relationIF .NOT. GetReadyO

? "No, I don't feel like it."QUIT

ENDIF




Network Processing

IF .NOT. Invoice->(DBSE EK(cName := "Jones"))? 'This example is hard-wired for "Joneses."'QUIT

ENDIF

// Parent record lock, gateway to its childrenIF Customer->(RecLock(5))

// Allow for possible retryDO WHILE .T.

BEGIN SEQUENCE// Transaction--multiple deletesaDels := {}DO WHILE TRIM(Invoice->(LastName)) == ;

"Jones"// If unsuccessful, calls// error blockInvoice->(RLOCK())Invoice->(DBDELETE())// Records deletions already doneAADD(aDels, Invoice->(RECNO()))Invoice->(DBSKIP())

ENDDO

RECOVER USING objErr

IF (objErrigenCode = EG_UNLOCKED)// Roll back —rec all deletionsDO WHILE .NOT. EMPTY(aDels)

aNots := {}AEVAL(aDels, {|nRec| ;

UnDeletelt(nRec, aNots)})aDels := ACLONE(aNots)

ENDDO

cMsg := "Rollback succ essful. " + ;"Restart transaction?"IF ErrBox(cMsg, {"Yes", "No"}) = 1

// Reposition pointerInvoice->(DBSEEK( cName := ;

"Jones"))// ...and start overLOOP

ENDIFENDIF

END SEQUENCEEXIT

ENDDO

Cu st om er s (DBUNLOCK ( ) )ENDIF

RETURN

9-40 CA-Clipper



Network Processing

STATIC PROCEDURE UnDeletelt(nRec, aNots)// either...

// recall works

// or.. .// mark for revisit

Invoice->(DBGOTO(nRec))IF Invoice->(RLOCK())

Invoice->(DBRECALL())

Invoice->(DBUNLOCK())ELSEAADD(aNo t s, nRec)

ENDIFRETURN

STATIC FUNCTION G etR ead yO/*Illustrates use of error system to treat networkfile "acquisition" as a transaction. Dispense swith Summer '87 NETERR( ) check after USE attemptas a result. Streamlines code and makes it morereadable.Need to accomplish 3-steps-in-1, or nothing:open 2 files and indexes, and set a relation.That defines the transaction. Relies onknowledge that error block will predictablyBREAK. Theref ore, if any part of the mainsequence of statements fails the RECOVERstatement block that gets control can undo theparts that did not. RETURN value reflectsoverall result.

* /

LOCAL 1Return := .T.CLEAR SCREENBEGIN SEQUENCE

USE Invoice INDEX Invoice SHARED NEWUSE Customer INDEX Customer SHARED NEWSET RELATION TO Customer->LastName ;

INTO Invoice

// for ANY error; don't grab object,// don't check whyRECOVER

CLOSE SELECT("Invoice")CLOSE SELECT("Customer")lReturn := .F.

END SEQUENCERETURN lReturn




Network Processing

FUNCTION ErrBox(cErrMsg, aOptions)LOCAL nChoice, i, nStrgLen,LOCAL cOldColor, cOldScreen

cOldColor := SETCOLOR("W/R+, W+/B")cOldScreen := SAVESCR EEN(10, 0, 14, 79)

@ 10, 0 TO 14 , 79 DOUBLE@ 11, 1, 13, 78 BOX SPACE(9)@ 11, 2 SAY cErrMsg

nStrgLen := LEN(aOptio ns) * 3AEVAL(aOptions, {|arr| nStrgLen += LEN(arr)})nStrgLen := (78 - nStrgLen) / 2

FOR i := 1 TO LEN(aOptions)@ 13 , nStrgLe n PROMPT aOptions[i]nStrgLe n += LEN(aOptions[i]) + 3

NEXT

nChoice := 1MENU TO nChoiceSETCOLOR(cOldColor)

RESTSCREEN(10, 0, 14, 79, cOldScreen)

RETURN nChoice

// EOF - Transact.prg //

9-42 CA-Clipper



Chapter 10CA-Clipper Compiler—CLIPPER.EXE


This chapter describes the basic operat ions of CLIPPER.EXE, theful l-featured and versat i le CA -Clipp er comp iler. I t can be u sedto compile a s ingle prog ram fi le (.prg) or to compile several filesat onc e by taking its inpu t from a script file. The result is anobject file (.OBJ) that can be linked with otherCA -Clipp er-com piled and foreign object f i les to form anexecutable file (.EXE).

CA-Clipper has been upgraded to Microsoft C 8.0. This upgradeswitches from al ternate to emu lator f loat ing point supp ort ,

enabling CA-C lipper to use a ma th coprocessor i f present . W iththis ne w release, you still get all the functiona lity of release 5.2features ( that is , command l ine compil ing and l inking, DBU, andso on), so you can mix and match the tool set as your needsrequire.

The following topics are discussed in this chapter:

• Invoking the CA -Clipp er com piler

• Us ing CLIPPE RCM D

• Com piler opt ions• The com piler script file

• The com piler return code

Program ming an d Utilities G uid e 10-1



Invoking the CA -Cl ipper Com pi ler

• H ow the CA -Clippe r preprocessor wo rks

• Ho w CA-Cl ipper compi les

• The com pile and link batch file

• H ead er files

• Ou tpu t files

• Cha nging the s ize of the environm ent

N o t e : The compiler requires a min im um 25 f i le handles. Thisrequires DOS 3.3 or greater and FILES=25 in CONFIG.SYS.

Invoking the CA-Clipper Compiler

To execute the CA-Clipper compiler from DOS, use thefol lowing syntax:

CLIPPER [<sourceFile> \ Q<scriptFile>[<option list>]]

<sourceFile> is the na m e of the pro gra m file to com pile to anobject file. If no extensio n is specifie d, (.prg) is assum ed. Thefi lename can op t ional ly include a dr ive designator and a pathreference.

<scriptFile> is the na m e of a script file conta ining a list of sourcefiles to comp ile into a single object file. If an extension is notspecif ied, (.clp) is assumed.

<option list> is a list of one or m ore op tions to control the courseof the com pilatio n. All availab le optio ns are discussed und erCo mp iler O ption s later in this chap ter. To get a list of options,specify the compiler command l ine with no arguments .

The fol lowing compiler command l ine checks the syntax ofMain.prg only, without displaying l ine numbers:

CLIPPER Main /S /Q /M

10-2 CA-Cl ipper



Using CLIPPERCMD

The fol lowing com piler com ma nd l ine com piles al l f i les in theAccou nt .clp scr ipt f ile . The opt ions in this case cause d ebu gginginformation to be included in the object file, which will be placedin the C: \CLIP53\OBJ directory and given the nameACCTPAY.OBJ :

CLIPPER ©Account /B /OC: \CLIP53 \OBJ\ACCTPAY

The script f i le , Acco unt .clp, is show n b elow :

AccMainAccPayAccRecAccRep

Using CUPPERCMD

In addit ion to specifying opt ions on the compiler command l ine,you can spec ify them us ing the CL IPP ER CM D envi ronmentvar iab le . To def ine CLIPPERCMD, use the DOS SET commandas fol low s:

SET OTiTPPERCMD= [<option l ist>]

<option list> is a list of one or m ore o ption s that will be read an dprocessed each t ime the com piler is invoke d. You specify theseoptions just as you would on the compiler command l ine.

To save yourself f rom having to enter this SET commandrepeatedly, you can place i t in your AUTOEXEC.BAT fi le wherei t wil l be processed autom atical ly each t im e you reset yourcomputer.

The fol lowing example causes CA-Clipper to suppress l inenumbers and use a new standard header f i le each t ime the

compiler is invoked:SET CLIPPERCMD=/L /UNewstd.ch

The next exam ple specif ies a directory in which to place ou tputobject files:

SET CLIPPERCMD=/OC:\CLIP53\OBJ\

Program min g an d Utilities G uid e 10 -3

http://c/CLIP53/OBJ

http://clip53/

http://obj/ACCTPAY

http://clip53/OBJ/

http://clip53/OBJ/

http://obj/ACCTPAY

http://clip53/

http://c/CLIP53/OBJ



Compiler Opt ions

Compi le r Opt ions

Com piler opt ions are switches that control compilat ion behavior.Besides the preprocessor directives and the standard header file,com piler opt ions are the main m echanism for control l ing thecompiler and preprocessor.

As already d iscussed, you can specify opt ions on the C A-Clipp ercom man d l ine and in the CLIPPE RC M D envi ronment var iab le.Command line options take precedence if there is a conflict.

All opt ions are show n in upp ercase preceded by a slash ( / ) .No te , however, that options are not case-sensitive and that youcan replace the slash with a dash (-) if you prefer.

Som e compiler opt ions have argum ents . I f an opt ion hasargu men ts , specify them after the opt ion, with no space betweenthe option and its first argument.

/A An y variable included in a PR IVA TE , PU BLIC , orPARAMETERS statement is automatical ly declared asM E M VA R .

/B Inclu des line nu m ber s, local and static variable nam es, source

filenames, and other debugging information in the object file. If/L is also specified, l ine numbers are not included as part of thedebugging information.

Using the /B option causes the size of the resulting object file toincrea se. Th e amo un t of the size increase depe nds on thenumber of lines in the source code file as well as the number oflocal and stat ic sym bols defined. The num ber of addit ional bytesis approximately (4 + 3 per line + size of each static and localsym bol + s ize of source f i lename symb ol) . Note that eachsymbol size includes a null terminator byte (for example, thesym bol Cu st_N am e requires 10 bytes) and that the 3 bytes perline figured into this size increase is eliminated by the use of the/L opt ion.

10-4 CA-Clipper



Compiler Options

/D /D<identifier>[=<text>]

Defin es an identifier to the prep roce ssor. If <text> is no tspecif ied, <identificr> is given an em pty value. No te that ifdouble quote marks are used in the <text> as li teral cha racte rs,they must be preceded by the backslash (\) character.

This option is designed for use with the conditional compilationdirectives to allow you to define a manifest constant and controlwh ethe r a section of the source file is com pile d. Refer to the#ifdef and #ifndef directives in the Reference Guide for moreinformation on condit ional compilat ion.

/ES /ES[<severityLevel>]

Specifies the severity level of warnings.

If <severityLevel> is 0 or om itted, the com piler does not set theDO S ER RO RL EV EL upon exit i f wa rnings are encou ntered. Thisis the default behavior of the compiler.

If <severityLevel> is 1, the com piler sets the DO S ER RO RL EV ELupon exit if warnings are encountered but stil l generates an .OBJfile.

If <severityLevel> is 2, the compi le r se ts the DOS ERR OR LEV ELupo n exi t i f wa rnings are encou ntered and does not generate an.OBJ file. This effectively promotes warnings to error status.

/I /l<pathName>

Adds the directory specif ied by <pathName> to the front of thelist of directories to be searched for header files (as specified bythe IN CL UD E environm ent variable) . M ult iple / I opt ions can bespecified in the same compiler session; each one causes anadditional path to be added to the front of the header filedirectory search list .

Program ming an d Utilities G uid e 10 -5



Excludes program source code line numbers from the object file.Th e effect of this option is to reduce the ob ject file size by threebytes for each line containing a program statement.

It should be used only on completed programs since its useprevents the report ing of source code l ine num bers w hen thereare runt im e errors . Add it ional ly, a progra m com piled using the/L opt ion cannot be debugged.

If both /L and /B are specified, l ine numbers are not included inthe debug information written to the object file.

Compiles only the current (.prg) fi le, suppressing the automaticsearch for (.prg) fi les to satisfy unreso lved externa l references. If

this option is specified, procedures referenced with a DOsta tement , SET FORMAT, or SET PROCEDURE commands andnot found in the current (.prg) are assumed external .

In addit ion, procedure f i les specif ied by SET PROCEDUREcom m and s are not compiled. Hea der f iles specif ied with the#includ e direct ive, how ever, are alwa ys com piled, regardless ofthe /M option.

/M has no effect when compiling with a script file.

Supp resses the autom atic defini t ion of a procedure with thesame name as the (.prg) file. This option m ust be used if youhave f i lewide variable declarat ions in a program (.prg) file.

If the /N option is not specified, each (.prg) fi le is compiled withan implicit procedure consisting of all code from the top of theprogram fi le to the f i rs t PROCEDURE or FUNCTION declarat ionstatement .

The first procedure to execute when you invoke an .EXE file, also

referred to as the starting procedure, is the first pro cedu re orfunct ion encountered at l ink t ime. When you compile withoutthe /N option, the implicit procedure serves as the startupproced ure. W hen you com pile with the /N option, the f irs texplicitly declared procedure or function in the first object filelisted at l ink time becomes the startup procedure.



Compiler Opt ions

/Ο /0<objFile>

Writes the output object file to <objFHe>. if <objFUc> containsonly a path sp ecification, it m ust end w ith a back slash (\)cha racter. Th e file is written to the specified directory w ith abase name the same as the source or script filename specified onthe com piler comm and l ine, but with an .OB] extension.

P Prod uce s a pre pro cesse d outp ut listing. Th e listing is written toa file with the same name as the source or script filenamespecif ied on the compiler command l ine, but with a (.ppo)exten sion. Th e location and na m e of this file is unaffected by th e/Ο option.

/Q Prevents l ine num bers from displaying on the screen wh en thecom pilation is in pro gres s. No te that line nu m ber s are stillwritten to the object file unless /L is also specified.

/R /R[</«?F//<?>]

Embeds in the object file a request to the linker to search <HbFiIe>for unresolved external references. Multiple /R options for thesame compiler session are addit ive, causing the name of eachlibrary referenced to be embedded.

By default , CA-Clipper embeds a request for CLIPPER.LIB,EXTEND.LIB, DBFNTX.LIB, and TERMINAL.LIB in the objec tfile. Specifying /R without a <libFile> caus es no libraries to beembedded, thereby overr iding this default request .

/S If spe cified, the synta x of the curre nt (.prg) file and all referencedsourc e code files is ch eck ed, bu t no object file is genera ted. Tochec k the synta x of the curre nt progra m file only , use the / Moption in conjunction with /S.

/T /T<pathName>

Specifies a directory for temporary files generated duringcom pilation . If this option is spe cified, it overr ides the direc toryset t ing specif ied in the TM P env ironm ent variable.

Pro gram min g a n d Utilit ies Gu ide 10-7



/U[<userStandardHeaderFile>]

Identifies an alternate standard header file to preprocess in placeof the supplied STD.C H wh ich is used automatical ly. If the / Uoption is specified without a <iiserStandardHeaderFile>, nostandard header is used.

The user-defined standard header file is a replacement forSTD.CH and, therefore, cannot contain anything other thanpreprocessor direct ives. CA-Clipper uses the same searchingorder for this header file as it does for all other header files: thecurrent directory, the / I directory, and the INCLUDE path.

Forces the compiler to assume that all references to undeclared

or una liased variable nam es are public or private variables. Thedefault is to treat ambiguous references as fields. The /V optionhas the same effect as using the dynamic variable alias( M E M VA R - > ) .

This option generates warning messages for undeclared oruna liased variable reference s. It is useful w hen conv ertingprivate and public variables to locals and statics.

This option suppresses shortcutting optimizations on the logicaloper ators .A ND . and .OR . It is pro vide d as an aid to isolatingcode that depends on the behavior of older versions ofCA -Clipper. Note that code executed using the runtime m acrooperator (&) is always optimized with shortcut t ing—optimizat ion can not be disabled in the macro system.



The Compiler Script File

The Compiler Script File

A script file (sometimes referred to as a clip list) is a text filecontaining a list of source files to compile into a single object file.The resulting object file has the same name as the script fileunless the /O option is specif ied.

The l is t can include program, procedure, and format f i les .Referenced f i les ( including procedure f i les) are not automatical lycom piled as they are if the applicat ion is compiled on theCA-Clipper command l ine. This is t rue regardless of whetherthe /M option is specif ied.

Use the following rules to create a script file:

• Sourc e f i les are separated by a carr iage return / l in efee d.

• So urc e files can be specifie d with or w itho ut an exten sion . Ifnot specif ied, a (.prg) extension is assumed.

• Drive designators and path references can also be specif iedas part of any source f i lenam e.

If a fatal error is encountered or the user presses Ctrl+C orCtr l+Break, the compiler terminates with a DOS return code of 1.If the compilation ends normally, the return code is set to 0.W hethe r or not w arning s set the return code is control led by the/ES compiler switch, as discussed in Compiler Options earl ier inthis chapter.

You can test the DO S return code in a batch f i le using the DO SER RO RLE VEL keyw ord . A good examp le of th is can be foundin the f i le CL.BAT located in your CA-Clipper BIN directory(this batch f i le is discussed m ore thorou ghly in The Com pile andLink Batch File later in this chapter.)

The Compiler Return Code

Progra mm ing an d Utilities G uid e 10 -9



How the CA-Clipper Preprocessor Works

If an error occurs, an error message is displayed and no outputfile is gen erate d. For a list of error messa ges an d their mean ing s,see the "Compiler Error Messages" chapter in the Error Messagesand Appendices Guide. To direct these messa ges to a file, use DO S

redirect ion. For exam ple, the fol lowing compiler com ma nd l inedirects the compiler output to a file called ERRFILE.TXT:

CLIPPER <sourceFile> > ERRFILE.TXT


The CA-Clipper compiler has two dist inct phases: thepreprocesso r phase and the com pilat ion phase. The port ion ofthe compiler eng ine that performs the preprocessor ph ase iscalled the preprocessor, and the portion that performs thecompilation phase is called the compiler.

Before the comp ilat ion p hase takes place, the preprocessor scansthe source file from top to bottom for certain directives andtranslates them into regular CA-Clippe r source code that can becom piled . The outp ut of the prep roce ssor is then used as inputto the compiler.

The /P compiler option can be used to wri te the preprocessoroutput to disk so that you can see the source code that was usedas inpu t to the comp ilation pha se. This option is especiallyuseful if you ha ve used the #com m and and #translate direct ivesto create user-defined c om ma nds . You can look at the contentsof the (.ppo) file to see whether or not commands translated asyou expected.

10-10 CA-Clipper




The fol lowing table sum marize s the preprocessor direct ives. Formo re information on their usage, see the Reference Guide.

Direct ive M e a n i n g

#co mm and Specify a user-defined com ma nd or t ranslat iondirective

#define Define a manifest constant or pseudofunction

#error Generate a compiler error and display amessage

#ifdef Compile a section of code if an identifier isdefined

#ifndef Compile a section of code if an identifier isundef ined

#include Include a file into the current source file

#stdout Write text to the standard output device

#undef Remove a #define defini t ion

#xcommand Specify a user-defined command or t ranslat iondirect ive without abbreviat ions




How CA-Clipper Compiles

How CA -Cl ippe r Co m pi le s

The CA-Clipper compiler converts source code wri t ten inCA-Clipper into Intel object code files. The source codeprograms are identified by the DOS filename extension (.prg).Object code files are identified by the DOS filename extension(.OBJ). Th ese object files can be linked with a linker to produ cean executable file, identified by the DOS filename extension(.EXE).

Unless a script file or the /M option is specified, CA-Clippercompiles the specified program file and all program filesreferenced wi th DO, SET PROCEDURE, and SET FORMAT.Within each referenced file, any other files referenced with these

com ma nd s and statem ents are also compiled unti l the ent iresyste m of sourc e files is pro cess ed. This proc eeds acco rding tothe following rules:

• The prog ram specif ied on the comp iler com ma nd l ine iscompiled first.

• Proced ure f i les , proced ures referenced with DO , and formatfiles referenced in the current program are compiled in theorder specified.

• Proced ure references ma de with DO and not alreadycompiled are compiled if found as (.prg) files in the currentdirectory. If not found, CA-Clipper returns a warningmessage .

• Form at references ma de with SET FO RM AT and not alreadyknown are assumed to have a (.fmt) extension unlessotherw ise specified. If a proced ure with the same nam e as aformat reference has already bee n com piled, the format w il lrefer to the compiled procedure and not to the (.fmt) file ondisk.

If a script file is used, each file is compiled in the order listedaccording to these rules with one exce ption— no referenced f i lesare compiled.

10-12 CA-Clipper



The Compile and Link Batch File

N o t e : A DO requires that the proc edu re be know n or avai lablein the current directory as a file of the same name with a (.prg)extension. If the proc edu re is cal led with funct ion-cal l ing synta x

and not known, CA-Clipper does not search the disk for aprogram fi le of the same name, but instead assumes theprocedure is external and proceeds without any warningmessage .


The defaul t instal lat ion of the CA-Clipper development system

places a sample compile and l ink batch f i le , CL.BAT in yourCA -Clip per BIN directory. This batch f ile can be used to com pileand l ink s ingle program fi les (.prg) to executable files (.EXE) onlyif there are no errors durin g com pilatio n. If there is a com pile rerror, CLIPPER.EXE terminates with a return code of 1, and thebatch f i le in turn termina tes with out at tem pting to l ink.

The com piler batch f i le is invok ed as fol low s:

CL <sourceFile>

<sourceFile> is the na m e of the prog ram fi le to com pile and l ink.The f i lename can be specif ied including both a dr ive designatoran d/ or a pa th re ference . Ho wev er, spec i fy ing <sonrceFile> wi than extension will cause a linker error.




Header Files

Header Files

Header files, also referred to as include files, contain preprocessordirect ives and com m and defini t ions. He ader f iles have nodefaul t extension and are specif ied using the #includeprepro cessor direct ive or the / U com piler opt ion. TheINCLUDE environment variable is used to locate header f i lesand is defined using the DOS SET command as fol lows:

SET INCLUDE=<pathSpec>

The INCLUDE path is searched if a requested header f i le cannotbe foun d in the current directory.

In the defaul t instal lat ion con figurat ion, IN CL UD E is set to\ C L I P 5 3 \ I N C L U D E . To chan ge this defau lt, alter the SETINC LU DE com ma nd in your AU TO EX EC.B AT f i le . To searchfor header files in a particular directory on the D: drive, youmig ht chang e i t to the fol low ing:

SET INCLUDE=D:\INCLUDE

N o t e : W hen search ing for head er fi les , CA -Clipp er searches thedirectory specif ied with the / I compiler opt ion af ter the currentdirectory and before the IN CL UD E path. In a sense, this opt ionadds the specif ied directory to the front of the INC LU D E pathspecification.

10-14 CA-Clipper

http://clip53/INCLUDE

http://clip53/INCLUDE



Output Files

Output Files

There are three types of output f i les produced by the CA-Clippercom piler : object f i les , prepro cessed outpu t f i les , and tem por aryfiles. Any sp ecif ied output f i lename can include a ful l or part ialpath name to explici t ly indicate where CA-Clipper wil l wri te thefile on disk. Un less other w ise specifie d, files are created in thecurrent directory.

Defau l t extensions for outpu t f i les , with the exception ofprepro cessor o utpu t f i les, can be overr idden with explici textensions specif ied as part of the f i lenam e.

Object Files

A single object file is created as a result of a successful compile.By default, the name assigned to the file is the same as the sourceor scr ipt f i lename specif ied on the compiler command l ine, butwith an .OBJ extension. Yo u can, how ever, specify the objectf i lename and dest inat ion with the /O compiler opt ion.

Temporary Files

Normally, CA-Clipper generates one or more temporary f i lesduring the compilat ion process. You can control where thesefi les are created by set t ing up an enviro nm ent variable cal ledTMP wi th the DOS SET command as fo l lows:

SET TMP=<pathName>

The compiler normally deletes temporary f i les af ter they haveserved their pu rpos e. Therefo re, you ma y never see them on

your disk. The ma in purp ose of the TM P variable is to wri te thetemp orary f i les to another d isk drive if you are running sho rt ofspace on the drive that you no rma lly use to compile . This w ay ,the temporary files will not take up disk space that is better usedby permanent f i les .




Changing the Size of the Environment

For example, i f you are working on the C: dr ive, you could puttemp orary f i les in a directory on ano ther disk drive as fol lows:

SET TMP=D:\TEMP

N o t e : The / T com piler opt ion can be used to specify atem po rary file directo ry. If this op tion is spec ified, i t overrid esthe TMP directory set t ing.

Preprocessed Output Listing

The /P compiler opt ion al lows you to wri te a preprocessedoutp ut listing to a file. Th e nam e assign ed to the file is the sam eas the progra m o r script f i lenam e specif ied on the comp ilercommand l ine wi th a (.ppo) extension.

Changing the Size of the Environment

When the envi ronment var iab les , CLIPPERCMD, INCLUDE, orTM P are spec if ied, it is possible to run out of environm ent space.In DO S version 3.2 and ab ove, you can cha nge the s ize of theenvi ronm ent by loadingC O M M A N D . C O Mwith the SHELLdirect ive in CO NF IG.SYS .

For example , the fo l lowing CO NF IG.SYS com man d l ine se ts theenvironment s ize to 2048 bytes:

SHELLAC:\COMMAND.COM C:\ /P /E:2048

Note that in addition to specifying the /E option to define theenvironment space, you must give the name and locat ion ofC O M M A N D . C O Mas well as forceC O M M A N D . C O Mto remainresident with the /P opt ion.

10-16 CA-Clipper

http://temp/

http://command.com/

http://command.com/

http://command.com/

http://command.com/

http://command.com/

http://command.com/

http://temp/



Chapter 11

CA-Clipper Protected ModeLin ker—EXOSPACE. EXE


Welcome to CA-Cl ipper /Exospace , the pro tec ted mode l inkerand DO S extender for CA -Clipp er. This chapter provides al l theinforma tion you need to l ink your applicat ions withCA -Cl ip per /E xosp ace and explains the benef i ts of do ing so . Thefol lowing topics are discussed:

• Ove rv i ew o f CA-C l ippe r /Exosp ace

• Invok ing CA-C l ippe r /Exosp ace

• The CA -Cl ip per /E xosp ace re turn code

• The com pile and l ink batch f i le• Ou tpu t files

• Ho w CA -Cl ip per /E xosp ace searches for f iles

• Linker com m and reference

• Troubleshooting




Overv iew o f CA-Cl ippe r /Exospace

O v e r v i e w o f C A - C l i p p e r / E x o s p a c e

CA-Cl ipper /Exospace a l lows your CA-Cl ipper appl ica t ions torun in protected mode, thereby el iminat ing the DOS 640 KBbarrier. In protected m od e, extende d mem ory is direct lyavai lable without requir ing sw app ing of any kind. This in itselfwo uld be exci t ing eno ugh , but i t a lso has a num ber of otherimportant implicat ions.

Load size concerns are a thing of the past.CA-Clipper/Exospace applicat ions can be loaded in as l i t t le as256 KB (or less) of low D OS m em ory. As long as enoughextended memory is avai lable, your applicat ion wil l run f ine.You wil l have no problems even if avai lable DOS memory is

being squ eezed by networ k drivers and the l ike. No w , you caneven l ink and run your CA-Clipper applicat ions while shel ledout from another CA-Clipper applicat ion or a memory-hungryeditor

Similarly, overlaying of code is no longer an issue. You do notneed to worry at all about which code to overlay or not tooverlay—just specify all your .OBJ and .LIB files, and linkOverlaying of code occurs automatical ly when your applicat ionis running—but i t is completely automatic and transparent , and

you never need to worry about i t .

Although overlaying occurs automatical ly i f necessary, i f youhave enough RAM, your .EXE wil l be loaded into memory—as i tis used— unti l the ent ire .EXE is resident in RA M . Previously,overlaid cod e had to be swa ppe d in and out of a relat ively sm alloverlay area as i t w as need ed, so a large applicat ion could neverbe com pletely resident in RA M . This had obvious perform anceimplicat ions.

CA-Cl ipper /Exospace rep laces CA-Cl ipper ' s rea l -modeDOS/Expanded Memory Spec i f ica t ion (EMS)-based Vir tua lMemory Manager with a robust , t ransparent , protected-modevir tual memory engine developed by Rational Systems, aleader in protected -mo de technolo gy. This same technology iscurrent ly used by Lotus, IBM, Quarterdeck, Borland, Symantec,Watcom, and hundreds of others , and has shipped mil l ions ofcopies of commercial applicat ions s ince 1987.

Say G ood -bye toLoad Size

No Over layingWorries

Industry StandardVir tual Memory

11-2 CA-Cl ipper



Overv iew of CA-Cl ipper /Exospace

ImprovedPerformance

Resurrect Your286 PCs

What Abo ut 386 an d486 Machines?

P r o te c t e d M o d e =P r o t e c t e d C o d e

Without al l the swapping that CA-Clipper was forced to dowithin the 640 KB DOS l imit , the performance of manyapplicat ions wil l improv e visibly and substant ial ly, de pend ing

on processor and memory configurat ions.

CA -Cl ipp er /Exo space brea thes new l ife in to 80286-basedmachines. With 2 MB or more of RAM, many 286 machineswill now run CA-Clipper applications faster than ever beforeand will be able to run applications that they may not havebeen able to run before becau se of restr icted DO S me mo ry.

App licat ions running on 386 and 486 machines also benefi t, ofcourse. Instead of continual ly having to swap data from E M S

or having to load overlaid code from disk, applications can nowuse al l of a ma chine 's mem ory direct ly. Sw appin g only occurswh en al l avai lable mem ory is exhau sted, instead of when thefirs t 640 KB is ful l. In effect, CA -Clip per /Ex osp ace raises the640 KB R A M ceiling to includ e all available mem ory . This willbenefi t a lmost any applicat ion on any supported machine.

Protected mode, as its name implies, provides a greater level ofprotect ion to your applicat ions. C or Assem bler code that hasnot yet been fully debugged, whether it is in a third-partylibrary or your own, will usually generate an exception error,detected direct ly by the CPU , as soon as it does so meth ingwrong, rather than corrupting memory and leading tomy sterious and difficul t-to-trace problem s later on. This m ake sit easier to find the source of the problem, and if a third-partylibrary is the source of a problem, it will usually be clear whichlibrary is at fault.




Invoking CA-Clipper/Exospace

I n v o k i n g C A - C l i p p e r / E x o s p a c e

To execute CA -Cl ip per /E xosp ace f rom DOS , use the fo llowingsyntax:

EXOSPACE [@<lnkFile>] [<command list>]

I f you spec i fy no argum ents , CA -Cl ip per /E xosp ace d isp lays abrief help screen.

Script Files <lnkFile> is the na m e of an AS CII text file called a script file f romw hic h the linker takes som e or all of its inpu t. If you sp ecify thefi le without an extension, .LNK is assumed.

You can opt ional ly specify a dr ive designator and/or a pathreference for the scr ipt f i le . See How CA-Clipper/ExospaceSearches for Files later in this chapter for information on how aninput file is located if i ts filename is unqualified.

You can use script files to automate linker sessions that you tendto repeat and sessions that are too long to enter from thecommand l ine—the DOS command l ine l imit of 128 charactersmay be too restrictive for some linker sessions, necessitating theuse of a script file.

The only rule governing the format of a script file is that i tcontain val id l inker com ma nd s. You need not place thecom m and s one to a l ine. The ne w l ine character, l ike a space or atab, is conside red to be white space. Therefo re, i f a com m andwill not fit on one line, continue it on a new line by pressingEnter—no continuat ion character is necessary.

The # character designates a com m ent. W hen encou ntered, therest of the line is ignored.

You can nest script files using the @<lnkFile> syntax w ithin ascript file. The named script file is read and executed byCA-Clipper/Exospace in i ts ent i rety. When i t terminates , controlreturns to the current script file.

11-4 CA-Clipper



Invoking CA-Clipper /Exospace

N o t e : CA-Clipper/Exospace supports scr ipt f i les for both.RTL ink and Blinker. Sim ply use your existing script files asinput to CA-Clipper/Exospace without modif icat ion (see theLinker Command Reference later in this chapter for moreinform ation ). If, on the other han d, yo u use anoth er linker, yo uwi l l need to modify it to use CA -Cl ippe r /Exos pace com man ds .

Linker Co m ma nd s command list> is a list of linker commands separated by spaces.Linker commands on the command l ine ei ther overr ide oraugm ent the sam e com ma nd s in a script fi le . For examp le, aFILE command on the command l ine adds to any FILEcommands in the script f i le , while an OUTPUT commandoverrides any OUTPUT commands in the script f i le . See the

Linker Co m ma nd Referenc e later in this chapter for detai ls onthe syntax and behavior of specif ic commands.

To invoke the linker, you must specify at least one FILEcommand to tel l CA-Clipper/Exospace which object f i les youwant to link. You can specify this command either on theco m m an d line or in a script file. If you attem pt to invokeCA-Cl ipper /Exospace wi th command l ine arguments and do notspecify a FILE command, the linker session will result in anerror.

This exam ple links a single object file, HE LL O .OB J. The result isthe executable H ELL O.EX E:

EXOSPACE FILE HELLO

The next examp le l inks the DBU uti li ty, assum ing you arelocated in the \C LIP53 \SO UR CE \ DB U directory. The resul t isDBU.EXE:

EXOSPACE @DBU

A simplified version of the DBU.LNK file is listed below:FILE DBU, DBUUTIL, DBUHELP, DBUVIEW, DBUINDX,

DBUEDIT, DBUCOPY, DBUSTRU, DBUNET




Invoking CA-Clipper /Exospace

W hile CA- Cl ip per /E xosp ace l inks your appl ica t ion for you , it sprim ary funct ion is not that of a l inker. The mo st imp ortanttasks CA -Cl ip per /E xosp ace per forms are inv is ib le and occur

before and after l inking:

• CA -Clipp er-com piled applicat ions are enabled to executewith out violat ing any of the restrict ions imposed byprotec ted mode .

• CA -Clip per 's real-m ode VM system is replaced with aprotected-mode version.

• An y other operat ions necessary to al low CA -Clipp er to runin protected mode are performed.

Per fo rmance CA -Cl ip per /E xosp ace per forms bes t i f g iven suffic ien t mem oryConsiderations in wh ich to operate . Just before CA -Cl ipp er/E xo spa ce f inishes

l inking, the amount of memory used during the l ink isdisplayed (for example, 2314208 bytes used out of 3057472bytes avai lable) .

Best perform ance wil l be achieved if you hav e at least as mu chRA M ava i lable as the num ber of bytes used w hen l inking. If youhave less , swapping to disk wil l occur, which s lows down thel ink process. No te that the am oun t of m em ory required for

linking is proportional to the size of the application being linked.

W h a t EXOSPACE.EXEDoes

11-6 CA-Clipper



The CA-C lipper /Exos pace Return C o de

The CA -Cl ip pe r /Ex os pa ce Return Co d e

If CA-Clipper/Exospace encounters an error or is interrupted bythe user pressing Ctr l+C or Ctr l+Bre ak, i t terminates with areturn code (DOS ERRORLEVEL) of 1. I f the l inker session endsnormal ly or i f on ly warning a nd /o r unreso lved symbol e r rorswere encountered, the return code is set to 0.

Some examples of typical errors that are encountered during al inker session are the inabi l i ty of CA-Clipper/Exospace to locatea file or to interpr et a co m m an d beca use of incorrect syntax . Ifan error occurs , an error messag e is displayed and no ou tput f i lei s genera ted (unless you spec ify the EXO SPA CE EXE CU TA BL E

N OD EL ET E com m and ). For a l is t of error me ssages and theirmeanings , see the "CA-Cl ipper /Exospace Error Messages"chapter in the Error Messages and Appendices Guide.


The defaul t instal lat ion of the CA-Clipper development systemplaces a comp ile and l ink batch f i le , CL .BA T in the\CLIP53 \BIN directo ry. Yo u can use this batc h file to com pile and link a singleprogram (.prg) fi le to an executable file (.EXE) if there are noerrors during com pila tion . If there is a com piler erro r,CLIPPER.EXE terminates with a return code of 1, and the batchfile in turn terminates without attempting to link.

To invo ke the batch f i le , use the fol lowing syntax:

CL <sourceFile>

The <sourceFile> is the nam e of the pro gram fi le to com pile andlink, specified with ou t an exten sion. Yo u can specify thefi lename with a dr ive designator and/or a path reference.

Warning Specifying the <sourceFile> with an extension will cause linker error.


http://clip53/BIN

http://clip53/BIN



Output Files

Output Files

There are several types of files produced as output byCA -Cl ip per /E xosp ace . This sec tion describes each typeseparately.

Any output f i lename that you specify can opt ional ly include adrive designator and/or a path reference to explici t ly indicatew here CA -C lipp er/E xo spa ce places the f i le on disk. Unlessotherwise specified, files are created in the current directory.

Except in certain cases pointed out in the ensuing discussion,you can override default extensions for output files with explicitexten sions sp ecified as part of the filenam e. To indicate a filewith no extension, include a period at the end of the filename.

Executable Files (.EXE)

CA-Clipper/Exospace produces an executable f i le as i ts output .You can specify the name direct ly using the OUTPUT commandor have CA -Cl ip per /E xosp ace de termine it for you based on thefirst filename (either script or object) encountered on theCA -Cl ippe r /Exo space comm and l ine . CA-C l ippe r /Exospace

assigns a default extension of .EXE to executable files, which youcannot overr ide.

The .EXE extension is used to designate a file that can beexecuted direct ly by the operat ing sy stem shel l ,C O M M A N D . C O M .

The order in which .EXE files are searched for at runtime isdictated by DOS as fol lows:

• The current directory

• The path specif ied in the PA TH environmen t variable

If the file is not found, a runtime error is generated.

11-8 CA-Clipper

http://command.com/

http://command.com/



Output Files

Map Files (.MAP)

You can cause CA -Cl ip per /E xos pac e to genera te a map f ileusing the M AP co m m and . The defaul t extension for this f iletype is .MAP.

A map file is simply an ASCII text file containing informationabout symbol and segment addresses within the memory image.You specify the exact content and order of the file contents withMA P command op t ions .

Temporary Files

On occas ion , CA-Cl ipper /Exospace genera tes temporary f i lesduring the l inking process. You can control whe re these f i les arecreated by set t ing up an environment variable cal led TMP withthe DO S SET comm and as fo l lows:

SE T TWP=<pathName>

Plac ing th is command in your AUTOEXEC.BAT f i leautomatical ly defines the TMP variable so that temporary f i lesgenera ted by CA-Cl ipper /Exospace a re au tomat ica l ly p laced in

the desired locat ion. I f you do not specify the TM P enviro nm entvariable, temporary files are created in the current directory.

The linker deletes temporary files after they have served theirpurp ose. The refore, you may never see them on your disk.

You can use the TMP variable to wri te the temporary f i les toanother disk drive if you are running short of space on the drivethat you norm ally use to l ink. To speed up the linking p rocessyou can also set TMP to wri te temporary f i les on a RAM disk.This way, the temporary files will not take up disk space that isbet ter used by permanent f i les . For example:

SET TMP=D:\TEMP


http://temp/

http://temp/



How CA-Clipper/Exospace Searches for Files

How CA-Clipper /Exospace Searches for Fi les

There are several types of files that serve as input to

CA -C lip pe r/E xo spa ce. Each type of f i le is searched foraccording to a prescribed set of rules as follows:

• The current directory

• The path in a specif ic DO S environ men t variable

You can include a full or partial path name to explicitly indicatewh ere CA -C lip pe r/E xo spa ce shou ld search for a f i le . I f,however, you do not specify the location of a file, the prescribedrules are used to locate the file. If the file is not found after all ofthe poss ib le loca t ions have been searched , CA -Cl ipp er /Exosp aceterminates with an error message, the DOS return code is set to1, and no outp ut f i le is produ ced.

This sect ion describes how CA-Clipper/Exospace at tempts tolocate each possible input file type. The rules stated above applyto all file typ es, so they w ill not be repeate d. Instea d, the specificsearch environment variable is defined for each file type and anydeviations from the general rules are noted.

Library Files (.LIB)

Library files have a default extension of .LIB and you specifythem us ing the LIBR AR Y com ma nd. The envi ronment var iab leused to locate library files is called LIB, and you define it usingthe SET command as fol lows:

SET LIB=<pathSpec list>

In the default installation configuration, LIB is set to\CLIP53 \LIB . To cha nge this defau lt, alter the SET L IB

com ma nd in your AU TO EX EC.B AT f ile . For examp le , to inc ludea directory containin g third-party l ibrar ies , you m ight change i tto the following:

SET LIB=C: \CLIP53\ LIB;C: \CLIP53 \THIRDPARTY\LIB

11-10 CA-Clipper

http://clip53/LIB

http://clip53/

http://clip53/

http://thirdparty/LIB

http://thirdparty/LIB

http://clip53/

http://clip53/

http://clip53/LIB



How CA-Clipper/Exospace Searches for Files

Object Files (.OBJ)

Object files have a default extension of .OBJ and you specifythem using the FILE com m and . The environ me nt variable usedto locate library files is called OBJ, and you define it using theSET comm and as fo l lows:

SET OBJ=<pathSpec list>

In the default installation configuration, OBJ is set to\CLIP53\OBJ. To chan ge this defau lt, alter the SE T OBJcom man d in your AUTO EXE C.BA T f i le . For exam ple , i f yourobject files are located in a directory called OBJ, you mightchange it to the following:

SET 0BJ=C:\0BJ

Script Files ( IN K )

Script files have a default extension of .LNK and you specifythem on the CA-Cl ipper /Exospace command l ine or wi th inanother script file by preceding the filename with an @ symbol.There is no associated env ironm ent variable to specify wh ere tosearch for script files.


http://clip53/OBJ

http://clip53/OBJ



Linker C om m an d Refe rence

Linker C o m m a n d Refe rence

This section provides an alphabetical reference to all the

CA -Cl ip per /E xosp ace comm ands . You can spec ify comm andson the CA-Clipper/Exospace command l ine or in a scr ipt f i le .The co mm and s are not case-sensi t ive, and you can specify themin wh atever order you want . The only comm and that is requiredto link is the FILE command—all others are optional.

Yo u can abbreviate any linker co m m an d to just a few letters. Forexample, FILE becomes Fl and LIBRARY become LIB (or just LI) .Abbreviat ions are not documented for each command, but as ageneral rule you must use enough letters to distinguish onecommand from another and should include enough let ters sothat the option is readable.

Unless otherwise stated in this section, the following rules applywhen the same command is encountered more than once duringa link session:

• Any com man d encountered on the CA -Cl ipp er /Exosp acecom ma nd l ine overr ides l ike comm and s in a scr ipt f i le .

• I f CA -Cl ip per /E xosp ace encounters the same comm andwithin script files, the last occurrence of the command is

used.

For example, i f you specify STACK 8192 on theCA-Clipper/Exospace command l ine and l ink with a scr ipt f i lespecifying STACK 9672, the stack size for the application will be8192 bytes . On the other han d, i f you l ink with no S TA CKcommand on the command l ine and specify STACK 8192 at thebeginning of your scr ipt f i le and STACK 9672 somewhere nearthe end, the stack size for the application will be 9672 bytes.

11-12 CA-Clipper




Co m patibility w ith Other Linkers

CA-Cl ipper /Exospace i s geared for compat ib i l i ty wi th .RTLink,

the l inker included with previous versions of CA-Clipper, andBlinker so that you link using script files developed for theselinkers.

.RTLink Compatibil i ty

CA-Cl ipper /Exospace achieves compat ib i l i ty wi th .RTLink intwo dist inct ways.

F i rst , CA -Cl ip per /E xosp ace suppor ts a subse t of .RTLink

commands (us ing the FREEFORMAT syntax only) . In o therwords, the syntax and semantics for the commands that the twol inkers have in com mo n are exac t ly the same. These com ma ndsare docum ented ful ly in the alphabet ical reference later in thissec tion . For exam ple , com ma nds such as FILE, M AP , andSTACK are the same for both l inkers .

Second , CA -Cl ip per /E xosp ace ignores any .RTLink com ma ndthat is not listed in the alphabetical reference later in this section.For ex am ple, the BEG IN AR E Α.. . .EN D AR E A construct is used todef ine over lay a reas . S ince CA-Cl ipper /Exospace over lays code

automatical ly as needed, i t ignores these commands.

Thus, when you l ink a CA-Clipper-compiled applicat ion usingCA -Cl ip per /E xosp ace , yo u can spec i fy your o ld .RTLink scr ip tf ile on the CA -Cl ip per /E xosp ace com man d l ine to bui ld theapplicat ion. Commands that are compatible wil l operate asexpected, while commands that are incompatible wil l be ignored.Note that the l ink scr ipt should work properly to produce thedesired .EXE since the ignored commands are ei ther performedautomatical ly or do not apply when l inking withCA -Cl ipper / Exospace .

Important The .RTLink MO DU LE comman d is mostly used tocontrol m odule placem ent relative to overlay areas and for this reasit is ignored by CA-C lipper/Exospace. If, however , you are using thMO DU LE comm and to force linkage of a module which w ould nototherwise be linked, CA-Clipper/Exospace requires that you use theMO DU LE...FROM comm and instead, specifying the library in whithe module can be found.





Bl inker Compat ib i l i ty

CA -Cl ip per /E xosp ace achieves compat ib i li ty wi th Bl inker inthree dis t inct ways.

Firs t , CA-Clipper/Exospace supports a subset of Blinkercom ma nd s. In other wo rds, the syntax and seman tics for thecommands that the two l inkers have in common are exact ly thesame. These commands are documented ful ly in the alphabet icalreference later in this section.

Second, i f a part icular Blinker command has anCA -Cl ip per /E xosp ace equiva len t bu t is per formed us ing as l igh t ly d i ffe ren t syntax , CA-C l ippe r /Exo space per forms asimple t ranslat ion of the comm and to achieve the desired resul t .For example , these BLIN KER com man ds a re s imply rep laced bythe i r EXOSPACE equiva len t :

B L I N K E R E N V I R O N M E N T C L I P P E RB L I N K E R E N V I R O N M E N T O V E R R I D EB L I N K E R E X E C U TA B L E C L I P P E RB L I N K E R E X E C U TA B L E N O D E L E T EB L I N K E R P R O C E D U R E D E P T H

Then, the ALLOCATE and SEARCH commands a re in te rpre ted

as LIBRA RY co mm ands , which wo rks in most cases .

Important The behavior of the SEARC H command underCA-Clipper/Exospace can lead to differences in link sequence comparto the same com mand used with Blinker. If you are using theSEARC H comm and to prioritize a particular library in a Blinkerscript, you m ay need to rearrange the order in which the libraries arespecified or use the MO DU LE...FROM comm and to explicitly controlink sequence as necessary.

Thi rd , CA-Cl ipper /Exospace ignores any Bl inker command tha tis not listed in the alphabetical reference later in this section anddoes not have an equiv alent as previou sly mentioned . Forexam ple, the B EG IN AR E Α.. . .EN D AR E A construct is used todef ine over lay a reas . S ince CA -Cl ipp er /Exo space over lays codeautomatical ly as needed, i t ignores these commands.

11-14 CA-Clipper



Linker Co m m an d Refe rence

Thus, when you l ink a CA-Clipper-compiled applicat ion usingCA-Clipper/Exospace, you can specify your Blinker scr ipt f i le onthe CA -Cl ipp er /Exo space com man d l ine to bui ld the

applicat ion. Co m m and s that are com patible or that can betranslated wil l operate as expected, wh ile com ma nds that areincom patible will be ignored . No te that the link script shou ldwo rk properly to prod uce the desired .EXE since the ignoredcommands are ei ther performed automatical ly or do not applywhen l ink ing wi th CA-Cl ipper /Exospace .

EXOSPACE CLIPPER 501

Purpose Spec ify that you are linking a CA -Cl ipp er 5.01 or 5.01aapplicat ion

Syntax EXOSP ACE CLIPPER 501

Descr ip t ion If yo u are using CA -Clip per 5.01 or 5.01a, you m ust inclu de thiscom mand when l ink ing wi th CA -Cl ipp er /Exo space . Otherw ise ,CA -Cl ipp er /Exo space assumes tha t you are l ink ing anapplication created with a later version of the CA-Clippercompiler.

No te that inclusion of this com ma nd does not affect w hichCA -Clipper l ibrar ies are l inked— you m ust s t il l ensure that theCA-Clipper 5.01 l ibrar ies are l inked. This command merelycauses CA-Clipper/Exospace to t reat the applicat ion as aCA -Clip per 5.01 app lication. If i t is actually an app licationcreated with a la ter version of the CA-C lipper com piler,unpredictable beh avior w il l resul t.




Linker C om m an d Reference

EXOSPACE ENVIRONMENT CLIPPER

Purpose

Syntax

A rg u m e n t s

Descr ip t ion

E x a m p l e s

See Also

Specify the environment variable to use for application runtimeconfigurat ion

E X O S PA C E E N V I R O N M E N T C L I P P E R <envName>

<envName> is the na m e of the enviro nm ent variable.

By defaul t , the CL IPPE R environ men t variable controlsapplicat ion runt ime configurat ion (see "The RuntimeEnv iron m ent" chapter in this guide for detai ls) . This com ma ndlets you specify an alternative environment variable name in caseyou w ant to use a nam e unique to your applicat ion.

This example causes the application being linked to read itsrunt ime configurat ion information from an environment variablenamed MYAPP:

# Use the environment variable MYAPP# instead of CLIPPEREXOSPACE ENVIRONMENT CLIPPER MYAPP

EXOSPACE EXECUTABLE CLIPPER, EXOSPACEE N V I R O N M E N T O V E R R I D E

11-16 CA-Clipper




EXOSPACE ENVIRONMENT OVERRIDE

Purpose Cau se runt ime configurat ion environ men t set t ings to overr ide.EXE defaults

Syntax E X O S PA C E E N V I R O N M E N T O V E R R I D E

Descr ip t ion By defaul t , wh en you hard-co de runt ime configurat ion set t ingsinto a CA-Clipper executable using the EXOSPACEEXECUTABLE CLIPPER command, se t t ings spec i f ied in theCLIPPER environment variable (or the variable specif ied by theEXOSPACE ENVIRONMENT CLIPPER command) a r e i gno red .This ensures that multiple applications with different settingscan run on the same machine without changing any environmentsettings.

I f you spec ify EXO SPAC E ENV IRON ME NT OV ERRID E,however, runt ime configurat ion set t ings specif ied in theCLIPPER environment variable (or the variable specif ied by theEXOSPACE ENVIRONMENT CLIPPER command) ove r r idecorresponding set t ings hard-coded in the .EXE.

N o t e : I f you use t he EXO SPACE EN VIRO NM EN T C LIPPER

command to specify a unique runt ime configurat ionenvironment variable for an applicat ion, you may want to al lowthe .EXE settings to be overridden.

See Also E X O S PA C E E X E C U TA B L E C L I P P E R , E X O S PA C EE N V I R O N M E N T C L I P P E R




Linker Command Reference

EXOSPACE EXECUTABLE CLIPPER

Purpose Hard-code default runtime configurat ion settings in the .EXE

Syntax EXOSPACE EXECUTABLE CLIPPER <settings>

Arguments <settings> is one or more enviro nment settings. In addition tothe settings listed in the table under Setting the ApplicationEnvironment in The Runtime Enviro nment chapter of thisguide, the following settings are available for controlling theCA-Clipper/Exospace protected-mode VM system:

Setting Meaning

L O W M E M : < / 7 K B y t o > Set the amount of low DOS memoryto reserve for allocation by third-party libraries for interrupt routines.The default is 0. Ignore this unlessyour third-party librarydocumentation specificallyrecommends that you set it.

MAXMEM:<nKBytes> Set the maximum amount of physicalmemory to use before swapping todisk. The default is 8096 KB, whichis ample for most applications. In atask switching environment, youmay want to lower this value.

MINMEM:<ni<CBi/te> Set the mini mum amount of physicalmemory that must be available torun the program. If there is notenough memory available, an errormessage is generated and theapplication returns to DOS. Thedefault is 1024 KB, which is therecommended minimum.

VMSIZE:<nKBytes> Set the amount of virtual memorythe VM system should provide. Thedefault is 8096 KB, which is amplefor most applications.

11 18 CA Clipper




N o t e : You can also specify these settings in the CLI PP ERenvironment variable (or the variable specified by theEXOSPACE ENVIRONMENT CLIPPER command) and on theapplicat ion command l ine as described under Set t ing theAppl ica t ion Envi ronment in 'The Runt ime Envi ronment"chapter of this guide.

The fol lowing rules apply when specifying environment set t ings:

• Preface each set t ing with a doub le-slash

• Place a s ingle blank space betw een set tings

• Place a colon betw een set t ing and argum ent , with nointervening space

Descr ip t ion By defaul t , appl icat ions that you create using the CA -Clip percompiler and the CA-Clipper/Exospace l inker rely on set t ings inthe CLIPPER environment variable (or the variable specif ied bythe EXOSPACE ENVIRONMENT CLIPPER command) t odetermine certain runt ime configurat ion parameters .

The EXOSPACE EXECUTABLE CLIPPER command l e t s youhard-code runt ime contigurat ion set t ings in the .EXE,eliminating the need to rely on an environment variable for the

information.

Norm al ly, i f you use EXO SPA CE EXE CU TA BLE CLIPP ERcommand to l ink, the runt ime configurat ion environmentsettings are igno red. Yo u can, ho w eve r, offer the flexibility ofoverriding the hard-coded defaults with similar settings in theenvi ronment var iab le us ing the EXOSPACE ENVIRONMENTOVERRIDE command .




Linker Co mm and Re fere nce

E x a m p l e s This exam ple sets the num ber of f i le handles to 40 and preventsthe use of EGA/VGA extended cursor capabi l i ty :

EXOSPACE EXECUTABLE CLIPPER //F:40 //CGACURS

This examples se t s var ious CA-Cl ipper /Exospace VM sys temsettings:

EXOSPACE EXECUTABLE CLIPPER //VMSIZE:16384//ΜΑΧΜΕΜ:2048 //MINMEM:1536

Se e Also E X O S PA C E E N V I R O N M E N T C L I P P E R , E X O S PA C EE N V I R O N M E N T O V E R R I D E

EXOSPACE EXECUTABLE NODELETE

Purpose Create an .EXE even if errors occur during l inking

Syntax E X O S PA C E E X E C U TA B L E N O D E L E T E

Descr ip t ion By defaul t , CA -C lip pe r/E xo spa ce wil l not create an .EXE iferrors occur. This command al lows you to overr ide thatbehavior, a l though the resul t ing .EXE is not guaranteed tooperate correct ly.

11-20 CA-Clipper




EXOSPACE PACKAGE

Purpose Cau se specif ied protec ted-m ode suppo rt pack ages to be include din the .EXE

Syntax E X O S PA C E PA C K A G E <package list>

A rg u m e n t s <package list> is a comma-separated l is t of packages as shown inthe table below to be included in the resulting .EXE:

P a c k a g e D e s c r i p t i o n

8514 IBM 8514 Display Adap ter. Allow s direct cal ls f rom

protected mode, with no mode switching.

DOS25 Absolu te Disk Read/Wri te compat ib i l i ty package .Services INT 25h and 26h.

INT10 Video BIOS compatibi l i ty package. Services INTlOh.

IPX IPX/SPX compat ib i l i ty package for Novel lNe two rks. Services INT 7Ah.

IPXCT Com pat ib i l ity package for CA-C l ipper Tools .

N E T 5 C NE TBIO S compat ib i l i ty package . ReplacesNETBIOS?.OBJ. Serv ices INT 5Ch.

NO VM Disab les t he CA -Cl ippe r /Exo space VM sys tem.The resul t ing applicat ion wil l run only on systemsthat have suff icient RAM to contain theapp licatio n's entire .EXE and all i ts data. (See N otesbelow for more information about this opt ion.)

Descr ip t ion Specif ies one or mo re packages to be include d in the .EXE.Packages provide protected-mode support for cer tain low-level(C or Assembler) operat ions. Specif ical ly, packages provideCA-Clipper programs transparent access to software interruptsthat are unsu ppo rted by the protec ted-m ode kernel . Pack agesare more sui table than l ibrar ies for this purpose beca use they aremuch more automatic , much less error prone, and require nosource changes.





Important You never need to use these packages in an applicationconsisting purely of CA-Clipper code that does not use any third-partlibraries. However, some third-party libraries that perform low-leveloperations—such as direct screen I/O or certain types of network

calls—may require one or more of these packages to be included. If yare using a third-party library tha t does not operate co rrectly, consultthe vendor of that library to determine whether it requires any packagto be included when linking with CA-Clipper/Exospace.

I f you spec i fy more than one EXOSPACE PACKAGE commandin the same l inker session, ei ther on the CA-Clipper/Exospacecom m and l ine or within o ne or more scr ipt f iles , each<package list> is add ed to the previous one, causing al l packagesin al l EXO SPA CE PA CK AG E l i s ts to be l inked .

No tes Disabling VM . You can a l so use the EXOSPACE PACKAGEcom ma nd to prevent the defaul t Vi r tua l M emo ry (VM ) packagefrom being includ ed. N orm ally, the VM pac kage isau tomat ica l ly inc luded in an CA-C l ipper /E xosp ace appl ica t ion .This ensures tha t CA -Cl ip per /E xosp ace appl ica tions can run ona wid e variety of target mach ines, even those that do not hav eenough physical RAM—in such cases, the VM system wil lautomatical ly swap data to disk as necessary.

H ow ever, i f you are certain that a part icular applicat ion wil lalways be run on a machine with suff icient RAM, you canexclude the VM package us ing the EXOSPACE PACKAGEN OV M co mm and. Appl ica t ions l inked in th is way may loadand initialize somewhat faster, but they will fail if there is notenough RAM on the target machine to hold the ent ire .EXE andall of its data.

Determining how much RAM a part icular applicat ion requiresm ay require som e trial and error. In general , i t is recom m endedthat you limit use of this option to special circumstances.

E x a m p l e s This exam ple includes the video BIO S packa ge and excludes theVM package :

# Include video BIOS package and exclude VM packageEXOSPACE PACKAGE INT10, NOVM

11-22 CA-Clipper




EXOSPACE PROCEDURE DEPTH

Purpose

Syntax

A rg u m e n t s

Descr ipt ion

E x a m p l e s

Set the stack size of an application in terms of maximumprocedure cal l depth

E X O S PA C E P R O C E D U R E D E P T H <maxDepth>

<maxDepth> is the m axim um depth to wh ich you can nestprocedure cal ls .

This com man d has the same effec t as the STAC K com man d, butconveniently allows you to set the stack size in terms ofproced ure depth rather than num ber of bytes. To set the s tacksize to a specif ied num ber of byte s, use the STA CK com m andinstead.

The fol lowing command al lows a maximum of 100 nestedproced ure cal ls in the applicat ion being l inked:

EXOSPACE PROCEDURE DEPTH 100

See Also S TA C K





FILE

Purpose

Syn tax

A rg u m e n t s

Descr ipt ion

E x a m p l e s

Specify one or more object files to be linked

FILE <objFile list>

<objFile list> is a com ma -sepa rated list of object or library files tolink. If you sp ecify a file with out an exten sion, .OBJ is assum ed.If you specify a library, all object files within the library arelinked . No te that in this case, you m ust specify the .LIBextension.

You can optional ly specify a drive designator and/or a pathreference for each fi le in the l is t . See How CA -Clip per /Exo spa ceSearches for Files earlier in this chapter for information on howan inpu t file is located if i ts filenam e is un qualified.

If you specify more than on e FILE com man d in the same l inkersession, ei ther on the CA-Clipper/Exospace command l ine orwithin one or more script files, each <objFile list> is added to theprev ious one , causing all files in all FILE lists to be linked .

This example links three object files to create an executable filen a m e d M A I N M E N U . E X E :

FILE MAINMENU, INVOICE, REPORTS

The next example links the same three object files and theCA-Clipper debugger l ibrary, CLD.LIB, to create an executablefi le named MAINMENU.EXE that has access to the debugger:

FILE MAINMENU, INVOICE, REPORTS, CLD.LIB

See Also LIBRARY

11-24 CA-Clipper




LIBRARY

Purpose

Syntax

A rg u m e n t s

Descr ip t ion

E x a m p l e s

See Also

Specify one or more library files to search during linking

L I B R A RY <UbFile list>

<libFile list> is a comma-separated l is t of l ibrar ies and/or objectfiles to search in orde r to resolv e any und efine d sym bol s. If yo uspecify a file without an extension, .LIB is assumed.

You can opt ional ly specify a dr ive designator and/or a pathreference for each f i le in the l is t . See How CA-Clipper/ExospaceSearches for Files earlier in this chapter for information on how

an input file is located if i ts filename is unqualified.

CA -Cl ip per /E xosp ace searches cer ta in l ib rar ies(EXOSPA CE.LIB , LLIBG.LIB , CLIPPER.LIB , EX TEND .LIB ,DBFNTX.LIB, and TERMINAL.LIB) au tomat ica l ly wi thout theneed for you to specify them as part of a LIBRARY command.These l ibrary names automatical ly supplement any l ibrar ies thatyou name us ing the LIBR ARY c om ma nd. I f you use theNO DEFL IB command , howeve r, CA -Cl ippe r /Exospace does no tautom atical ly search these l ibrary f i les; therefore, you m ay need

to specify one or more of them using the LIBRARY command,depending on your needs.

If you specify more than one LIBRARY command in the samel inker sess ion , e i ther on the CA -Cl ip per /E xosp ace com ma nd l ineor within one or more script files, each <libFile list> is ad ded tothe previous one, causing all l ibraries in all LIBRARY lists to besearched.

This exam ple specif ies that the applicat ion being l inked n eedsaccess to three l ib rar ies : PW FU N CS.LIB , CLA SSY.LIB, andP W K E R N E L . L I B :

LIBRARY PWFUNCS, CLASSY, PWKERNEL

N O D E F L I B





MAP

Purpose Cau se a ma p to be generated

Syntax M A P [=<mapFile>] [<mapO ption list>]

A r g u m e n t s <mapFile> is the na m e of the file to gen era te. If yo u spe cify thefile without an extension, .MAP is assumed.

You can optional ly specify a drive designator and/or a pathreferen ce for the file. Oth erw ise, the map file is created in thecurrent directory.

If you specify the MAP command without a f i lename, the map

file is given the same name as the resulting .EXE file (see theOU TPU T com ma nd) , but wi th a .MAP extens ion .

<mapOption list> is a comma-separated list of map options thatdete rm ines wh ich reports are wr itten to the specified ma p file. Ifnot specified , all possible repo rts are written. Yo u can specifyany combination of the options shown in the following table:

O p t i o n Reports

A Public symbols sorted by addressΝ Public symbols sorted by name

S Segments with assigned addresses

E x a m p l e s In this exa m ple, even thou gh no m ap filenam e is explicitlyspecif ied with the MA P com m an d, the ma p f ile is generated w itha defaul t nam e of TEST1 .MA P:

EXOSPACE FILE TESTl, TEST2 MAP S, Ν

On the other hand, you could specify the map filename as part ofthe MA P option . In this exa m ple , the file will be calledM Y M A P. M A P :

EXOSPACE FILE TESTl, TEST2 MAP=MYMAP S, Ν

See Also O U T P U T

11-26 CA-Clipper




MODULE...FROM

Purpose

Syntax

A rg u m e n t s

Descr ip t ion

E x a m p l e s

Search for the named module in the specified library only

M O D U L E <moduleName> F R O M <libName>

<moduleName> is the nam e of a mo dule or symbo l wh oselocation you want to specify to the linker.

<libName> is the na m e of the library in w hich <moduleName> isdefin ed. This is not an actual filena m e (that is, i t does n otinclude a path or extension) but the root portion of a library thatis a lready known to the l inker (via the LIBRARY command or

the fact that the linker knows it by default).

Normal ly, when CA-Cl ipper /Exospace encounters a re ference toan unknown module or symbol during the l inking process, i tsearches defaul t l ibrar ies (unless you specify NODEFLIB) andlibrar ies that you have specif ied using the LIBRARY command toresolve the reference. CA-Clipper/Exospace searches thelibraries in certain predefined order (called the link sequence)and stops as soon as it resolves the reference.

Using the MODULE. . .FROM command, you can te l lCA -Cl ip per /E xosp ace exac t ly which l ib rary conta ins a cer ta inmodule or symbol, thereby el iminat ing the automatic searchingthat i t w ould no rma lly perform . This feature is useful , forexample, i f you have the same procedure defined in twodifferent libraries and want to specify which of two should belinked.

This exam ple forces the l inker to link the OrdEn try m odu le fro mMYOLDLIB.LIB, even though i t may be defined in other l ibrar iesbeing l inked:

MODULE OrdEntry FROM MYOLDLIB

See Also FILE, L IBRARY, NODEFLIB





NODEFLIB

Purpose Do not search d efault l ibraries

Syntax N O D E F L I B I N O D E FA U LT L I B R A RY S E A R C H

Descr ip t ion By defau l t , CA -Cl ip per /E xosp ace searches lib rar ies w hose

n a m e s are embedded in the object mo dules being l inked. W ithCA-Clipper-compiled object f i les , t he em bedd ed l ibrar ies areCLIPPER.LIB , DBFNTX.LIB , EXTEND.LIB , an d TERM INAL.LIB .In addit ion to these embed ded l ibrar ies , CA -Cl ipp er /Exo spacealso includes the E X O S PA C E . L IB and LLIB G.LIB l ibrar ies . If youu se the NO DEF LIB comm and , CA-C l ippe r /Exospace igno resthese library files; therefore, you may need to specify one or

m o r e of them us ing the L IBRARY comm and , depend ing on yourneeds.

Important If you specify N OD EFLIB, you must explicitly specify theCA-Clipper/Exospace library, EXO SPACE .LIB, using the LIBRARYcommand. EXOSPACE must be the first library in the first LIBRAR Ycomm and encountered. Otherwise, CA-Clipper/Exospace will beunable to successfully link a protected-mode executable.

Notes

• Renaming EXOSPACE LIB: Do not r ename theCA -Cl ippe r /Ex ospace l ib r a ry, EXOSPAC E.LIB .CA-Cl ipper /Exospace requi res tha t the l ibrary ha ve thisn a m e and wil l not operate correct ly if it is renam ed.

Similar ly, d o not r ename the CA -Clipp er debu gger l ibrary,CLD.LIB. CA-Cl ipper /Exospace per forms spec ia lprocess ing on this library to a l low it to operate in protectedm o d e , s o the debugger wi l l n ot function correctly if thel ibrary is renamed .

• Using Graphic Mode Functions: If y ou use both, m ake sureyou l ink LLIBG.LIB before CLIPP ER.LIB.

11-28 CA-Clipper




E x a m p l e s This exam ple show s how to specify selected system-sup pliedlibraries if you cho ose the N O D EF LIB o ption. In this case, theDBFMDX driver is used instead of the defaul t DBFNTX driver,and the TER M IN AL l ibrary is not used at a l l:NODEFLIBFILE MYAPPLIBRARY EXOSPACE, CLIPPER, EXTENDLIBRARY DBFMDX, MYLIB

OUTPUT

Purpose

Syntax

<exeFile>

Examples

Specify the name of the executable file to be generated

O U T P U T <exeFile>

Th e nam e of the execu table file (.EXE) to gen erate. If you do n otspecify an OUTPUT file, the name of the first filename (eitherscript or object) encountered on the CA-Clipper/Exospacecommand l ine is used, but with an .EXE extension—you cannotoverride this default extension.

You can opt ional ly specify a dr ive designator and/or a pathreference for the file. Oth erw ise, the execu table file is created inthe current directory.

This exam ple specif ies that the executable f i le be nam edM YD BU.EX E. I f the OU TP UT com man d was not spec if ied inthis case, the resul t w ould be D BU .EXE , after the name of thescript file:

EXOSPACE @DBU OUTPUT MYDBU

See Also FILE





STACK

Purpose

Syntax

A rg u m e n t s

Descr ip t ion

Examples

Set the stack size of an application in bytes

S TA C K <sizeBytes>

<sizeBytes> is the nu m ber of byte s to allocate in decim al. Thevalue you specify can be any posi t ive number up to 65,535.

The stack s ize determines h ow deep the procedu re cal l s tack canbe . In mo st cases, i t is mo re convenien t to use the E XO SPA CEPRO CED UR E DE PTH com mand in s t ead , bu t t he STACKcommand provides more accurate control over the s ize of thestack.

This example sets the stack size at 8192 bytes:

STACK 8192

See Also E X O S PA C E P R O C E D U R E D E P T H

Π-30 CA-Cl ippe r



Troubleshooting

Troubleshooting

This section suggests ways to resolve certain problems that canoccur wh en you execute your CA -Cl ip per /E xosp ace appl ica t ion ,such as:

• Ho w to determ ine the cause of an applicat ion fai lure

• W hat to do about mem ory problems

• W hat to look for i f your prog ram terminates abnorm allyunder DOS Protec ted-Mo de In ter face (DPM I)

• Ho w to deal with third-party l ibrary prob lems

• Ho w to ensure ma xim um comp atibi l ity for your applicat ionunder various operat ing environments

Exam ine this sect ion for solut ions to your prob lems before youcal l Computer Associates Technical Support .

If the A pp lication Does N ot Run

If you r applicat ion d oes not run on a particular mach ine or w ithother software that uses extended memory, answer thesequest ions to help determine what the problem is :

1. In wh at w ay does the applicat ion fai l?

Can yo u load the applicat ion at a ll? If so, w hat b ehavio rdoes the fai l ing prog ram exhibi t? Does your ap plicat iondisplay any error me ssages? If so, wh at message andregister values appear on the screen?

2. Does PM INFO run?

If you cannot run your program at al l , t ry running PMINFO,

supplied w ith CA-Clip per. I f i t runs, the problem is notl ikely to be a BIO S incom patibi l i ty.




What resident programs are loaded on your system?

Yo u m ay have a device driver or som e other software ( l ikenetwork software) that is incompatible withCA -Cl ip per /E xosp ace . To de termine whether the problemis caused by a softwa re incomp atibi l i ty, t ry running yourapplicat ion af ter unloading your network drivers orremoving DE VIC E= s ta tements f rom your CON FIG.SYS. I fthe CA-Cl ipper /Exospace program runs when the o therpro gram is rem oved , there is a comp atibi l i ty problem .

CA -Cl ip per /E xosp ace fo l lows the DP M I, Vir tua l Cont ro lProgram In ter face (VCPI) , and Extended Mem ory (XMS)protoco ls . I f the prod uct that preventsCA -Cl ip per /E xosp ace f rom running fo l lows one of theseprotoco ls , cal l Co mp uter Associates Technical Suppo rt . I f i tdoes not, refer to Software Compatibility later in thischapter.

What kind of a machine are you running on?

If PMINFO does not run on your machine af ter you haveremoved other resident programs, your system or BIOS isnot compat ib le wi th CA-Cl ipper /Exospace .

If you are running o n a machin e that you think isAT-compatible , your system BIOS is probably not

compat ib le wi th CA -Cl ipp er /Exo space . Run RM INFO to ge tthe information abou t your system that you could not getf rom PMINFO (RMINFO does every th ing tha t PMINFOdoes except at tempt to switch to protected mode).

How much avai lable memory does your system contain?

If the applicat ion fails with the message "no t eno ughmemory/ ' your sys tem may not have enough memory or theme mo ry may not be ava i lab le to CA -Cl ipp er /Exo space . SeeMemory Shortage later in this chapter.



Troubleshooting

How Does It Fail?

Protect ion Fault I f your C A- Cl ipp er/E xo spa ce applicat ion terminates with a

General Protection Fault (Error 35), look at the selector thatCA-Clipper/Exospace reports as the locat ion of the problem.

The selector is the num ber printed before the colon. Forexam ple, in the error messag e belo w, the faul t is reported asoccu rring " at 016F:0O 22." In this case , the selector is 016 F:

Error [35] : General Protection Fault inMYAPP.EXE at 026F:0022code=0000 ss=07FF ds=07FF es=0000ax=0004 bx=0016 cx=0000 dx=0000sp=7B50 bp=7B56 si=0000 di=0001

Unless your applicat ion is running under DPMI (for example, ina Microsoft Windows DOS box), a selector value less than 200hindicates an error in the CA -C lip pe r/E xo sp ace cod e. Selectorvalues greater than 200h indicate a problem in the applicat ioncode—either in a third-party l ibrary, or other C or Assemblercode. The error message shown above was generated by aNULL pointer error in a third-party library or other C orAssembler code .

When you l ink an applicat ion, you can generate a .MAP fi leusing the M A P com m and . Un less your application is runn ingunder DPMI, you can f ind out which module and/or rout ine isat fault by finding the selector number and closest offset in themap file.

Another way to determine where the problem is occurr ing is touse the CA-Clipper debugger to t race up to the point where theproblem occurs .

Not α DOS/16M If you get the me ssage "no t a D O S/ 16 M exe cut able / ' your cop y

Exe cutab le of the applicat ion ma y be corrup ted. This indicates that a virusmay exist on your system . Use a virus scanning program todetermine if there is a virus on your system; if there are noviruses, try relinking the application.

If you enco unter this error on any of the CA-C lipper dis tr ibut ionfi les , try reinstal l ing CA -Clipp er from the dis tr ibut ion disket tes .

Pro gram min g an d Utilit ies G uide 11-33



Troubleshooting

System Han g It can be difficult to deter min e the caus e of a system han g,becau se the system hal ts before you can obtain any significantinformation about the problem.

Try running the program on a different machine to determinewh ether the prob lem is hardw are-related. I f i t runs on anothermachine, compare the configurat ions of the two machines todetermine the source of the problem.

If the applicat ion does not run on any m achine y ou have , tryloading the program under the CA-Clipper debugger andlooking at the code that executes prior to when the system hangs.This may give you an indication of the cause or source of theproblem.

If you call us for support, we will ask more questions: Whathap pens wh en the prog ram terminates? Is the keyboarddisabled, or does your machin e spontaneou sly reboot? Is theredisk act ivi ty? When the system hangs, does Ctr l+Alt+Deletework to reset i t?

W hen you cal l us , we m ay also ask you to try reproducing theproblem in a small test case.

Running PMINFO I f PM IN FO runs on you r ma chine , you can usual ly rule out mo sthard wa re or BIOS incom patibi l i t ies and confl icts with othersoftware that uses extended m em ory. PM IN FO is a small ,s imple pro gram , so your problem could be one that only occurswhen a program uses a lot of memory or at tempts somethingfair ly complicated.

If PMINFO fai ls , then you have a hardware or BIOS problem, ora prob lem w ith other softwa re that uses extended m em ory. Ifremoving resident software does not remedy the problem, runRMINFO and send us the fol lowing information so we can

resolve the problem:• Ou tput from RM IN FO (redirect to a f i le)

• The fact that PM IN FO would not run on your machine

• Your nam e, address , phone num ber

• A descript ion of your com puter

11-34 CA-Clipper



Troubleshooting

You may also want to call us for help in determining whetheryou have a hard wa re prob lem , or the dealer or manufactu rer ofyour machine to see if there is a newer BIOS available to support

protected -mo de produ cts . Such a BIOS could enable you to runCA-Cl ipper /Exospace on your machine .

AT&T 6 30 0 Plus I f you are running your CA -C lipp er/E xo spa ce applicat ion on anAT&T 6300 Plus, which runs MS-DOS but is not completely AT-compatible , use the DOS16M environment variable to specify them ach ine type. (Unless VCP I or DP M I is active, this also specifiesthe switch mode.)

For an AT&T 6300 Plus, set DOS16M as fol lows:

SET DOS16M=6

Sof tware Compa t ib i l i t y

Sharing Extended Tw o CA -Cl ipp er /Exo spac e appl icat ions can share ex tendedMemory— me mo ry witho ut confl ict. Ho w ever, i f anCompatibil i ty Notes CA -Cl ip per /E xosp ace appl ica tion and a pro tec ted-mode

application that does not use C A-C l ippe r /Exospace a r erunning concurrent ly, the two applicat ions may have t roublesharing the extended memory.

The protected-mode DOS extender technology on whichCA-Clipper/Exospace rel ies is supplied by Rational Systems,Inc. , a leader in protected -mo de technology. M any com merc ialapplications that run in protected mode rely on the RationalSystems technology, including applicat ions from Lotus, IBM,Quar te rdeck , Bor land , Syman tec , and W atcom . Suchapplicat ions should successful ly coexist w ithCA-Cl ipper /Exospace appl ica t ions .

However, when running other protected-mode applicat ionsalongside CA-Clipper/Exospace applicat ions, i t is possible thatthe f i rs t CA-Clipper/Exospace applicat ion which s tar ts up mayreserve al l avai lable extended m em ory , unless it is runn ingunder a DPMI host , a VCPI host , or an XMS manager.




Troubleshooting

W ithout a mem ory m anag er, if you try to s tart up aprotected-mode applicat ion that was not bui l t withCA -Cl ippe r /Exosp ace a f te r you r C A-Cl ippe r /Exospaceprogram , the non -CA -Cl ipp er /Exo space appl ica t ion wi l l no t

f ind any extended memory avai lable.

There are several ways to avoid this prob lem:

• Use a me mo ry ma nager w hose protocol both program sadhere to.

CA-Cl ipper /Exospace fo l lows the DPMI, VCPI , and XMSpro toco ls. If the other prog ram also follow s one of theseprotocols , the memory manager wil l ensure that theprogram s proper ly share m emory.

• Star t the no n-C A-C lipp er/E xos pac e applicat ion f i rs t .

I f the non-CA-Cl ipper /Exospace , pro tec ted-modeapplication reserves only the memory that i t needs, theCA-Cl ipper /Exospace program uses ex tended memory tha tthe first does not reserve.

• Use the DO S16 M environm ent variable to l imit the amo untof mem ory tha t the CA -Cl ipp er /Exo space appl ica t ion canuse.

For example, to l imit the CA-Clipper/Exospace applicat ionto 1 MB, use this setting:

SET D0S16M= :1M

• Use the DO S16 M environm ent variable to set the range ofmemory tha t CA-Cl ipper /Exospace uses .

11-36 CA-Clipper



Troubleshooting

If you can specify a range of m em ory for the non-CA -Cl ip per /E xosp ace appl ica tion , you may be ab le toestablish a private range for each application so that they d o

not confl ict . The DOS16M environment variable al lows youto specify a range for the CA-Clipper/Exospace applicat ion.

For example , i f you can make your non-CA-Cl ipper /Exospaceapplicat ion ut i l ize addresses from 1 MB to 2 MB, you canspecify the memory from 2 MB to 3 MB forCA -Cl ip per /E xosp ace . To spec ify th is range of mem ory, useone of these set t ings in your DOS16M environment variable:

SET D0S16M= @2M - 3MSET D0S16M= :1 (22M

If set t ing a range in the DOS16M environment variable doesnot solve the pro blem , remove the set ting.

A20 Problems If the fifth digit of the add ress disp laye d in the G PF errormessage, when your machine abnormally terminates , is an oddnumber (for example, f rom 0x10000 to OxlFFFF, or from 0x30000to 0x3FFFF), you may be running software that requires r igorousm anag em ent of the A20 l ine. Try set ting the A2 0 option in theDOS16M envi ronment var iab le :

SET DOS16M= A2 0




Troubleshooting

Memory Shortage

I f you encounter a "not enough m em ory " e r ror when youat tempt to execute your applicat ion, run PMINFO to determinehow much memory i s ava i lab le for CA-Cl ipper /Exospaceapplicat ions.

E x t e n d e d M e m o r y N o t Av a i l a b l e

CA-Cl ipper /Exospace uses ex tended memory, no t expandedme m ory. If you can configure your mem ory ei ther wa y, and youare not running under an expanded memory manager, be sure toconf igure the mem ory as ex tended mem ory.

If you are using an expanded memory manager that fol lows theVCPI pro tocol ( such as EMM386, QEMM, or 386MAX), yourCA -Cl ip per /E xosp ace appl ica tion a l loca tes i ts mem ory f rom theVC PI host (unless you also have an XM S ma nag er) . Thereforeyou do not have to configure i t as extended m em ory.

If you have a VCPI host and an XMS manager (such asHIM EM .SYS) , CA -Cl ippe r /Exo space a l l oca te s memory f romboth the VCPI pool and the XMS pool .

If you have another program that uses extended memory, seeSoftw are Co mp atibi l i ty earl ier in this chapter.

Using the High M em or y Ar ea

I f you are running CA -Cl ip per /E xosp ace on an o lder machine(manufac tured before 1989) and PM INF O repor t s less m emo rythan your hardware documentat ion specif ies , your manufacturermay be count ing ex tra me mo ry as ex tended memory. The HighM emo ry Area (HM A) i s the a rea be low 1 M B but above the640 KB conventional ly used by DOS.

For example , an AST m achine may be docum ented to have 2 MBof extended memory, but PMINFO reports only about 1.7 MBbecause AST ut i l izes HMA. Some manufac turer-spec i f ic RAMdrives also use the HMA.

11-38 CA-Clipper



Troubleshoot ing

CA-Clipper/Exospace automatical ly ut i l izes this memory on aCompaq 386 machine, but i t does not recognize i t on othermachines. You can set the DOS16M environment var iable to test

the memory between 640 KB and 1 MB and use whatever i t f indsthat is not read-on ly me m ory . To try this, use the + option inyour DO S16M envi ronm ent var iab le se t t ing :

SET DOS16M= +

If implementing this set t ing does not solve the problem or makesi t worse, remove the set t ing and reboot your machine.

B a d M e m o r y

If your system is configured with adequate extended memory,and you s t i l l encounter a "not enough memory" error, some ofyour configured memory may be bad. Another indicat ion of badmemory is when your program consis tent ly terminates at thesame address .

A simple way to check for bad memory is to set the memoryrange at different mem ory locat ions and see if your appl icat ionst il l does not run. For exam ple, if you have 4 MB of mem ory onyour machine, and your appl icat ion takes less than 2 MB, youcould try the following setting:SET D0S16M= @2M

With this set t ing, CA-Clipper/Exospace s tar ts loading theexecutable at 2 MB, leaving extended memory below thatlocation free. If the application runs with this setting, someport ion of the memory below 2 MB is bad.

Programming and Uti l i t ies Guide 11 -39



Troubleshooting

Problems When Running Under DPMI

If you have a program that runs well under DOS but abnormallyterminates when i t runs under a DPMI host , such as Windows3.1 in enhanced mode or a Vir tual DOS Machine under OS/2 2.0,check for the fol lowing problems:

• Ho w m uch m em ory does your appl icat ion require?

Ensure that enough extended memory is avai lable from theDPMI host .

• Does your prog ram shel l out to another program?

In the DPMI 0.9 specif icat ion (which enhanced-modeWindows 3.x fol lows) , only one protected-mode appl icat ion

can run on a vir tual machin e at a t ime. That mea ns that youcannot run two protected-mode programs in the same DOSbox under W indow s 3 .1 in enhanced m ode .

Modify your program so that i t does not shell to aprotected -mo de prog ram . DP M I hosts that fol low the 1.0specif icat ion al low more than one protected-modeapplicat ion to run. Som e 0.9 DP M I hosts have extensionsthat a llow tw o protected-m ode appl icat ions to run on thesame virtual machine, but i t is difficult to detect thiscapability.

11-40 CA-Clipper



Troubleshoot ing

Problems In Third-Party Libraries

Before l inking your CA-Clipper appl icat ion with

CA -Cl ipp er /Ex ospa ce , you need to ensure that any th i rd-par tylibraries you are using are compatible withCA-Cl ippe r /Exospace .

CA -Cl ipp er /Ex ospa ce i s compat ib le wi th mos t th i rd-partyl ibrar ies for CA-Clipper because most of them are generalpurpose funct ion l ibrar ies that consis t most ly of CA-Clippercode. Ho we ver, incom patibi l i ties wil l ar ise i f a third-partyl ibrary performs ope rat ions that are not valid in protected m od e.Typically, only libraries that perform very low-level orhardware-dependent opera t ions presen t p roblems.

If you use third-party l ibrar ies in your prog ram , you may nothav e access to the source cod e for the library . W ha t if there is aprotected -mo de violat ion in the l ibrary? Here are somesolutions:

• Seek assis tance from the l ibrary vend or. Problem s areusual ly easy to correct and rarely require m aintenan ce of adis t inct version for protected mode.

• If the violation is in a sm all m od ule , you may be able to write

a replacemen t for that m odu le. A good exam ple of this is theCA -Cl ippe r /Exosp ace l i b r ary, EXO SPAC E.LIB , wh ichincludes replacement modules for violat ions in CA-Clipperand the M icrosoft C 8.0 runt ime l ibrar ies . Rem em ber that i fyou redefine a module, you may need to include aMODULE. . .FROM command to ensure tha t your vers ion ofthe module is l inked.

• Exe cute the library in real m od e. Yo u can either l ink thel ibrary as a separate program and communicate withinterrupts , or you can use other special funct ions from the

CA -Cl ipp er /E xosp ace l ib rary for man aging mem ory andperforming inter-mode cal ls .




Troubleshooting

Environment Compatibility Issues

This sect ion provide s a detai led discussion of possibleenviron me nt-related com patibi l i ty issues, specifically in the

areas of:• P C /A T compat ib il i ty

• Extended mem ory

• DO S vers ions

PC/AT Compa t ib i l i t y

CA -Cl ippe r /Exospace works on a ll IBM PC/A T-com pa t ib l e

com puters . The re are , how ever , som e ma chines that c laim ATcomp atibi l i ty, but fai l in cer tain important res pects— an 80286CP U does not m ake a ma chine comp atible . The BIOS code mustalso be compatible .

Because the 80286 does not have a direct way to switch fromprotec ted m ode to rea l mo de , CA-C l ipper /E xospa ce forces theswitch by reque st ing a reset (much l ike power on or rebooting) .When i t receives the reset , your ROM BIOS star tup code must beable to distinguish a restart from a power up, in order to returnto the CA-Cl ipper /Exospace kerne l .

The 80386 and 80486 processors have a direct way to switch fromprotected m od e to real m od e, I f you have an 80386 or 80486, youwil l not encounter this problem.

CA -Cl ipp er /Ex ospa ce wi l l run on any PC that :

1. Has an 80286, 80386, or 80486 CPU.

2. Can run M S-D O S or com patible operat ing system, Version3.0 or later.

3. Suppor t s IB M -P C/ A T BIOS In te rrup t 15h func tion 88h (ge tex tended m emo ry s ize).

11-42 CA-Cl ipper



Troubleshoot ing

4. Is com patible with the IBM PC /A T in these respects :

• CM OS RA M (for sav ing t im e/d a te , conf igura tion da ta ,and the restart code) accessible via I/O ports 70h and71h

• Intel 8259-com patible Prog ram ma ble InterruptControl ler, accessible via I /O ports 20h and 21h(additional controllers may be cascaded to the first)

• Intel 8042 auxiliary pro cess or, with control port at I/ O60h, and s tatus port a t I /O address 64h

• "AT -com pat ib le " RO M BIOS code that suppor t s som eform of restarting

E x t e n d e d M e m o r y

The CA-Cl ipper /Exospace program, EXOSPACE.EXE, as wel l asappl ica t ions l inked wi th CA -Cl ipp er /Ex ospa ce , requi reex tended memory whi le running . Extended memory i s memoryaddressed by the CPU above 1 MB .

CA -Cl ipp er /Ex ospa ce does no t work wi th EM S, as def ined bythe Lotus / In te l /Microsof t bank-swi tch ing scheme, a l though i t

can use memory managed by products that use the 386 VCPIstandard, as descr ibed below.

In i ts defaul t configurat ion, the CA-Clipper/Exospace loaderut i lizes about 90 KB, 18 KB of wh ich is in low mem ory. Un de r aVC PI host , the VCP I page tables are also s tored in low m em ory ,adding about 15 KB to the low memory footprint . Under DOSDP M I, the s tack is a lso locked in low me m ory. Und er so mecircumstances, you can reduce the amount of memory thatCA-Cl ipper /Exospace requi res .

In most cases, no special action needs to be taken to makeextended mem ory ava i lab le to CA -Cl ipp er /Ex ospa ce . Ho we ver,to ensure that CA-Clipper/Exospace and appl icat ions l inkedwi th CA-Cl ipper /Exospace a re running opt imal ly, you maywish to ensure that enough extended memory is avai lable .




Troubleshooting

If you are runnin g M S-D OS Version 5 or la ter, you can executethe MEM command to f ind out how much convent ional andextended memory is avai lable .

Two i tems l is ted by the MS-DOS MEM command are importantto CA -Cl ipp er /Ex ospa ce : "ava i lab le cont iguous ex tendedmemory" and "ava i lab le XMS memory." Depending on yourma chine 's configurat ion, one of these i tems m ay be missing or i tsvalue may be zero, but as long as one of the two items has avalue of 1 MB or greater, you should be able to runCA -Cl ipp er /Ex ospa ce and CA -Cl ipper /Exosp ace appl ica tionssuccessfully.

If neither of these items are listed when you execute MEM, ortheir values are both zero or less than 1 MB, you may need tochange the machine 's configurat ion in some way, perhaps byinstal l ing more extended memory or by reducing the amount ofme mo ry al located to any other resources that uti l ize X M S.

In general , the ma nne r in which a mach ine is configured viaCONFIG.SYS should not be of concern, as long as enoughextended memory is avai lable . Software dr ivers for extendedand expanded memory are descr ibed in the fol lowing sect ion.

Extended Memory CA -Cl ipp er/E xos pac e wo rks with the fol lowing protocols that

Protocols use extend ed m em ory:• DO S Protected -Mo de Interface (DPM I)

• Vir tual Control Program Interface (VCPI)

• Extended M em ory S tandard (XMS)

11-44 CA-Clipper



Troubleshoot ing

The fol lowing table shows examples of products that use theseprotocols and l is ts the versions that CA-Clipper/Exospace workswith:

Protocol Products Vers ions

DPMI Microsof t Windows, 386Enhanced mode

3.0 and later

OS/2 Vir tua l DOS Machine 2.0 and later

VCPI Q E M M 4.1 and later

E M M 3 8 6 MS-DOS 5 orMS-Windows 3 .1

and later

3 8 6 M A X 4 .01 , 4.02, 4.06and later

X M S H I M E M . S Y S 2.10 and later

W hen your CA-C l ipper /E xosp ace appl ica t ion s tar ts up ,CA-Cl ipper /Exospace searches the envi ronment for memoryma nage rs , in the order lis ted below . In mo st cases ,CA -Cl ipp er /Exo space uses the fi rs t mem ory m anager tha t i t

finds:1. A prev ious ly- loaded CA -Cl ipp er /Ex ospac e program wi th a

non-pr iva te memory pool

If i t f inds a loaded CA-Clipper/Exospace appl icat ion, theappl icat ion uses the same memory pool as the f i rs tappl ica t ion . (You can c rea te C A-C l ipper /E xosp aceprograms that use pr ivate memory; this pr ivate memory wil lnot be avai lable to subsequ ent ly loadedCA-Cl ipper /Exospace appl ica t ions . )

If a previous loaded CA-Clipper/Exospace appl icat ion is notfound , it cont inues searching.

2. A DPM I hos t

If CA-Clipper/Exospace f inds a DPMI host , i t fol lows theDPMI pro tocol . The DPMI hos t manages memory.

If i t does not find a DPMI host, i t continues searching.




Troubleshooting

3. A VC PI host

If CA-Clipper/Exospace f inds a VCPI host , i t fol lows theVC PI protocol . I t a lso searches for an XM S driver.

4. An XM S dr iverIf CA-Clipper/Exospace f inds an XMS driver, i t fol lows theXM S protocol to al locate m em ory from the XM S pool . I fboth a VCPI host and an XMS driver are found, i t allocatesmemory from the XMS pool and from the VCPI pool .

W ith VC PI only, the VC PI protocol is fol lowed. With X M Sonly, the XM S protocol for a l locat ing m em ory is fol lowed.

I f CA -Cl ipp er /Exo space does no t f ind any mem ory m anagersthat use one of these protocols, i t uses BIOS Interrupt 15h,funct ion 88h on ATs and compatibles to determine how muchmemory is avai lable to i t . On other non-AT-compatiblemachines , your users mus t use the DO S16M envi ronmentvariable to specify the exact extended memory range.

Except under VC PI and DPM I, CA -Cl ipper /E xospa ce a l loca tesal l avai lable mem ory, unless you restr ic t the amou nt of m em oryyour program can ut i l ize .

Device dr ivers that a l locate their memory from a DPMI, VCPI, or

XM S pool pose no problems for CA -Cl ippe r /Exosp ace . Inaddi t ion, CA-Clipper/Exospace works with the fol lowing devicedrivers , even when they do not a l locate memory from a s tandardmemory manager :

D ev ic e Dr iver Vers ions

R A M D R I V E . S Y S 2.0 and later

SM ART DRIVE . SYS 2.0 and later

VDISK.SYS All IBM versions

11-46 CA-Cl ipper



Troubleshooting

Other appl icat ion prog ram s, device dr ivers , or TSR s ( l ike diskcaches) that do not use DPM I, VCPI , XMS , or Interrupt 15h,funct ion 88 for managing extended memory wil l not work with

CA-Clipper/Exospace programs i f they s tar t beforeCA-Cl ippe r /Exospace .

CA -Cl ippe r /Exos pace appl ica tions wil l work underenvironments such as Windows ( including Windows 3.0 or la terin enhanced m ode) , Carouse l , Doub leDOS , DESQv iew, andothers.

DOS Versions

This sect ion descr ibes CA-Clipper/Exospace compatibi l i ty issueswith specific versions of DOS.

DOS 3.x to 4.x CA -Cli ppe r/E xos pac e runs with DO S Version 4.0, but i t does notwork wi th XMAEM.SYS, which suppor t s no ex tended memoryprotocol.

DOS 5.0 a n d 6 .0 CA -Cl ipp er/E xos pac e runs und er DO S Version 5.0 and 6.0.These D OS ve rsions al low you to put most of the DOS cod e inthe high me mo ry area (HM A), the 64 KB abov e 1 M B, saving

about 50 KB of conven t ional mem ory. They also allow you toput TSRs and device dr ivers in the upper memory area, between640 KB and 1 M B, wi th the LO AD HIG H and DEV ICEH IGHcommands .

To use the features offered in DOS 5.0 or 6.0, however, you mustalso use a me mo ry manage r. These DO S versions come withEM M 386, which is a VCP I hos t, and wi th HIM EM .SYS, an X M Smemory manager upon which EMM386 depends . You can useQEMM or 386MAX ins tead of EMM386.

CA-Cl ipper /Exospace programs run wel l wi th DOS=HIGH,becaus e they do not use mem ory in the HM A. In fact ,management of the A20 l ine works bet ter with HIMEM.SYSwhen you se t DOS=HIGH.




Troubleshooting

To use the LOADHIGH command wi th EMM386, se t the RAMswitch to ma ke it an "upp er mem ory block prov ider." To usethe DEVICEHIGH command, se t DOS=UMB in yourCONFIG.SYS.

For more in formation about running CA -Cl ipper /Exo spaceprograms in environments that have memory managers , seeExtended Memory ear l ier in this chapter.

DOS 5.0 Task Switcher If you use EM M 386 and H IM EM .SY S, you should be able to runmult iple CA-Clipper/Exospace appl icat ions under the DOS 5task switcher, DOSSHELL, without any problems.

When you use other memory managers ( l ike QEMM or386MAX), the DOS 5 task switcher takes al l the XMS memory,leaving none for the m em ory m anager. To avoid this problem ,set the opt ions that reserve EM S m em ory for the m emo rymanager :

• W ith Q EM M , set the EM B param eter to indicate themaximum amount of XMS memory that wil l be avai lable tothe task switcher

• W ith 386 M AX , set the EM S or the EX T option to indicate theamount of EMS memory that the memory manager wil lcontrol

This table summarizes the requirements for runningCA-Clipper/Exospace programs with the task switcher:

M e m o r y M a n a g e r R e q u i r e m e n t fo r S u c c es s

386M AX Use EM S or EXT parameter

EM M3 86 + HIM EM Default s should work

Q E M M Use EMB parameter

11-48 CA-Clipper



Troubleshooting

O S/2 Virtual DOS CA -Cl ipp er /Ex ospac e program s can run in a Vi r tua l DO SMachines Mach ine wi th in O S/ 2 , Vers ion 2.0 or later; this environment is

a D PM I hos t. Us ers ma y need to set one or both of thefol lowing parameters for the Vir tual DOS Machine:

• D P M I _ M E M O RY J L I M I T

This is set to 2 M B by defaul t . I f your program needs m orethan 2 MB, have your user specify a larger l imit.

• H W _ T I M E R

In order to get an accurate reading for PMIN FO , turn thet imer ON.

Other parameters may affect your program behavior; this hasmore to do with the way OS/ 2 emulates DOS than i t does withDOS extension.

To access these parameters , fol low this procedure:

1. F rom the Sys tem /C om m an d Prompt wind ow, se lec t the iconfor the Vir tual DOS Machine.

2. Bring up the m enu (Shif t+FlO).

3. Select Ope n >Set t ings from the m enu.

4. W hen the set t ings box opens, select Session from the tabbedoptions at the right.

5. Select the DO S settings butto n. Th e list of para m eters willappear.

For information about these parameters , please refer to yourO S/ 2 documenta t ion .






Chapter 12

CA-Clipper Real Mode Linker—BLINKER.EXE


W elcom e to Blinker, the real m ode l inker for CA -Clipper . Th ischapter provides all the information you need to link yourappl icat ions with Blinker, and explains the benefi ts of doing so .The fol lowing topics are discussed:

• Ov erview of Blinker

• Up grad e offer

• Bl inker com ma nd re fe rence

• Blinker funct ion reference

Pro gra m m ing a n d Utilities G uid e 12-1



Overview of Blinker

Overview of Blinker

CA-Clipper 5.3 contains a l imited version of the full Blinkerproduct produced by Blinkmc. This real mode CA-Clipper 5.3version of Blinker features:

High-Speed Unking

Dynamic Over laying

Cach ing o f P rogramOverlays

Compress ion of theSymbol Table

Support for thePag ing System

Suppor t for "burnedin " CLIPPEREnvironmentVar iables

High-speed l inking of real mode CA-Clipper 5.3 programs.

Dynam ic over lay ing of CA-C l ipper, C /C + + and Assemblercode within real mode CA-Clipper 5.3 programs to overcomethe 640K B mem ory l imit . Dyn am ic overlaying is the process ofbreaking a program into small pieces and only loading onepiece into memory at a t ime, instead of keeping the entireprogram in memory al l the t ime. Once the programmer has

specified which part(s) of the program to overlay, Blinkerautomatical ly m anag es the overlays at runt im e to mak e the bestuse of avai lable real mode memory.

Caching of program over lays to EM S /X M S to op t imize run t imeperform ance of the overlaid .EX E, plus the uti l izat ion of U M Bsand the EMS pageframes to execute overlays in the real modememory above 640KB.

Compression of the CA-Clipper symbol table to reducememory requirements and the s ize of the runt ime .EXE.

Support for the CA-Clipper paging system to opt imize memoryusage and improv e run t ime per form ance .

Support for "burned in" CLIPPER environment var iables in the.EXE for ease of config uration an d distribution. On ce aCLIPPER envi ronment var iab le has been "burned" in to the.EXE, i t cannot be inad vertent ly o verr idden by a change of theCLIPPER environment var iable on the runt ime machine.

12-2 CA-Cl ipper



Upgrade Offe r

Upgrade Offer

Blinkmc is making an exclusive offer to CA-Clipper 5.3custo m ers to up grad e to the full version of Blinke r. Please seethe file entit led BLINKER.TXT in the directory in whichCA -Clippe r is instal led for details and pricing inform ation.

The full version of Blinker is the only product that featuresincremen tal l inking of both real and protected m ode CA -Clipp erprograms. Incremental l inking substant ial ly reduces l ink t imesby requiring that only the parts of a program which havechanged be rel inked.

Blinker also includes a royal ty-free DOS extender which cancreate dual mode programs. This unique dual mode featureal lows the creation of a s ingle program which wil l au toma tical lyrun in ei ther real or protected mo de, dep endin g on theconfigurat ion of the runt ime machine, on any processor from the8086 to the Pentium.

Other reasons to upgrade include the fol lowing:

• L inking of Wind ows and O S /2 programs and DLL s.

• Suppor t f or C /C + + , FORT RA N, BASIC , Assemble r andearl ier versions of CA-Clipper.

• An integrated swap package to swap out the current lyexecut ing program to EM S/ X M S or d i sk and run o ther la rgeprograms from within the main program.

• Ful l M icrosoft Co deV iew debugg er support , creat ion ofdemonstrat ion versions, a ser ial izat ion feature andcomprehensive technical documentat ion.

Programming and Uti l i t ies Guide 12-3



Blinker C o m m a nd Referen ce

Blinker C o m m a n d R eference

Script fi le(s) are specified on the command line and default to anextension of .LNK . They m ay be nested, and more than one m aybe used on the command l ine, e .g . ,

BLINKER ©Defaults ©Other LIB Mylib VERBOSE.

This command line instructs Blinker to read the script fi leDE FAU LTS .LNK fo l lowed by the scr ip t f il e OTH ER.LN K.

It also instructs Blinker to use the library MYLIB.LIB and todisplay a VE RB O SE l is t ing of the .OBJ f i les being processed . Theful l names of the commands, or any unique abbreviat ion of thewords which comprise the commands, may be used al though i tis rec om m en de d that at least three letters be used for clarity. Forexample , the command BLINKER OVERLAY OPSIZE 40 can beabbrevia ted to BLIOVE OPS 40 .

Most Blinker commands may be specif ied in any order, a t anypoint in the link script fi le. Typically the first FILE statementshould specify the .OBJ containing the main program procedure.

# (comment)

Purpose

Syn tax

Descr ip t ion

E x a m p l e s

Indicate text as a script fi le comment

# . . .

Any line in the script fi le beginning with the character # istreated as a com m en t and is igno red by Blinker. If the #character occurs within a line, the rest of the line is ignored.

This example indicates the following text as a script fi le

comment :# To link or not to link, that is the question.

12-4 CA-Cl ipper



Blinker C om m an d Re ference

/ / (comment)

Purpose

Syntax

Description

Examples

Indicate text as a script file comment

/ / . . .

An y line in the script file beg inni ng w ith the characters / / istreated as a com me nt and is igno red by Blinker. If the / /characters occur within a line, the rest of the line is ignored.

This example indicates the following text as a script filecomment :

// The main file

@ (nested script)

Purpose Spec ify the na m e of a script file

Syntax @<scriptname>

A rg u m e n t s <scriptname> is the na m e of the specified script file.

Descr ip t ion Blinker sup ports nested script files of any size to a depth of 5levels. Th e processin g of nested script files is similar to aprog ram funct ion cal l . W hen Blinker encounters a nested scr iptcommand, the current script file is suspended, the second scriptis processed, and then Blinker returns to the first script andresum es proc essing . W he n searching for a script, Blinker firstlooks in the current directory, and then in the path specified inthe LIB environ men t variable. This al lows frequently usedscripts which are rarely modified, (such as scripts for overlayinga particular library), to be stored in a common directory for

convenience.

E x a m p l e s This exa mp le illustrates the use of @ (nested script):

# Process the link script 'Myscript' here@Myscript




Blinker C om m an d R eference

BEGINAREA

Purpose Spec ify the start of a dyn am ic overlay area

Syntax B E G I N A R E A

Descr ip t ion The BE GIN AR EA com ma nd is used to specify to the l inker thestart of an overlay area in the output file. Each BEGINAREAshould have a corresponding ENDAREA to indicate the end ofthe overlay area.

With s tat ic overlays, BEGINAREAs, and therefore overlay areas,may be nested within one another as long as there is acor responding EN DA REA for each BEG INAR EA. This a l lows

the developer to create a structure of overlays within an area touse the minimum amount of mem ory for the max imum numb erof overlay routines.

With Blinker dynamic overlays, as opposed to static overlays, themu tual dep enden cy of each overlay procedure or f i le isunim por tant. Also , the mu ltiple nested overlay areas associatedwith static overlays are no longer necessary although multipleoverlay areas may be helpful in ordering the included libraries.The BEGINAREA and ENDAREA commands a re s imply t rea tedas markers to the beginning and end of code which is to beoverlaid.

For most compilers other than CA-Clipper the .OBJ files listedbetween a BEGINAREA and ENDAREA are managed a t run t imeon a segment basis, i .e. , the whole CODE segment for each .OBJis loaded into memory whenever any funct ion or procedurewithin that .OBJ file is called. The CA-Clipper 5.3 dynamicpaging system automatical ly breaks procedures down into IKpages for improved execution speed., so this is not a concern forCA-Clipper code.

See Also E N D A R E A

12-6 CA-Clipper




BLINKER CACHE EMS

Purpose

Syntax

Argument s

Descr ip t ion

Examples

See Also

Specify am oun t of EM S to be used for overlay caching

B L I N K E R C A C H E E M S <nuMax[% ]> [, <nuMinLcavcl%]>]

<nuMax[%]> is the m axim um num ber of KB or percentageamount of the total available EMS to be allocated to the overlaycache.

<nuMinLeave[%]> is the min imu m nu mb er of KB or percen tageamount of the total available EMS to be left for program use.

The defaul t for BLINKER CACHE EMS is 100 for <nuMax[%]>.This command specif ies the amount of EMS (LIM version 4.0and higher) memory to be used for the overlay cache.

Two numeric parameters are used to specify the amount of EMSme mo ry to be al located and the amoun t to be left for pro gramuse. Both parameters m ay be specif ied as ei ther a num ber of KB ,or as a per centa ge of the total availab le EM S. Th e secon dpar am eter alw ays overrid es the first. For exam ple , if the firstparameter cal ls for 256KB and the second requires 50% of EMSto be left free, then ha lf of EM S will be left free and the cache w illfit i tself into the remaining memory.

Blinker will never allocate a cache that is larger than the totalsize of all the overlays contained within the program.

This example defines the maximum size of the EMS cache asbeing 50% of avai lable EMS while leaving a minimum of at least1024KB avai lable for the program:# use a maximum of 50% of available EMS,# but leave at least 1024KB availableBLINKER CACHE EMS 50 %, 1024

B L I N K E R C A C H E X M S , B L I N K E R E N V I R O N M E N T N A M E




Blinker C om m an d Reference

BLINKER CACHE XMS

Purpose

Syntax

A rg u m e n t s

Descr ip t ion

E x a m p l e s

See Also

Specify am oun t of XMS to be used for overlay caching

B L I N K E R C A C H E X M S <nuMax[% ]> [, <nuMinleave[%]>]

<nuMax[%]> is the m axim um num ber of KB or percentageamount of the total available XMS to be allocated to the overlaycache.

<nuMinLeave[%]> is the min im um numb er of KB or percentageamount of the total available XMS to be left for program use.

The defaul t for BLINKER CACHE XMS is 100 for <nuMax[%]>.This command specif ies the amount of XMS (version 2.0 andhigher) memory to be used for the overlay cache.

Two numeric parameters are used to specify the amount of XMSmemory to be allocated and the amount to be left for programuse. Both pa rameters m ay be specif ied as ei ther a num ber of KB,or as a percentage of the total available XMS. The secondpara m eter alw ays overrid es the first . For exam ple, if the firstparameter calls for 256K and the second requires 50% of XMS tobe left free, then half of XMS will be left free and the cache willfit i tself into the remaining memory.

Blinker will never allocate a cache that is larger than the totalsize of all the overlays contained within the program.

This examp le defines the ma xim um size of the XM S cache asbeing 5 0% of avai lable XM S while leaving a minim um of at least1024KB avai lable for the program:

# use a maximum of 50 % of available XMS,# but leave at least 1024KB available# BLINKER CACHE XMS 50%, 1024

This examp le defines the ma xim um size of the XM S cache asbeing 512 KB w hile leaving a m inim um of 25 % of the avai lableXMS memory for the program:

# use a maximum of 512KB XMS,# but leave at least 25% of the total freeBLINKER CACHE XMS 512, 25%

B L I N K E R C A C H E E M S , B L I N K E R E N V I R O N M E N T N A M E

12-8 CA-Clipper




BUNKER CLIPPER PAGE

Purpose Ena ble /D isable au tomat ic CA-Cl ipper 5 .3 code paging

Syntax BLINKER CLIPPER PAG E ON I OFF

Descr ip t ion This com ma nd can be used to disable the CA -Clipp er 5.3dynamic paging system for CA-Clipper code. The only reasonfor ever wishing to do this is if a CA-Clipper 5.3 program withno overlays is required, for example, to create an installationprogram.

BLINKER ENVIRONMENT CLIPPER

Purpose Cha nge the nam e of the CA -Clipp er environ men t variable

Syntax B L I N K E R E N V I R O N M E N T C L I P P E R <cName>

A rg u m e n t s <cName> is the nam e of the CA -Clipp er environ me nt variable.

Descr ip t ion This com m and al lows the developer to chang e the nam e of theCLIPPER environment variable from the defaul t set t ing of

"CLIPPER" to any str ing of up to 16 characters , and thus avoidthe remo te s ite set t ings for the CLIPP ER e nvironm ent v ariable.

Used in conjunct ion wi th the BLINKER ENVIRONMENTOVERRIDE command, this al lows the set t ings burnt in with theBLINK ER EXEC UT AB LE CLIPPER comm and to be overwr i t tenat run tim e by this new ly created variable . The choice of auniqu e nam e avoids any confl ict with previou s set tings for theCLIPP ER envi ronm ent var iab le .

For exam ple, if a scr ipt fi le contains the fol lowing com m and s:

• BLINKER EXEC UTA BLE CLIPPER F31 ; X100

• B L I N K E R E N V I R O N M E N T O V E R R I D E

• B L I N K E R E N V I R O N M E N T C L I P P E R A C C S Y S





Even thoug h the fol lowing statement m ay already have been setfrom DOS:

SET CLIPPER=F21

This CLIPPER environment variable wil l be ignored by theappl ica tion , and the BLIN KER E XEC UTA BLE C LIPPER se tt ingcan be overr idden by the fol lowing DOS command:

SET ACCSYS=F99

E x a m p l e s This example i l lus t ra tes the use of BLINK ER EN VIRO NM EN TCLIPPER:

# Change the name of CLIPPER variable to NewclipBLINKER ENVIRONMENT CLIPPER Newclip

See Also B L I N K E R E N V I R O N M E N T N A M E , B L I N K E R E N V I R O N M E N TOVE RRIDE , BLINKE R EXECU TABL E CLIPPER

BLINKER ENVIRONMENT NAME

Purpose

Syntax

A rg u m e n t s

Descr ip t ion

Specify the nam e of the environmen t variable for Blinkerrunt ime options

B L IN K E R EN V I R O N M E N T N A M E <cName>

<cName> is the na m e of the env iron m ent variable for Blinker runtime options.

By default, if the argument is not specified, the default setting isBLIN KE R. This comm and is used to change the nam e of theBLIN KER envi ronm ent var iab le.

At program runtime the Blinker overlay manager checks theDOS environment for the BLINKER environment variable, and if

this is present then the variable is examined for certain runtimeparameters .

For a l is ting of the BLIN KE R env ironm ent variable 's val idparameters , see the "Runtime Environment" chapter in theProgramming and Utilities Guide.

12-10 CA-Clipper




E x a m p l e s This example i l lus t ra tes the use of BLIN KER EN VIR ON M EN TN A M E :

# Rename the Blinker variable

BLINKER ENVIRONMENT NAME TESTAPP

Following l inking with the above command, the overlaymanager wil l check the environment for the TESTAPP variable.

Use the fol lowing command at the DOS prompt to al ter theOPSIZE at program runtime without having to rel ink. :

SET TESTAPP=/OO3 0

BLINKER ENVIRONMENT OVERRIDEPurpose

Syntax

Description

See Also

Specify that environ men t set t ings m ay overr ide defaul ts

B L I N K E R E N V I R O N M E N T O V E R R I D E

As a defaul t , the variables set using the BLIN KE R EX EC UT AB LECLIPPER command wil l not be overr idden at applicat ionruntime. This al lows mult iple applicat ions with differentrequirements to run on the same machine without changing theCLIPPER environment set t ings.

This com m and is used to tel l Blinker to al low the C A-C lipperenvi ronment var iab les se t us ing the BLINK ER EXE CU TAB LECLIPPER command to be overr idden at applicat ion run t ime bythe set t ings of the CL IPPE R environ men t variable. W hen doingthis you may want to consider renaming your CLIPPERenvi ronment var iab le wi th the comm and BLINK ERE N V I R O N M E N T C L I P P E R .

B L I N K E R E N V I R O N M E N T C L I P P E R , B L I N K E R E X E C U TA B L ECLIPPER




Blinker C om m a nd Reference

BLINKER EXECUTABLE CLIPPER

Purpose

Syntax

A rg u m e n t s

Descr ip t ion

Specify defaul t CLIPPER environment set t ings

B L I N K E R E X E C U TA B L E C L I P P E R <cEnvironmentstring>

<cEnvironmentstring> is the defaul t CLIP PER environmentsettings.

This com m and is used to burn defaul t values for the CA -Clipperrun time enviro nm ent variables into the execu table file. Tho sese tt ings se t us ing the BLIN KER EXEC UTA BLE CLIPPERcommand take precedence over those set with the SET CLIPPERcommand. Parameters not specif ied with the BLINKER

EXE CU TAB LE C LIPPE R com man d wi l l re ta in va lues or ig ina llyassigned by the SET CLIPP ER com ma nd. Ho we ver, i f you wan tthe values in the SET CLIPPER command to take precedence, usethe comm and BLINKE R ENV IRON ME NT O VERRIDE.

The m axim um str ing length that can be burned into a 5.3application is 128 bytes, and Blinker will ignore all but the LASTenvironment burn-in command encountered, so al l parametersthat are to be burned in should be specified in a single BLINKEREXECUTABLE CLIPPER command .

The burned-in environment values are not returned by thefunct ion GETENVQ.

12-12 CA-Clipper




The runt ime parameters l is ted here are applicable to CA-Clipper5.3. See the "Runtime Environment" chapter of the Programmingand Utilities Guide for a com plete l is t of these param eters , co rrect

syntax and defaul t values.

Runt ime Pa ramete r s M e a n i n g

E:nnnn Expanded Memory in KB

F.nnn Number of f i les

X:nn EXclude memory in KB

B A D C A C H E Protect the EMS pageframe

C G A C U R S Disable EGA cursor

DYNF:nn Number of handles fordynamic paging

N O I D L E Disable background garbagecollection

SW AP Kin nnn Size of disk swa p f i le

SWAPPATH: 'pa th ' Path for swap file

TEM PP ΑΤΗ : pa th ' Path for temporary files

CA-Clipper 5.3 environment set t ings can always be overr idden( rega rd l es s o f t he BLINKER E NV IRON M EN T OV ERRID Esett ing) on the applicat ion command l ine, using the commandline switch comment ( / / ) as in:

MYAPP //SWAPPATH:'D:\'

This would cause CA-Clipper to create the VMM swap f i le in theroot of dr ive D, Re me mb er that for the applicat ion to be able touse 41 f i le handles, corresponding values have to be set in theCO NF IG.SY S, and , if necessary, in the appropr ia te ne two rkconfigurat ion.

E x a m p l e s This examp le i l lus t ra tes the use of BLIN KER EXE CU TA BLECLIPPER:

BLINKER EXECUTABLE CLIPPER F3 5

See Also B L I N K E R E N V I R O N M E N T C L I P P E R , B L I N K E RE N V I R O N M E N T O V E R R I D E





BUNKER EXECUTABLE NODELETE

Purpose Create .EXE regardless of unresolv ed externals

Syntax B L I N K E R E X E C U T A B L E N O D E L E T E

Descr ip t ion By defau lt, Blink er will no t create an .EXE if errors occu r. Thiscommand al lows you to overr ide that behavior, a l though theresultin g .EXE is not gua rante ed to ope rate correctly. This can beuseful during the development cycle, when not al l rout ines havebeen defined.

N o t e : At runt ime the progra m w il l fail i f an unresolved externalis called.

BLINKER LINK EMS

Purpose

Syntax

Descr ip t ion

E x a m p l e s

Speci fy l ink- time EM S mem ory use

B L I N K E R L I N K E M S O N I OFF

By defaul t , BLIN KER L INK EM S is ON . This com man d is usedto control wh ether or not EM S me m ory is used at l ink time by

the vir tual m em ory system w ithin Blinker. There is usual ly noreason to use this com m and unless a conflict with som e othersoftware is suspected. This command also sets BLINKER LINKPA G E F R A M E O F F.

This example disables EMS due to a confl ict with a TSR:

# disable EMS due to conflict with a TSRBLINKER LINK EMS OFF

See Also BLINKER LINK XMS

12-14 CA-Clipper



Blinke r C om m an d Refe rence

BLINKER LINK PAGEFRAME

Purpose

Syntax

Descr ip t ion

Examples

Specify l ink t ime pageframe use

B L I N K E R L I N K PA G E F R A M E O N I OFF

By defaul t, BLIN KER LINK PA GE FRA M E is ON . Thiscommand is used to control the use of the EMS pageframe byBlinker at l ink t ime by the vir tual mem ory system w ithin B linker.There is usual ly no reason to use this com m and unless a confl ictwith some other software is suspected.

This example disables the pageframe due to a confl ict with a disk

cache:# disable pageframe due to conflict# with a disk cacheBLINKER LINK PAGEFRAME OFF

See Also BLINKER LINK EMS

BLINKER LINK XMS

Purpose

Syntax

Descr ip t ion

Examples

Speci fy l ink-t ime XMS m em ory use

BLINKER LINK XMS ON I OFF

By defaul t , BLIN KER L INK XM S is ON . This com man d i s usedto control wh ether or not XM S m em ory is used at l ink time b ythe vir tual m em ory system w ithin Blinker. There is usual ly n oreason to use this com m and unless a confl ict with som e oth ersoftware is suspected.

This example disables XMS use:

# disable XMS useBLINKER LINK XMS OFF

See Also BLINKER LINK EMS




Blinker C o m m a n d Referen ce

BLINKER MESSAGE DUPLICATES

Purpose Enable wa rning s for duplicate mo dules within l ibraries

Syntax B L I N K E R M E S S A G E D U P L I C AT E S

Descr ip t ion By defaul t, BLIN KER M ESS AG E DU PLIC ATE S is d i sab led . Thiscommand causes Blinker to generate the 1004 l ink-t ime warningme ssage for all duplicate symbo ls encountered at link time. Thiscommand can be a very useful debugging tool for ident ifyingduplicate m odu les am ong the f iles and l ibrar ies used in l inking apro gra m . The first m od ule listed in the Blinker mess age 1004 isthe mo du le which is actual ly linked. The second mod ule in the1004 messag e is the duplicate , and is ignored un less o verr idden

wi th t he MODULE FROM command .

The fol lowing modules (and included symbols) are processed atlink time and listed in the first half of the VERBOSE output. Eachof these symbols will be listed in the generated 1004 messages ifanother processed symbol has the same name.

• All mo du les specif ied in a FILE com m and .

• Tho se mo dule s extracted from a l ibrary to resolve externalreferences.

• All mo du les within a SE AR CH ed l ibrary.

N o t e : There may be numerous dupl ica ted modules / symbols inthe included l ibrar ies which are not reported when BLINKERM ESS AG E D UP LICA TES is used , since one or bo th of themodules are not processed.

12-16 CA-Clipper




To obtain a list of all duplicated modules relevant to yourprogram by using this command in conjunct ion with theVERBOSE command :

• List all pos sible dup licates: The first half of the VE RB O SEoutput wil l ident ify al l mo dules pro cessed du ring l inking.The duplicates among these modules wil l be reported by theBLINKER MESSAGE DUPLICATES command . S ince youcan force all mod ules w ithin a l ibrary to be processed bySEARCHing that l ibrary, SEARCHing al l included l ibrar ieswil l cause all mo dule s within the prog ram to be p rocessed ,and hence cause all duplicates to be listed.

Linking w ith all these SEAR CH es is only intended toprod uce the desired duplicate mes sages, not a viable .EXE .

• Ident ify only those mo dule s used in the prog ram : Thesecond half of the VE RB OS E ou tput wil l identify only thosemodules actually included in the final executable file. Thesymbols highl ighted as duplicates whose modules appear inthe second half of the VERBOSE listing, are the ones thatshould be examined. General ly al l duplicates betweenthird-party libraries or files which are provided by the samevend or are intended and can be igno red; also thoseduplicates between a third-party product and a compilerl ibrary can be assum ed to be intended .

BUNKER MESSAGE NOBUNK

Purpose Disable display of bl inking eyes

Syntax B L I N K E R M E S S A G E N O B L I N K

Descr ip t ion By defaul t, BLIN KER M ESSA GE NO BLIN K is d i sab led . Thiscom m and is used to switch off the bl inking ey es wh ich aredisplayed while Blinker is running.




Blinker C om m an d Referen ce

BLINKER MESSAGE NOWARNING

Purpose Disable display of l ink-t ime warn ing messages

Syntax B L I N K E R M E S S A G E N O WA R N I N G

Descr ip t ion By default , BLIN KER M ESSA GE NO W AR NIN G is d isab led .This command is used to suppress the display of Blinkerl ink-t ime warning messages 1001 to 1100.

BLINKER MESSAGE WINK

Purpose

Syntax

Descr ip t ion

Examples

Enable s ingle eye wink ing du ring l inking

BLINKER MESSAGE WINK [LEFT]

This com ma nd is used to enable the winking of only one eyew hile Blinker is run ning . If no para m eter is entere d, the righteye will wink (from Blinker's point of view, i .e. , from inside thescreen looking out). The parameter LEFT causes the left eye towink.

This exam ple displays a winkin g r ight eye during l inking:

# display a winking right eyeBLINKER MESSAGE WINK

See Also B L I N K E R M E S S A G E N O B L I N K

12-18 CA-Clipper




BUNKER OVERLAY OPSIZE

Purpose

Syntax

Descr ip t ion

Examples

Request a size for the overlay pool

BLINKER OVERLAY OPSIZE <nuSize>

If the size of the overlay pool is not specified, the default size is4 0 K B . This com m an d is used to set the ope rating size of theoverlay p ool at run time in KB . It can be set to any valu ebetween 12KB and 128KB. The defaul t operat ing s ize is 40KB.This may be m ade sm aller to save m em ory or larger to red ucethe num ber of disk accesses mad e by the overlay ma nag er tore- load overlaid procedu res. W hen overlays are specif ied in the

link script file, Blinker will determine the size of the smallestpossible overlay pool by adding ap proxim ately 8K B to the s ize ofthe largest overla y unit (a segm ent for mo st com pilers) . Th isminimum value wil l be displayed along with the value specif iedin the BLINKER OVERLAY OPSIZE command. I f the minimumvalue is greater than the value specif ied, the minim um value wil loverr ide the value specif ied. The overlay opsize may beadjusted at runt ime through the use of the BLINKERenvironment variable. See the Environment Variable sect ion inthis chapter.

This example requests the size of the overlay pool to be increasedto 60Kb:

# increase the overlay pool size to 60KbBLINKER OVERLAY OPSIZE 60

See Also B L I N K E R E N V I R O N M E N T N A M E





BUNKER OVERLAY PAGEFRAME

Purpose Enable use of the EM S pagefram e for overlays

Syntax B L I N K E R O V E R L A Y PA G E F R A M E O N I OFF

Descr ip t ion Warning Please read this section fully before using thiscommand .

By defaul t , BLINKER OVERLAY PAGEFRAME is OFF. Thiscommand wil l a l low the overlay manager to ut i l ize theexpanded memory pageframe for the overlay pool (maximumsize 64KB), on machines equipped with LIM EMS (3.2 or higher)expanded m emo ry boards or emula tors .

N o t e : This comm and w il l be ignored at runt ime in the absenceof an EM S driver (or pag efram e). To use this option there mu stbe 64KB or more of avai lable expanded memory, and theprogram's overlay OPSIZE must be less than 64KB.

At runt im e, if expanded me m ory is avai lable and this opt ion isenabled , the overlay man ager wil l a l locate 4 expanded me mo rypages, map them into the pag efram e, and use the pageframe foroverlay execution. The overlay OPSIZE wil l automatical ly be

expanded to use all 64KB available in the pageframe, resulting inincreased execution speed of overlaid code.

If both this command and the UMB command are used, and boththe pageframe and a UMB are available, Blinker will use thepa gefra me in preferen ce. If either or both of these are specifiedand are not available on the end user 's system, Blinker willautomatical ly ignore these commands and al locate the overlayarea from conventional memory.

When this command is act ivated with CA-Clipper 5.3, Blinkerwil l automatical ly burn in the BADCACHE set t ing to theCLIPPER environment variable, causing CA-Clipper 5.3 to savethe pageframe mapping state between each access to expandedme mo ry. This wil l protect the overlay area in the pagefram efrom corrupt ion.

12-20 CA-Clipper




E x a m p l e s This exam ple enables the use of EM S pagefram e for overlays:

# use the EMS pageframeBLINKER OVERLAY PAGEFRAME ON

See Also B L I N K E R E N V I R O N M E N T N A M E , B L IN K E R O V E R L AY U M B

BUNKER OVERLAY THRESHOLD

Purpose

Syntax

Argument s

Description

Examples

Set size of the smallest overlaid segments

B L I N K E R O V E R L AY T H R E S H O L D <nuLimit>

<nuLimit> is a num eric value representing the size of thesmallest overlaid segments.

If the size of the smallest o verlaid segm ent is not set, the de faultsize is 32 byte s. This com m and sets the thresho ld size belo wwhich code specified to be overlaid will be moved back to theroot section of the pro gra m. Very sm all routines (less than 32bytes) take up more root space when they are overlaid, due tooverlay manager table entries, than they would if they weresimp ly left in the root. Ad dition ally, very small overlaidroutines execute disproportionately slower, since the timeoverhead in loading/cal l ing them may be large in comparisonw ith the actual execu tion tim e of the routine. If i t is the case thatvery small routines are very frequently called, the developermay wish to specify a threshold large enough to cause them to bemo ved back to the root, impro ving the perform ance of theprogram.

N o t e : This com ma nd has no effect on CA -Clipper 5.3 codeoverlaid through the paging system but could be used forexample, for C funct ions within a CA-Clipper program.

This example sets the minimum size of overlaid segments to 64bytes:

# only overlay segments larger than 64 bytesBLINKER OVERLAY THRESHOLD 64




Blinker Co m m an d Re fere nce

BLINKER OVERLAY UMB

Purpose

Syntax

Descr ip t ion

E x a m p l e s

See Also

Enable use of the XMS UMBs for overlays

B L I N K E R O V E R L AY U M B O N I OFF

By de fau l t, BLINK ER OV ERL AY U M B is ON . Th i s commandused in conjunct ion with a sui table XMS driver a l lows theBlinker overlay manager to execute overlays in upper memoryblocks above 640KB. Blinker 's use of UMBs is dependent onthere being a sui tably large cont iguou s block avai lable . The s izeof the UM B al located wil l be the same as the prog ram 's overlayopsize.

Use of this com m and requires a 386 processor (or bet ter) , and an

XM S 2 .0 ex tended m em ory dr iver tha t suppor t s UM B's (upperme mo ry b locks) . UM B's a re b locks of mem ory which a remapped into the area above 640Kb, using the memorymanagement capabi l i t ies of the 386/486 family of processors .Upper memory blocks are sometimes referred to as "highmemory" o r LOADHI a r ea s .

If your XMS driver supports the loading of dr ivers into highmemory, i t is l ikely that you can use this feature. Blinker willneed a UMB at least as large as the overlay area, so you mayneed to al ter the placement of your programs in high memory tofaci li ta te this . M ost 386 m em ory m anage rs provide ut i li t ies tohelp opt imize this area. I f both this com m and and thePAGEFRAME command are used , and both the pagef rame and aU M B are avai lable , then Blinker wil l use the pagefram e. I f e i theror both of these are specified and are not available on the enduser 's system, Blinker wil l automatical ly ignore these commandsand al locate the overlay area from conventional memory. Thisuse of UMB's may be adjusted at runt ime through the use of theBLIN KE R envi ronm ent var iab le ( see the Envi ronment Var iab lesect ion in Chap ter 2) .

This example i l lus t ra tes the use of BLINKER OVERLAY UMB:

# do not use XMS UMB's for the overlay areaBLINKER OVERLAY UMB OFF

B L I N K E R E N V I R O N M E N T N A M E , B L IN K E R O V E R L AYPA G E F R A M E

12-22 CA-Clipper



Blinker C om m an d Referenc e

BLINKER PROCEDURE DEPTH

Purpose

Syntax

Argument s

Descr ip t ion

Examples

Specify maximum depth of CA-Clipper procedure nest ing

B L I N K E R P R O C E D U R E D E P T H <nnDcpth>

<nuDepth> a num eric value represent ing the ma xim um depth ofCA-Clipper procedure nest ing.

If the maximum depth of CA-Clipper procedure nest ing is notspecified, the default is 50. This command is provided as aconvenience to CA-Clipper programmers to al low the set t ing ofthe program stack based on the maximum procedure nest ing

dep th w hich will occu r in the applica tion at runtim e. This dep this the number of procedure calls that are executed before aproced ure return. For exam ple, if proced ure A cal ls proced ure Βwh ich cal ls proced ure C, the m axim um depth is 3 . But , ifprocedure Β returns to procedure A which then cal ls procedureC, the m axi mu m dep th is 2 . The defaul t depth is 50 proced ures,but this may be increased if i t is possible for more nesting tooccu r. For instance , a recurs ive proce du re (one that calls i tself)will often require a greater depth. The size of the stack set isappro ximately lk b per 10 levels . Thu s the defaul t of 50procedures has an overhead of approximately 5kb, and this wil lr ise proport ional ly as the PROCEDURE DEPTH is increased.Since both this command and the STACK command control thesize of the application stack, only one of these commands shouldbe used (the last one specifie d is the one that is proc esse d). So m eapplications making use of third party libraries linked into theroot , especial ly in a network environment , may require anincrease in the PR OC ED UR E DEPT H. Sym ptom s indicat ing thisinclude errat ic hanging of the mac hine, spurious characters onthe screen and other fatal errors which do not happen regularly.

This example i l lustrates the use of BLINKER PROCEDUREDEPTH:

# increase stack size for 3rd party librariesBLINKER PROCEDURE DEPTH 60

See Also S TA C K




Blinker C om m an d Reference

DEFINE

Purpose

Syn tax

A rg u m e n t s

Descr ip t ion

E x a m p l e s

Specify sym bols to be exclu ded at l ink t ime

D E F I N E <symbol>[, <symbol> ...]

<symbol>[, <symbol> . ..] are the symb ols to be exclud ed at l inkt ime

The DE FINE co mm and i s used to '' s tub ou t" the nam ed symbolsand point them to a dummy rout ine in the overlay manager.Instead of including the modules containing the named symbolsin the f inal .EXE f i le , Bl inker maps each DEFINEd symbol to arout ine within the overlay manager which wil l display the

runt im e error 1213 i f the rout ine is ever cal led. This com m andcan be used (with care) to preve nt rout ines which y ou know wil lnever be cal led from being l inked in.

N o t e : In order to prevent a mo dule from bein g l inked in youmu st DEF INE al l i ts publ ic sym bols . Take care to ensure thatonly code symbols are s tubbed using DEFINE. If DEFINEd datai tems are wri t ten to , the overlay manager may be corrupted.When MIXCASE is ment ioned pr ior to any DEFINE commandsthe symbols named wil l then be processed as case sensi t ive.

This example i l lustrates the use of DEFINE:

DEFINE Alpha, Beta

See Al so M O D U L E , M A P

12-24 CA-Clipper




DEFLIB

Purpose

Syntax

Descr ip t ion

See Also

ECHO

Purpose

Syntax

A rg u m e n t s

Descr ip t ion

Use defaul t l ibrary search records

DEFLIB

The DEFLIB command is used to specify that Blinker shouldlocate and link libraries which are specified within an objectmodule. Some compilers inser t information into each generatedobject module, specifying the names of l ibrar ies which the l inkerm ay need at l ink t ime. This com m and is enabled by d efaul t .

N O D E F L I B

Display script or text on the screen

E C H O [ O N I O F F I ] [<cString>]

<cString> is the char acter string ech oed to the screen.

By defau l t , th is com m and i s OFF . EC HO <cString> causes<cString> to be echoed to the screen regardless of , and w ithou taffect ing , the EC HO s ta tus . EC HO O N <cString> turns onechoing of the script fi le to the screen, with the first l ined isp layed be ing <cString> if i t is specified . EC H O OFF turn s offechoing to the screen of the script fi le and ignores the rest of theline.

Prog ram min g a n d Uti li ties G uid e 12-25




ENDAREA

Purpose

Syntax

Descr ip t ion

Specify the end of an overlay area

E N D A R E A

The ENDAREA command is used to specify to the l inker the endof an overlay area, as descr ibed in the BE GIN AR EA sect ion.

See Also B E G I N A R E A

EXTDICTIONARY

Purpose

Syn tax

Descr ip t ion

Enable use of l ibrary extended dictionaries if they exist

E X T D I C T I O N A RY

By defau l t, EXT DIC TIO NA RY is enabled . This comm andspecifies that Blinker should use the extended dictionary that isappen ded to l ibrary fi les by som e l ibrarian ut il i ty program s. Theextended dictionary is a cross reference of the library contents,and is used by Blinker to speed up the processing of l ibraries.Not al l l ibrar ians provide an extend ed dict ionary— in this case

Blinker will process the library slightly slower than if i t werepresent.

See Also N O E X T D I C T I O N A RY

12-26 CA-Cl ipper



Blinke r Co m m an d Refe rence

FILE

Purpose Spec ify object fi le(s)

Syntax F ILE [d:][pa\h]<filename> [, [d:][path]<filename> ...]

A rg u m e n t s <filename> is the specified object fi le.

Descr ip t ion The FILE com ma nd is used to specify to the l inker the nam es ofone or more .OBJ files to be included in the output file at thatpoin t. Th e defau lt fi le exten sion of .OBJ need not be spe cified.The f i rs t f i le specif ied must be the program's main module.

Several f i lenames may be specif ied within a s ingle FILEcom m and , separated by comm as. Blinker wil l interpret acarr iage return/ l inefeed combinat ion as the end of a FILEcommand, therefore the FILE command must be restated at thebeginning of each l ine.

All f iles lis ted in FILE com m and s are included in the l inkedprogra m , wh ether they are required or not . To include only thef i les needed by the specif ic progra m , a library (.LIB) f ile sho uldbe created using a l ibrar ian such as Microsoft LIB.EXE. Thisl ibrary can then be l inked into the program using the LIBRARYcom m and , and only the required .OBJ f i les f rom the .LIB f i le wil lbe l inked to the program.

Blinker looks for each file first in the current directory and thenin each directory path specified in the OBJ environ men t v ar iablein the order they appe ar. Alter nativ ely, a full drive an ddirectory path may be specified with any or each of the filenames .

The FILE command can be used on a library file to force all the

m od ules w ithin the library to be includ ed in the .EXE . In thiscase the .LIB extension and full path will probably need to bespecif ied, e .g . FILE path\CLD.LIB. Please use this method withcaution.

Prog ram min g a n d Uti lit ies Gu ide 12-27



Blinker C o m m an d Re ference

E x a m p l e s

See Also

This example il lustrates the use of FILE:

FILE Myappl, D:\APPS\OBJ\Myapp2

LIBRARY

LIBRARY

Purpose

Syntax

A rg u m e n t s

Descr ip t ion

E x a m p l e s

Specify one or mo re program l ibrar ies

L I B R A RY [d:][path]<libname> [, [d:][path ]<//fm am e> ...]

<libname> is the na m e of the specified progra m library.

By defaul t , this command specif ies compiler def ined defaul tl ibrar ies . The L IBR AR Y com m and is used to specify to the l inkerthe name s of one or more pro gram l ibrary f i les required by theprogra m. The d efaul t f ile extension of .LIB is assum ed, and neednot be specified . If m ore than o ne library is specified in a singleLIBRARY command, each l ibrary name should be separated by acom m a. Library f iles are processed d ifferent ly from FILEcomm ands in tha t a LIBRA RY com man d causes on ly modu leswh ich are required by the progr am to be included, i .e ., mod ulesare included from a library if a public definition in the library

mo dule resolves an external reference. Object fi les nam ed inFILE commands are included regardless of whether they arerequired or not.

The LIBRARY command may be used for both root and overlaidl ibrar ies . I f the l ibrary is to be overlaid, the LIBR AR Y com ma ndshould be p laced wi th in a BEG INA REA / E ND AR EA sequence .

This example i l lustrates the use of LIBRARY:

LIB C:\LIBS\Mylibl, Myl ib2, D:\OTHER\Mylib3

See Also D E F L I B , N O D E F L I B , S E A R C H

12-28 CA-Cl ipper

http://d/APPS/OBJ/Myapp2

http://c/LIBS/Mylibl

http://d/OTHER/Mylib3

http://d/OTHER/Mylib3

http://c/LIBS/Mylibl

http://d/APPS/OBJ/Myapp2




MAP

Purpose

Syntax

A rg u m e n t s

Descr ip t ion

Examples

See Also

Request a segment map of the executable

M A P [=[d:][path]<filename>] [S][,A]

<filename> is the na m e of the M AP file of the execu table that isrequired.

By defaul t , this command is disabled. The MAP command isused to specify to the linker that a map file of the linked .EXE fileis required. The map file defaults to the same name as the .EXEfile with an extension of .MAP, or the name can be specified in

the M AP com ma nd. The map f i le can be l is ted with varyin glevels of detail , as requ ired . Th e two options to the com m an dare as fol lows: S— All segm ents— lists the addres s , length andnam e of each segm ent in the executable image. This is thedefaul t opt ion, if non e is specif ied. A— Public sy mbols inaddress order—lists the publ ic symbols and their memoryaddresses .

This example i l lustrates the use of MAP:

# generate a map of all public symbolsMAP=C:\TEMP\Mymap A

B L I N K E R M E S S A G E D U P L I C AT E S , V E R B O S E

MIXCASE

Purpose

Syntax

Descr ip t ion

Specify case sensitivity

M I X C A S E

By defaul t , MIXCASE is disabled. This command causes Blinkerto treat all publics and externals as case sensitive at l ink time,rather than convert ing them to UP PE RC AS E. This com m and isof pr im ary interest to developers using C, wh o may re quire casesensitivity.

See Also U P P E R C A S E

Prog ram ming a n d Utili ties Gu ide 12-29

http://temp/Mymap

http://temp/Mymap



Blinker C o m m a n d Refere nce

MODULE

Purpose Specify placem ent of individual l ibrary mod ules

Syn tax M O D U L E <modu le> [,<module> ...] [FR OM <libname>]

A rg u m e n t s <module> is the specified mod ule with in the library.

<libname> is the na m e of the library specified.

Descr ip t ion The M OD UL E com man d a l lows ind iv idua l modules to be forcedinto the root or the overlay area regardless of whether theoriginating libraries or object modules are specified within anoverlay area or not . The m odu le nam e refers to an object mo dule

that exists within a library which has been specified elsewhere inthe l ink scr ipt with a LIB or SE AR CH co mm and . Blinker 'sVERBOSE command output l is ts a l l modules that are processedat l ink t ime. The posi t ion of the mo dule com ma nd w ithin thel ink scr ipt determines the placement of the named modulewithin the executable; i f the MODULE command is in the rootthe named modules will be forced into the root; if i t is in theoverlay area, the nam ed m odule s wil l be overlaid. Mu lt iplemodules can be specif ied on the same command l ine separatedby a comma (,) .

The l ibrary and module names should be specif ied without pathnam es; i f included , they wil l be ignored. The VE RB OS Ecommand can be used to determine the correct module name touse , since it displays each module name as it is processed fromthe library or object mo du le. This is the same nam e as used bythe Microsoft l ibrar ian (LIB.EX E).

MODULE commands are case insensi t ive, (upper or lower casewil l be t reated the same) unless the MIXCASE command hasbeen specif ied in the scr ipt fi le before the M OD UL E com m and .

12-30 CA-Cl ipper




The MODULE command has a second mode of opera t ion ,whereby a source library is specified using the FROM <libname>option. This allows mo du les from specific libraries to be used in

preference to others , and at the same t ime performs the no rmalMODULE funct ion of changing the placement of rout ines in theroot or overlay area.

This is useful to resolve a conflict between two libraries whichcontain mod ules with the same nam e. I t is advisable to use theFROM option only when necessary, s ince i t modif ies the normall inking sequence.

E x a m p l e s • This exam ple i l lustrates the use of M O DU LE :

# Move the module COLOR to the current locationMODULE COLOR

• This example forces the mod ules DBE DIT and M EM OE DITfrom EXTEND to be used in preference to modules of thesame name which may have been found previously in otherl ibrar ies or fi les , A N D m oves those mod ules to the currentlocation in the script file:

MODULE DBEDIT, MEMOEDIT FROM EXTEND

• This exam ple forces the mo dule ME M O ED IT not to be l inkedat all , since Blinker will be looking for a l ibrary called NUL,wh ich cannot exis t . I f, how ever , som ething in M EM OE DI T isexplicitly referenced by another module, this will cause anunreso lved external . To overr ide this , use the DE FIN Ecommand ra ther than the MODULE command, and DEFINEthe publ ic symbols within the module which are unresolved:

MODULE MEMOEDIT FROM NUL

See Also B L I N K E R M E S S A G E D U P L I C AT E S , L I B R A RY

Pro gram min g a n d Uti li ties Gu ide 12-31




MURPHY

Purpose

Syntax

Descr ip t ion

Create a worst case overlay situation

M U R P H Y

The MURPHY command causes the overlay manager to at temptto force any inadvertent overlay errors (programming errors) toman ifest themselve s during test ing or debuggin g. Thiscommand is disabled by defaul t .

When MURPHY is enabled, the overlay manager wil l only al lowa single overlay to be in memory at any given time, allowing thedeveloper to detect 'badly behaved' dependencies between

overlays and correct them.

N o t e : The use of the M UR PH Y comm and may s low down theexecution of the program significantly.

NOBELL

Purpose

Syntax

Descr ip t ion

Suppress the beep upon complet ion of l ink

N O B E L L

The NOBELL command is used to specify to the l inker that nobeep is to sound w hen the l ink has completed. This comm and isdisabled by default .

12-32 CA-Clipper




NODEFLIB

Purpose

Syntax

Descr ip t ion

Ignore default l ibrary search records

N O D E F L I B

The NODEFLIB command is used to specify that Blinker shouldignore defaul t l ibrary search records which are encounteredwithin object modules . CA-Clipper inser ts information into eachgenerated object module, specifying the names of l ibrar ies whichthe linker may require . Blinker defaults to using these reco rdsunless NODEFLIB is specif ied.

See Also DEFLIB

NOEXTDICTIONARY

Purpose

Syntax

Descr ip t ion

Disable processing of extended l ibrary dict ionaries

N O E X T D I C T I O N A RY

This command specif ies that Blinker should ignore the extended

dict ionary wh ich is appe nde d to l ibrary f i les by som e l ibrar ianut i l ity progra ms . The extend ed dict ionary is a cross reference ofthe library contents, and is used by Blinker to speed up theproc essin g of l ibraries. If use of the exte nd ed diction ary isdisabled using this command, Blinker wil l process the l ibrarysl ight ly lower. Som e l ibrar ians have been know n to createinvalid extended dictionaries, which can lead to erratic results atl ink t ime—this command wil l ensure that such l ibrar ies wil l beprocesse d correct ly. This comm and appl ies global ly to alll ibraries processed during the link and is disabled by default .

See Also E X T D I C T I O N A RY

Prog ram min g a n d Uti lit ies G uid e 12-32



Blinker C om m a nd Referen ce

NOTABLEOFCONTENTS

Purpose

Syntax

Descr ip t ion

Disable processing of l ibrary table of contents

N O TA B L E O F C O N T E N T S

By defau lt , NO TA BL EO FCO NT EN TS i s d i sab led . Thiscom ma nd forces Blinker to SEA RC H all librar ies , i .e. , ignore al lthe library table of con tents. This is nece ssary for som e librariesbui l t with cer tain versions of Borland TL IB such as the BorlandC++ 4.0 l ibrar ies . Alternat ively you may SEARCH just thel ibrar ies containing the unresolved externals . This commandapplies globally to all l ibraries processed during the link.

See Also N O E X T D I C T I O N A RY

OUTPUT

Purpose

Syn tax

A rg u m e n t s

Descr ip t ion

E x a m p l e s

Specify the name of the output executable file

O U T P U T [dnve:][path]<filename>

<filename> is the na m e of the outp ut execu table file.

The OUTPUT command is used to specify to the l inker the dr ive,path and filename of the output executable file to be created bythe l inker. I f no OU TP UT com m and is used then the linker wil luse the name and path of the first object fi le appearing on a FILEcom m and in the scr ipt f i le (or on the com m and l ine) . TheO UT PU T fi le nam e extension d oes not have to be .EX E, but i f nofile extension is specified, a default of .EXE is used.

This example specifies the name of an output executable file:

# Create a linked file called OUT.EXEOUTPUT OUT.EXE

12-34 CA-Cl ipper



Blinke r C om m an d Refe ren ce

READONLY

Purpose Spe cify that the exe cutab le file will be set to read -only status.

Syn tax R E A D O N LY

Descr ip t ion By de fau l t, REA DO NL Y is d i s ab l ed . The REA DO NLY comm andcauses Blinker to create the .EXE fi le with a REA DO NL Y fi leat t r ibute . This com m and wil l be of pr ima ry interest todevelopers l inking and test ing a program over a network, as i tprevents sharing violat ions when execut ing the program fromseveral workstat ions.

N o t e : The R EA DO NL Y at t r ibute is lost i f the fi le is copied.

SEARCH

Purpose

Syntax

A rg u m e n t s

Descr ip t ion

Prioritize all symbols in the specified libraries.

SEARCH [d:][path]</*w7me> [ [d:][pa\h]<libname> ...]

<libname> is the na m e of the specified libra ry.

The SEA RC H com ma nd i s an al terna t ive form of the LIB RA RYcom m and , but operates s l ight ly different ly. Durin g the no rm all inking process , Bl inker wil l make mult iple passes over a givenlibrary until i t is unable to resolve any further externalreferences, a t which point pro cessing of the next l ibrary be gins .If, after all l ibraries have been processed, there are sti l lunresolved externals , Bl inker wil l make another pass over thelibraries and so on.

W hen Bl inker encounters a SEA RC H co m ma nd, i t loads al l thesymbol names from the named l ibrary into a table in memory.This has the effect of causing any previous un resolved externalreferences, and any future external references encountered to beresolved from the SEARCHed l ibrary ( i f they are defined there)in preferen ce to a subseq uent l ibrary. Use of the SE AR CHcommand should be l imited to those cases where i t is required,as it slows the linking process, and uses large amounts ofm em ory at l ink t ime. By defaul t , this com m and is disabled.

Pro gram min g a n d Uti lit ies Gu ide 12-35




E x a m p l e s This exam ple i l lustrates the use of SEA RC H:

SEARCHC:\LIBS\MYLIB1, D:\ABC\LIB2

See Also L IBRARY

SECTION INTO

Purpose Spe cify files to be placed in an extern al overlay

Syn tax S E C T I O N I N TO <ovlname> [FILE [d:][path]<filename>

[, [d:][path]</'ilename>...] ]

A r g u m e n t s <ovlname> is the na m e of the extern al overlay in wh ich thespecified files are to be placed.

<filename> is the na m e of the specified externa l over lay file.

Descr ip t ion By defaul t , this com m and is disabled. The SE CT ION INT Ocommand is used to specify the name of an external overlay filefor the ove rlays . Th e file m ay have any extens ion except .EXE ,and if no extens ion is specified , then .OV L is assu m ed. Th e firstSEC TIO N IN TO co mm and m ust p recede the fi rs t over laid FILE

command, otherwise an internal overlay within the OUTPUT fi lewil l be created and al l SECTION INTO commands wil l beignored.

N o t e : This com m and d oes NO T cause overlays to be created, i tmerely causes overlays (if any) to be stored external to the EXEf il e ( in OV L fi le s ). The BEGI NA RE A/E ND AR EA command s a reused to create overlays.

Once an overlay f i le has been specif ied using the SECTIONINTO command, a l l overlaid code wil l be placed in the same f i leunt i l a SECTION INTO command with a different f i le name isfoun d. At this t ime a new o verla y file will be created. Ou tputmay be spread between the overlay files by the use of multipleSEC TIO N INT O comm ands . Once an in te rna l over lay has beencreated, a l l SECTION INTOs wil l be ignored and al l overlaidproced ures w il l be s tored internal ly.

12-36 CA-Cl ipper

http://c/LIBS/MYLIB1

http://d/ABC/LIB2

http://d/ABC/LIB2

http://c/LIBS/MYLIB1




Once an external overlay has been created it is not possible tocreate an internal overlay. Blinker has a limit of 15 externaloverlays in this version.

N o t e : At pro gram run time , one file han dle is allocated to eachoverlay file, so it may be necessary to increase the number of filehandles available to the program.

Examples

See Also

This examp le i l lustrates the use of SEC TIO N INT O:

FILE MAINBEGINAREA

SECTION INTO 0VL1FILE ABC, DEF, GHISECTION INTO 0VL2FILE JKL, MNO, PQRENDAREA

B E G I N A R E A , E N D A R E A

# Placed in 0VL1

# Placed in 0VL2

STACK

Purpose

Syntax

Argument s

Description

Examples

Specify stack size of .EXE file

S TA C K <nuSize>

<nuSize> is the stack size of .EX E file.

The STACK command is used to specify to Blinker inhexad ecima l the s tack s ize in bytes required by the prog ram.EXE file.

N o t e : A preferable way of increasing the stack size, andtherefore the m axim um depth of procedure cal ls is to use theBLINKER PRO CED URE DE PTH comm and . B l inke r' s de fau l ts tack s ize when l inking CA-Clipper programs is 1400h, whichcorresponds to a PROCEDURE DEPTH of approximate ly 50 .

This example sets the stack size to 1800h:

# Set stack size to 1800h bytesSTACK 1800

See Also B L I N K E R P R O C E D U R E D E P T H





UPPERCASE

Purpose

Syntax

Descr ip t ion

Convert a l l symbols to uppercase

U P P E R C A S E

The UP PE RC AS E c om ma nd is used to specify to the linker thatal l symb ols shou ld be converted to uppercase before beingadded to the symbol table. Blinker defaults to uppercase.

See Also MIXCASE

VERBOSE

Purpose

Syntax

Descr ip t ion

Display s tatus informa tion during l inking

V E R B O S E [ 0 1 1 1 2 ]

The VERBOSE command is used to specify to the linker that i t isto display inform ation regarding the current operat ion beingperform ed. This comm and wil l s low dow n the l inking processsignificantly, but provides the developer with a means ofisolating the cau se of a link-tim e error. This com m an d isdisabled by default.

W hen V ER BO SE is specif ied, Blinker displays each objectm od ule an d the file conta ining it , as it is proc essed. This o utpu tmay be redirected to a file using standard DOS redirection ifrequired. VERBOSE's numerical parameter indicates the desiredlevel of output detail:

0 disables VERBOSE output1 outputs f i lenames while processing

2 outputs f i lenames and module names(default if no number is specified)

12-38 CA-Clipper



Blinker C om m a nd Refe rence

Examples This example i l lustrates the use of VERBOSE:

# Creates VERBOSE output, redirects to TEST.MSGBLINKER @TEST VERBOSE >TEST.MSG

See Also B L I N K E R M E S S A G E D U P L I C AT E S , M A P

WORKFILE

Purpose

Syntax

A rg u m e n t s

Descr ip t ion

Specify drive, path, and f i le name of the temporary WORKFILE

W O R K F I L E [d:][path]<filename>

<filename> is the nam e of the temp orary W OR KF ILE .

The WORKFILE command is used to specify to the l inker thedrive, path and file name of the temporary work file to use atlink time if one is requ ired. By defau lt, Blink er will use eitherXMS (2.0 or higher) or EMS (3.2 or higher) memory in preferenceto a wo rk f ile , w hen avai lable. I f no WO RK FILE com ma nd isspecified and Blinker needs to swap to disk during a link, i t willcreate a unique file in the directory specified by the TEMPenvironment variable if one exists, or the current directory if i t

does not exist.

Examples This example specifies drive, path, and file name of thetemporary work f i le "Temp":

WORKFILE C:\TEMP\Temp


http://c/TEMP/Temp

http://c/TEMP/Temp



Blinker Function Reference

Blinker Function Reference

BLIVERNUMPurpose

Syntax

Return

Descr ip t ion

E x a m p l e s

Return the Blinker version number as an integer

nuVa lue := BLIVERNUM()

Blinker version used to link the program.

This function returns an integer containing the version numberof Blinker used to l ink the prog ram . The num ber representsmajor version * 100 + minor version, e.g., 100 represents Blinkerfor CA-Clipper 5.3 version 1.00.

This example i l lustrates the use of BLIVERNUM:

* BLIVERNUM()*? "The Blinker version nu mber is "?? STR (BLIVERNUM()/10 0 , 4, 2)

12-40 CA-Clipper



Chapter 13

CA-Clipper Debugger—CLD.LIB


Once you have f inished wri t ing a program, you must test i t tom ake sure there are no errors. Th e com piler and linker w ill spot

some errors that you can correct without having to actuallyexecute the program, but it is not at all unusual for a program tocontain errors which you can detect only wh ile the program isrunnin g. Exam ples of this type of error are runt im e andexecution errors , cosm etic and other display errors , and logicerrors. It is with this type of error that a deb ug ger co m es inhandy.

CA-Clipper offers two methods for debugging an applicat ion,the Workbench debugger, and the DOS-level debugger,CLD.LIB.

The easiest and more user-fr iendly method for debugging anapplicat ion is to use the Workbench debugger, which places al lthe debugging tools within an easy-to-use GUI environment .At the touch of a but ton, the Workbench debugger al lows youto:

• Con trol the execution of your applicat ion

• Evalua te and trace expression s

• Set, reset, and clear brea kp oin ts

• View and mo dify variables

• Create wa tch expression s, and mu ch mo re




In This C ha pt er

This chapter documents the DOS-level debugger only, with anoccasional reference to the equivalent Workbench debuggerfunct ion so that you can compare the two debugging methods.For complete detai ls on how to use the Workbench debugger, see

the Workbench User G uide.

As i ts nam e sugg ests , a debugger tool helps you track down andremove errors from your source code. CA-Clipper 's DOS-leveldebu gger (referred to more s imply as the debugger througho utthis chapter) is a source code debugger which means that i ta l lows you to view your source code while your program isrunning . You use the debu gger to execute your application sothat you can switch back and forth between running the programand view ing the source code to spot potential problem areas.

The debugger provides you with certain features that make i teasier to isolate and identify errors. Among these features arethe ability to:

• Trac e sour ce cod e line-by-lin e (single step m od e)

• W atch a variab le as it is up date d (watch poin t)

• Mo nitor variables by s torage class

• Inspect w ork areas and set valu es

• Ch ang e the value of a variable

• Crea te new variables and cha nge the value s of existing ones

• Execute proced ures and user-defined funct ions l inked intoyour applicat ion

• Stop prog ram execution w hen a variable changes value(tracepoint)

• Stop prog ram execution at a l ine of code or wh en a funct ionis called (breakpoint)

13-2 CA-Clipper



In This C ha p te r

When you execute your applicat ion using the debugger, a l l ofthese features and more are available to you so that you cant ight ly control how your applicat ion runs and keep an eye on

things as it doe s. In this m an ne r, you can quick ly and eas ilyidentify errors in your source code.

Whenever you not ice an error, s imply edi t the code, recompile ,and rel ink, a l though you m ust perform these s teps outside thecontext of the debu gger. You m ay need to repeat thisdebug/edi t /compi le / l ink cyc le severa l t imes i f your programhas a lot of errors.

This chapter documents the debugger command l ine syntax andits various modes of operat ion, describes the debugger displayincluding al l windows and menus that you wil l encounter,explains how to debug a program using the debugger, and offersa complete menu command reference. These major topics arecovered:

• Star t ing the debu gger

• The debu gger display

• Debugg ing a program

• Men u com ma nd reference

Prog ram min g a n d Utilit ies G uide 13-3



Start ing the De bug ger

Starting the D eb ug ge r

In order to debug an application, you must first create anexecutable file (.EXE) using the compiler option for debugging.You can then invoke the debugger and begin the debuggingsession. Som e parts of your applicat ion ma y require source codechanges in order to be properly debugged.

Preparing Your Programs for De bu gg ing

To take full advantage of the features offered by the debugger,there are certain things that yo u sho uld consider. Som eprogramming pract ices inhibi t the debugging process whileothers require the kno wle dge of special debugger features . Also,there are a couple of compiler options that you need to knowabout before you can debug a prog ram . This sect ion discussesspecial programming, debugging, and compil ing issues that youneed to consider before at tempting to debug you r ap plicat ion.See the "Debugging Your Applicat ion" chapter of the WorkbenchUser Guide for the equivalent information co ncerning theWorkbench debugger.

Programming Cons ide ra t ions

Certain parts of your cod e present special problems wh endebu gging. This sect ion explains the techniques for debug gingmu lt is tatement c om ma nd l ines, head er f i les , code blocks, andmacros.

Multistatement Lines CA -Clipp er al lows you to place mo re than one programstatement on a single line. For example:

nNewPa ge := (nLineNo > 5 5 ) ; ReportPage(n NewPage)

When you use the Up arrow or Down arrow in the debuggerCode window, the cursor moves up and down one complete l ineat a time. This is true regardless of ho w m any statem ents are onthe line in que stion. In the abo ve exam ple , the deb ugg er doesnot allow you to step through the first and second statementsindependently nor does it allow you to set a breakpoint at eitherstatem ent. Th e entire line is treated as a single entity.

13-4 CA-Clipper



Start ing the De bug ge r

The code in the above example should be broken up into twolines, as follows:

nNewPage : = (nLineNo > 55)ReportPage(nNewPage)

This makes debugging easier and also makes the code morereadable.

Header Files H ead er files are files that are referen ced usin g the #inc lud epreprocessor direct ive. They typical ly contain manifest constantand pseudofunct ion defini t ions. The debugger does notautomatical ly display header f i les in the Code window, but youcan view them with the Fi le Open command.

Code Blocks A code block contains executable prog ram code that is t reated byCA-Clipper as data and can be passed as a parameter to otherprog ram s. Inspect ing a code block in the debu gger reveals onlyits name, not the actual code.

However, code blocks can be executed from within thedebu gger. The fol lowing com m and , wh en entered in theCommand window, causes the code b lock bMyBlock to beevalua ted. An y code within bMyBlock is execu ted and the resultsare displayed accordingly:

? EVAL(bMyBlock)

In addit ion to al lowin g you to execute code blocks interact ively,the debugger also traces code blocks back to their definition aslong as Op tions Codeb lock is on. W hen using s ingle s tep mo deto execute a piece of code con taining a code block, the debu ggermo ves the execution bar to the l ine of code w here the block w ascreated each t ime the code block is evalua ted. This al lows you tosee the contents of the block (which are unavai lable duringnormal inspect ion) and occurs regardless of whether the blockw as declared in the current rout ine.

Macro Substi tution The debu gger t reats ma cros as ordinary character s t r ings. Assuch, they can be inspected or viewed using the ? I ?? command.For exam ple :

? &macroVar

displays the contents of the expanded macro variable macroVar.





C o m p i l i n g Yo ur S o u r c e C o d e

To debug an applicat ion, you must compile with the /B opt ionor, f rom the Workbench, check Debug Information in the

Com piler Option s dialog box . This instructs the com piler toinclu de debu gg ing inform ation in the object file (.OBJ). Forexample :

CLIPPER MainProg /B

In this exam ple, a l l prog ram s cal led by M ainprog .prg are alsocompiled with debugging information.

If , however, you use a (.clp) f ile or com pile each program in yourapplicat ion separately, you must specify that debugging

inform ation be includ ed for each f i le every t ime you invo ke thecompiler. During the debugging session, any subsidiaryprograms which have been compiled without this opt ion areignored.

In addit ion, you must compile without the /L o ption or, from theWorkbench, uncheck Suppress Line Number in Obj in theCompiler Options dialog box. Effect ive debugging is notpossible without line numbers in the .OBJ file.

Finally, if you use any of the preprocessor directives, and areinterested in viewing the preprocessor output while debugging,you should use the /P opt ion, or check Generate PPO File in theCompiler Options dialog box from the Workbench.

As their nam e sug gests , preprocessor direct ives are instruct ionsto the pre pro cesso r that do not exist at run time . This mea ns, forexample, that you cannot inspect #define constants andpseudofunct ions in the same way as other expressions when youare debugging.

If you compile a program using the /P (or Generate PPO File)com piler op t ion, a fi le with a (.ppo) extension is prod uced. Thisf i le shows the preprocessor output which can be viewed usingthe Options Preprocessed command. With this command, thedebugger displays each l ine of source code in the Code windowwith the output from the preprocessor shown underneath.

13-6 CA-Clipper



Start ing the Debugger

Important In order to use the debugger, your application must becompiled with CA-Clipper with IB options.

Invoking the Deb ugge r

There are several way s to invoke the deb ugg er, each of wh ich isdiscussed below . All of the me thod s require that the applicat ionbe compi led wi th /B and without / L (or, f rom the W ork ben ch,wi th Debug Informat ion checked and Suppress Line Nu mb ers inObj unchecked in the Com pi le r Opt ions d ia log box )— debu ggingis not possible otherw ise.

From DOS

To invoke the debugger from the DOS prompt for real modeapplicat ions, use the fol lowing syntax:

CLDR [[/43 I /50 | /S /D] [®<scriptFile>]<exeFile> [<argument list>]]

CL DR .LIB is the real m ode deb ugg er l ibrary. I f you instal led theCA-Clipper development system using the defaul t configurat ion,

CL D.L IB is located in the\CLIP53\BIN directory and your DOSPATH should be al tered accordingly.

/43 I ISO I IS specif ies the screen mode used by the debugger.These three opt ions are mu tual ly exclusive an d, i f m ore than oneis specified, CLDR.LIB uses the last one that occurs on thecom m and l ine. The defaul t screen m od e is 25 l ines, with thedebu gger u sing the ent ire screen.

14 3 specif ies 43-l ine mod e and is avai lable on EG A mo nitorsonly.

/SO specif ies 50-line mo de and is avai lable on EG A and VG Amonitors only.

/D specif ies that the debug ger screen wil l have focu s and theapplicat ion w il l be sus pen ded , ready to execute the fi rs t l ine ofcode.

Progra mm ing an d Utilities G uid e 13- 7

http://clip53/BIN

http://clip53/BIN




/S is avai lable on EG A and VG A mon itors only. This opt ionspl i ts the screen betw een y our applicat ion and the d ebugg er,al lowing you to view the applicat ion and the debuggersimultaneously.

On a VGA monitor /S uses 50-l ine mode, and on an EGAm onit or it uses 43-line m od e. In split screen mo de , the top 25lines of the screen are used by your application, and therema ining l ines are used for the debugger display.

If the /D option is not used, execution of the application willbegin im me diately. At this point , to invoke the debug ger, youma y use the A lt+ D keystroke . I f the / D option is used, thesource code associated with the <exeFile> app ears in the cod e

window, and you can begin running and debugging yourapplicat ion.

<scriptFile> is the na m e of a script file w ith a defau lt extensio n of(.eld). CL D R searches for the specified <scriptFile> in the currentdirecto ry then search es the D O S PAT H . A script file is simp ly anASCII text f i le containing one or more debugger commands,with each command appearing on a separate l ine. When thedebu gger is invok ed w ith a scr ipt f i le, each com m and in the f i leis executed automatical ly af ter the <exeFile> file is load ed. SeeUsing a Script File later in this chapter for more information onthis subject.

In addit ion to any scr ipt f i le cal led for on the CLD R com m andline, the debugger automatically searches for a script file with thena m e Init .cld. If a file by this nam e is located in the currentdirectory or anywhere in the DOS PATH, the debugger executesit as a script file. If bo th Init .cld and a com m an d line script fileare present, Init .cld is executed first , followed by the commandline script file.

<exeFile> is the na m e of the execu table (.EXE) file you wa nt todebug. CLDR searches for the <exeFile> in the curren t directoryonly— the D OS PA TH is not searched. As s tated earlier, the fi lemust include debugging information and l ine numbers.

<argument list> is the argument list for <exeFile>. There mu st bea space between <exeFile> and <argument list>.

13-8 CA-Clipper



Star ting the De bug ge r

No te that with the exception of the argum ent l is t , a l l other C LD Rarguments must come before the executable f i lename on thecommand l ine .

If no command l ine arguments are specif ied, CLD displays abrief help screen.

U n k i n g t h e D e b u g g e r

For protected mode applicat ions, you must l ink the debuggerinto you r applicat ion. Doin g this wo uld al low you, for exam ple,to debug a program at a customer's site in the event that an

unforeseen problem occurred af ter the applicat ion was alreadyin the field.

To includ e the debugge r as part of your applicat ion, thedebugger l ibrary, CLD.LIB, must be l inked into your program asan object file (not as a library file) as in the following examplewhich uses the protected-mode l inker:

EXOSPACE FI MainProg, CLD.LIB

N o t e : Real mod e applicat ions can also use the l inked deb ugg er.

Instead of using CLD.LIB, the protected mode debug l ibrary, useCLD R.LIB for rea l mo de debugging .

When debugging an applicat ion with an integrated debugger,real or protected mode, the environment variable,CLIPPERDEBUG, may be used to spec i fy "command l ine"argu me nt switches. The switches avai lable are discussed here insome detai l .

Cont ro l ling Execu t ion o f Ap p l i c a t io n— /D or / d

Instead of the applicat ion beginning execution immediately, asis norm al , the debu gger screen w il l have focu s and theapplication will be suspended, ready to execute the first l ine ofcode. The /D or /d switch can be used in conjunct ion with thescreen mode switches, fol lowing.




Starting the Debugger

Permi t t ing Concur ren t Viewing o f App l i ca t ion and Debug Sc reens—/S o r / s

The /S or /s opt ion, avai lable with EGA and VGA adapters ,perm its the applicat ion and d ebug screens to be v iew edconcurrent ly by part i t ioning the maximum l ines supportedbetween the applicat ion and the debugger.

Set t ing scr een l ines— /4(3)

If supported by the adapter, /4[3] sets screen lines to 43.

Set t ing scr een l ines— /5(0)

If supported by the adapter, /5[0] sets screen lines to 50.

N o t e : The screen m od e switches are mu tually exclus ive, the lastof one or mo re wil l predo min ate.

Again, your program must be compiled with debugginginformation and l ine num bers present . W hen the debug ger isl inked into a prog ram in this man ner, i t does not come upautom atical ly when yo u run your applicat ion. Instead, i t mu st

be invoked with Alt+D.

N o t e : I f you del iver your applicat ion with the debug ger l inkedas an object file, you should also include the help file, CLD.HLP,located in \CLIP53\BIN in the defau lt installation. W hen y ouask for help, the debugger searches the current directoryfol lowed by al l directories in the DO S PAT H. If CL D.H LP is notfound in any of these locat ions, the debugger wil l promp t yo ufor a directory na m e. If CL D .H LP is still not foun d, you will nothave access to help text within the debugger.

13-10 CA-Clipper

http://clip53/BIN

http://clip53/BIN




From Windows

You can also invoke CL D from within the W orkbe nch. To do so,s imply compile your applicat ion with debugging information bychecking the Debug Information opt ion on the Compiler Optionsdialog box . You m ust also include CLD .LIB in the Add it ionalOb ject Files edit contro l of the Linke r Op tion s dialog box . O nceyour application is successfully built , simply run the application.This creates a DOS window with CLD act ive. You can thenact ivate the debugger using Alt+D or ALTDQ, as discussedbelow.

In order to use the Workbench debugger, you must choose the

Deb ug men u's Run option. For mo re inform ation, please seethe "Debugging Your Applicat ions" chapter in the WorkbenchUser Guide.

Invoking wi th Al t+D

W hen an applicat ion is l inked with CL D.LIB as one of the objectfiles, the debu gger is enabled an d can be invok ed by pressingAl t+D w hile the application is running. Doin g this invokes thedebu gger w ith the execution bar posi t ioned on the current l ine ofexecuting code.

You can also use Alt+D when the debugger is invoked with theCLD command l ine. When executing the applicat ion in runmo de, s imply press Alt +D at any t ime to terminate theapplicat ion and return control to the debug ger. Run m ode is oneof the man y execution m odes that is avai lable to you w hen youdebu g an applicat ion using the debu gger. For mo re inform ationon mo des of execution, see Deb ugg ing a Pro gram later in thischapter.





Using ALTD()

The AL TD () funct ion serves two purp oses: it a l lows you tocontrol whether the debugger is enabled or disabled, and itallow s you to invoke the deb ug ger if i t is enab led. AL TD () canbe used regardless of whether the debugger is invoked using theCLD co mm and l ine or us ing Al t+D .

When i t appears in a program compiled with debugginginformation, ALTD() used without arguments acts l ike abreakpoint by stopping the application and giving control to thedebugger.

ALTD(O) temporarily disables the debugger so that any code

following the function call is executed as if the debugger was notpresent.

W hen the debu gger is disabled, a ll breakpo ints and tracepointsare ignored and even cal ls to ALTD() and pressing Alt+D wil lnot invoke the debu gger.

A LT D (l) is used to enable the debug ger once i t has beendisab led. N ote that the defau lt state is enab led for progra m scompiled with debugging information.

For applicat ions that are l inked with C LD .LIB, you can u seAL TD () to prevent the user from inadvertent ly invoking thedeb ugg er. By inclu ding cod e simila r to the follow ing at thebeginning of the main program, the ability to invoke thedebug ger is control led by the presence of a comm and l ineparameter:

PARAMETERS dBug

IF dBug = NILALTD(l) // Invoke debugger with ALTD() or Alt+D

ELSE

ALTD(0) // Debugger cannot be invokedENDIF

13-12 CA-Clipper




Using the previous code, the debugger is disabled unless theapplicat ion is invoked w ith an argum ent . Even though theprogram may contain cal ls to ALTD() and the user may pressA l t + D , the debugger cann ot be invoked unless the applicat ioncom ma nd l ine argum ent is specif ied. I f your applicat ion acceptsother arguments , use dBug as the last one in the list.

How the Debugger Searches for Files

W hen y ou m ake a f i le open request to the debugger, you canspecify the drive, directory, and file extension explicitly as partof the f i lename. Othe rwise, the debugger ma kes certain

assum ptions abou t the f i lename and locat ion.

Depending on the context of the file open request, the default fileextension supplied by the debug ger varies . For exam ple, w henthe request is for a script file the debugger assumes a (.eld)extension and for a preprocessed output file the defaultextensio n is ( .ppo). Def ault file exten sions are supp lied on lywhen you do not specify an explicit file extension.

If no explicit file location is specified or if the file location cannotbe obtained from the application, the debugger looks for the filein the current directory . The n, with the exception of the .EXEfile, the debugger searches the DO S PAT H . Only af ter theselocations are exhausted will an error message be displayedindicating that the file could not be found.

Important The debugger searches for the executable file in thecurrent directory only.




Start ing the Deb ugg er

Using a Script File

The debugger allows you to record commands in a script file andexecute the commands directly from the file. A script file issim ply an AS CII text file. The file consists of one or mo redebugger commands, with each command on a separate l ine,and has a default extension of (.eld).

Some programs may requi re severa l debug/edi t /compi le / l inkcycles in order to trace persistent errors. Reco rding repetitivecommands in a script file eliminates the amount of typingnecessary to reach the same position in your application eacht ime.

For example, the following script file sets a breakpoint at the firstcall to the function ViewData(), designates the variablesIMadeChanges and ISaveChanges as w atchp oints, and specifiesnFieldNum and nFileArea as tracepo ints:

BP ViewDataPoint Watchpoint IMadeChangesPoint Watchpoint ISaveChangesPoint Tracepoint nFieldNumPoint Tracepoint nFileArea

Another advantage to using script files is to record preferred

debugger settings so that you do not have to set them each timeyou debug.

The easiest way to record option settings in a script file is to setthem using the debug ger menu s. Then, use the Options Sav ecommand as in the fol lowing example:

Options Save MyScript

The script file, Myscript.cld, is saved to disk and can be used ormo dified at any time . The settings that you can save in this w ay

include most Op tions men u set t ings, the Mon itor menu set tings,and case sensitivity and call stack status.

13-14 CA-Clipper



Star t ing the Debugger

As an alternative to setting the options and saving them to ascript file using the Options menu, you can type the appropriatemenu commands direct ly into a scr ipt f i le . Menu commands are

formed using the menu name fol lowed by the f i rs t word of themen u option you want to set. Any necessary argum ents areplaced at the end of the command.

An example of some menu commands recorded in a scr ipt f i lefollows:

View CallstackMonitor LocalOptions Codeblock

When the debugger is active, you can execute a script file withthe Options Restore command as in the fol lowing example:Options Restore MyScript

You can also execute a scr ipt f ile from the debugger com ma ndline as in the following example:

CLD @MyScript MainProg

Each time the debugger is invoked, it automatically searches fora script file w ith the nam e Init.cld . If a file by this nam e islocated in the current directory or anywh ere in the DOS PA TH ,the debu gge r execu tes it as a script file. If both Init .cld and acommand line script file are present, Init .cld is executed first ,followed by the command line script file.




Start ing the Deb ugg er

Getting Help

The debugger offers online help in the form of a Help windowthat is divided into two panes: the left pane contains a list of

topics for which help is available, and the right pane contains thehelp text for the currently highlighted topic.

Yo u can activate the H elp win do w three way s. The first is byusing the Help com m and . The second is by cl icking Fl-H elp onthe function k ey line at the bo ttom of the screen. The third is bysimply pressing Fl .

There are several main topics of discussion in the Help windowincluding Abou t Help , Keys , W indow s, Menu s , and Co mm ands .

When the Help window is first activated, one of these topics ishigh lighted on the left , and the text on the right discusses thetopic.

To get help on a particular topic, highlight it using the Up arrowor D ow n arrow or by clicking on it . As you mo ve the highlight,the associated help text on the right changes to reflect the currenttopic.

If the indicator at the bottom right of the window shows morethan one page of information, use PgUp and PgDn to scroll thehelp text.

To remove the Help window and continue debugging, press Esc.

For more information on the Help window, see The DebuggerDisplay later in this chapter.

Leaving the Deb ugger

When you have finished your debugging session, enter the FileExit command or s imply press Alt+X. The debuggerautomatically closes all files and returns.

13-16 CA-Clipper



The De bu gg er Display

The Debugger Display

Before you can make ful l use of the debugger, you must befamil iar with the various windows, menus, and keys on whichthe debugging environment is based.

See "Debugging Your Appl ica t ion" in the Workbench User Gu idefor detai ls on its win dow s, menu s, and keys. You can alsoaccess the Workbench's onl ine Help system for moreinformation.

The Debugger Menus

The fol lowing sect ion contains a descr ipt ion of the menusavai lable in the debugger and how to access and execute opt ionsin those men us. Specif ic information on the operat ion ofindividual men u opt ions, how ever , is not discussed here. Referto the Menu Command Reference at the end of this chapter formore detai led information on how menu opt ions work.

The Menu Bar

M e n u b a r

M enu select ions appear on the me nu bar at the top of the screen.Each menu contains a group of s imilar, commonly used opt ions.For example, the Find, Next , Previous, Goto Line, and CaseSensi t ive opt ions are found on the Locate menu:

Run Toint fbnitor Options Window Help

0) Secondfunc <wp, U>: undefined

• C:ÎP53\mCI\CALLSTftC.FRG -• H u hFUMCTIOM ThirdFuncDO SecondProcRETURMCMIL)

PROCEDURE SecondProcFinalFuncC)

RE UMI

FUNCTION FinalFuncALTDC)

RETURM(MIL)mmComand -




Although each of the opt ions has an associated command thatperforms the same funct ion ( in the above example: Locate Find,Locate Next , Locate Previous, Locate Goto, and Locate Case) , themenu system provides a quick way for the beginner to learn how

to use the deb ugger.

Th e Fi le men u lets you view other f iles and access DO S withoutleaving the current program.

The L ocate me nu lets you search for a s t r ing in a program andmove the cursor in the Code window to a par t icular l ine number.

N o t e : I f the Co m m and w ind ow is act ive wh en a Locate men uoption is selected, you will not see the cursor move to its newlocat ion in the Cod e win dow . You mu st select the Cod e win dowin order to see the new cursor position in the file.

Th e View m enu lets you view certain information that is notnorm ally displayed as par t of the debugger screen.

The Run menu lets you run the current appl icat ion using one ofseveral debugger execut ion m ode s. Ad dit ional ly, i t le ts youcontrol how m uch of the appl icat ion to run using the C odewindow cursor and restar t the current appl icat ion from thebeginning.

Th e Point men u al lows you to set and delete break points ,watchpoints , and t racepoints .

Th e Mo nitor m enu lets you control the display of publ ic , pr ivate ,s ta t ic , and local var iables in the Monitor win dow .

The Options menu lets you control the debugger display opt ionsand create and run debugger script fi les.

The Window menu lets you perform certain window operat ions,including s izing and moving the act ive window.

The Help men u lets you act ivate the Help wind ow. The m enuoptions select the help topic that is initially highlighted when thewindow is opened .




M e n u O p e r a t i o n s

Access ing a Menu

Selec t ing a MenuOpt ion

To access a menu, click on it , or hold down the Alt key and press

the first letter of the m en u nam e. For exam ple, to access theView m enu, p ress Al t+V .

Whenever a menu is displayed on the screen, any menu on themenu bar can be accessed.

• To access the m en u to the right of the curren t on e, pressRigh t arrow . If you are position ed on the last m en u, thecursor wraps around to the f i rs t menu on the menu bar.

• To access the m enu to the left of the curre nt on e, press Leftarrow . If you are position ed on the first m en u, the curs orwraps around to the last menu on the menu bar.

• To close the current m enu , press Esc or c l ick anyw hereoutside of the menu.

The fol lowing table summarizes the keys discussed in thissection:

Key A c t i o n

Alt+<Firs t le t ter> Activate designated menu

Lef t a r row/Ct r l+S Activate menu to left; wrap if on first

R igh t a r row/Ct r l+D Activate menu to right; wrap if on last

Esc Close menu

To select an option from an open menu, either click on it , or:

1. Press Up or Do wn arrow to highl ight the opt ion.

2. Press Enter to select the option and close the m enu .

Prog ram min g a n d Uti li ties Gu ide 13-19




W hen select ing a me nu op t ion, pressing Up arrow on the f i rstoption causes the highlight bar to wrap around to the last option;the reverse is true if you press Down arrow on the last option.The following table lists the active keys within a menu:

Key Act ion

<Option le t ter> Select designated option

Enter Select highlighted option

Up a r row/Ct r l+E Move up one option; wrap if on first

Down a r row /C t r l+X Move down one option; wrap if on last

Ac celera tor Keys On ce a me nu is open, a l l opt ions within the me nu have anassociated accelerator key that you can press to select the option.The accelerator key is a single letter which is usually the firstletter of the option name.

Within a menu, the accelerator key for each option is highlightedin the option na m e. Typ ing the indicated key is equiv alent tohighlighting that option and pressing Enter. For example, if theFile menu is open, pressing X selects the Exit option.

Shortcut Keys In add ition to accelerator key s, m any options also hav e anassociated shortcut key that allows you to select the optionwithou t f i rs t openin g its associated menu. These keynam esappear to the right of the option name in the menu.

For example, to select File Exit using its shortcut, press Alt+X.

All shortcut and accelerator key equivalents are documented inthe Menu Command Reference at the end this chapter.

13-20 CA-Clipper




M e n u C o m m a n d s

Any menu opt ion can be turned into a command that can be

executed from the Command window or from a scr ipt f i le .These commands, cal led menu commands, are formed using themen u n am e fol lowed by the f irs t word of the option n am e.

For examp le, to execute the Mon itor Public menu opt ion type:

Monitor Public

Arguments can be specif ied fol lowing a menu command if theme nu opt ion requires fur ther input . For exam ple, select ing RunSpeed prompts you for the step delay using a dialog box.

To specify a delay speed of .5 seconds using a menu com m and :

Run Speed 5

Menu commands can usual ly be abbreviated down to one le t terper word, but in some cases a second or third letter is required inthe option keyword to distinguish it from another option thatbegins with the same letter(s).

For instance, instead of Run Speed 5 you can type:

R Sp 5

The abbreviat ion "Sp" dis t inguishes Run Speed from the RunStep command.

All of the debugger commands are documented in detail in theMenu Command Reference at the end of this chapter.





The Function Keys

Many of the function keys used in the debugger are shortcuts tousing a me nu select ion or com ma nd. For exam ple, using F9 toset a breakpoint is slightly easier than selecting the PointBreakpoint menu opt ion and much easier than enter ing theappropriate BP or Delete com ma nd . The fol lowing table shows alist of all the available function keys and their actions:

Key Ac t ion

F l Help

F2 Ful l-screen /w in do w toggle

F3 Retype last com ma ndF4 View appl icat ion screen

F5 Exec ute application

Ctr l+F5 Execute until next activation

F6 View Wo rkareas window

F7 Execute application to cursor

F8 Execute application in single step mode

F9 Se t /d e le te breakpoin t

F10 Trace

The function key assignments are displayed on the function keyline at the bo ttom o f the screen. Th ey can be selected by simplyclicking on them.

For details on all of the Workbench function keys, access theWorkbench onl ine Help system.

13-22 CA-Cl ipper



The De bu gge r Display

The Debug ger Windows

The de bugg er display is based on a ser ies of windo ws, each with

a uniqu e purpose. The fol lowing table gives the name and abrief descr ipt ion of each of these win dow s:

Wi n d o w N a m e P u r po s e

Calls tack Display the list of pending activations

Code Display program code

C o m m a n d Display commands and their resul ts

Help Display help information

M onitor Display mo nitored variables

Set Colors Display and modify color settings

View Sets Display and modify system set t ings

View Workareas Display work area and (.dbf) information

W atch Display watch points and t racepoints

The Workbench also provides the same funct ional i ty in i ts

poin t and click env iron m ent. For details on setting colors seethe "Working in the Workbench" chapter of the Workbench UserGuide. Th e "De bug gin g You r Ap plicat ion s" chapter has detailson the other topics.

Pro gram min g a n d Uti lit ies Gu ide 13 21




Wi n d o w O p e r a t i o n s

This sect ion descr ibes the general behavior of win dow s thatappear on the main debugger screen ( that is , Code, Command,

Monitor, Watch, and Cal ls tack) , including s izing and movingbetween windows. The instruct ions regarding select ing menuoptions are intentionally generic—use the method that best suityour needs, be it clicking the option with the mouse, pressing theappropriate accelerator, shortcut, or function key, or entering theequiva len t command in the Command window.

N o t e : The remain ing window s, Help , View Sets , ViewW orkare as, and Set Colors , are not par t of the main debu ggerdisplay. W hen you ope n one of these win dow s, you enter amode in which the window takes control of the screen andnorm al debu gger operat ion is temporari ly suspen ded . W henyou are f inished with the win dow , you must c lose i t before y oucan continue deb ugg ing. Th e opera tions in this section do notapply to these modal windows.

For detai ls on the Workbench window operat ions, seeWorkbench Basics in the "Working in the Workbench" chapterof the Workbench User G uide.

Navigating Betw een Of all the wi nd ow s on the m ain screen , one is said to be the

Windows active wi nd ow and the rest are inactive. W hen you select awin dow , you make i t the act ive wind ow. The act ive win dow isindicated by a highl ighted border; inact ive windows have asingle- line b order.

• To select a wi nd ow on the screen , click any wh ere on it withthe mouse.

• To select the next w ind ow on the screen , press Tab .

• To select the previous win dow , press Shif t+T ab.

W hen a win dow is act ive, keystrokes affect only that window .For example, when the Monitor window is act ive, pressingDown arrow moves the highlight bar to the next variable in thelist of monitored variables but does not affect the cursor orhighl ight bar in any other window.

13-24 CA-Clipper




The ex cept ion to this rule is that a com m and can be typed andexecuted from any active window . For exam ple if you type "L istBP" while the Code window is act ive, the command wil l appear

in the Co m m and w indo w as you are typing. As soon as youpress Enter, the command wil l be executed and the resul td i sp layed in the Com ma nd w indow . Fur thermore , Enter a lwaysexecutes the com ma nd pend ing in the Com m and w indow ( ifany) , taking precedence over the normal operat ion of the Enterkey for the act ive window.

Ope n ing a nd C los ing Not al l debu gger win do ws mu st be open on the debu gger screenat a l l t imes. The deb ugge r automatical ly controls the open ingand closing of cer tain win dow s, while leaving the control ofothers up to you. This sect ion descr ibes how to open and closeeach window.

The Code and Command windows are a lways open and cannotbe closed by you or the debugger.

The debugger au tomat ical ly opens the W atch window wh enthere are t racepoints and/or watchpoints def ined. When al lt racepoint and watchpoint def ini t ions are deleted, the debuggercloses this window.

The debugger au tomat ica lly opens the Mo ni tor windo w wh enone or mo re variable classes is being m onitored . W hen there areno monitored variables , the debugger closes this window.

You control opening and closing of the Cal ls tack window usingthe View Cal l s tack com man d.

Pro gram min g a n d Util it ies G uid e 13-25




Iconizing A ny w ind ow on the screen can be effectively put out of sightwithou t actually closing the win dow . For example, if theCallstack window is open and you are not interested in itscontents for the moment, you can shrink it down so small that

only the window name is vis ible .

To iconize a win do w, cl ick the Dow n arrow at the top r ight-handcorner of the window, or :

1. Select the win dow .

2. Ch oose the W indo w Iconize m enu opt ion.

The active window is replaced by an icon (its name) so thatyou can no longer see its contents.

When a window is iconized, cer tain window operat ions, such assizing, are not available.

To return an iconized win dow to view , double-click the icon, or :

1. Select the iconized win dow .

2. Ch oose the W indo w Iconize m enu opt ion.

The window is restored.

Zooming W ind ow s can be zoom ed to ful l -screen in order to view more

information at one t ime.

To zoom a window to full-screen, click on the up arrow at thetop r ight-hand corner of the window, or :

1. Select the win dow .

2. Choose the W indow Zoo m me nu opt ion .

To return a zoom ed w indo w to i ts or iginal wind ow display, c lickthe restore arrow at the top right-hand corner of the window, or:

1. Se lect the zoom ed wind ow.2. Choose the W indow Zoom men u opt ion .

When a window is zoomed, other window operat ions such asmoving and s izing are not a l lowed.

13-26 CA-Clipper




Sizing Th e heigh t and wid th of all de bu gge r wi nd ow s is dete rm ined bythe display mode and those windows current ly open. The s ize ofa window, however, can be changed to sui t your part icularneeds .

To s ize a window, press and hold the lef t mouse but ton on thewindow's lower r ight-hand corner while dragging the mouse, or :

1. Select the win dow you wan t to s ize.

2. Cho ose the W indo w Size m enu opt ion.

The border of the window changes to a different pat tern toindicate that size mode is active.

3. Use the Direct ion keys to s ize the win do w.4. Press Enter to com plete the sizing.

The following table lists some shortcut keys for changing theheight of a window:

Key Act ion

Al t+G Grow act ive window by one l ine

Al t+S Shrink act ive window by one l ine

Al t+D Shr ink Command window by one l ine

Al t+U Grow Command window by one l ine

N o t e : You canno t s ize a win dow that is zoom ed to ful l -screenusing these Alt+key combinat ions.





Moving The locat ion of a ll debu gger win dow s is determ ined by thedisplay mode and which windows are open at any given t imeand can be chan ged to sui t your part icular need s.

To move a window, press and hold the lef t mouse but tonanywhere on the window's border, except a scrol l bar or thesizing area, while dragging the mouse, or :

1. Select the win dow you wan t to m ove.

2. Choose the W indow Move men u opt ion .

The bord er of the win dow change s to a different pat tern toindicate that move mode is act ive.

3. Use the Direct ion keys to m ove the win dow to the desired

screen location.4. Press Enter to com plete the mo ve process .

N o t e : You cann ot move a win dow that is zoom ed to ful l -screen.

Tiling The W ind ow Tile com ma nd is a quick wa y to clean up thescreen. This com m and restores each windo w on the screen to itsdefaul t locat ion and s ize. Any windows that have been zoomedor iconized are also restored to the original window displaymode .

To t i le the debugger windows, choose the Window Tile menuoption.

13-28 CA-Cl ipper




T he C o d e W i n d o w

C o d ew i n d o w "

The Code window is initially located underneath the menu bar

and is used to d i sp lay program cod e and header (.ch) files.Preprocessed output can be displayed beneath prog ram cod e ona line-by-line basis using the Opt ions Preprocessed com ma nd.The name of the fi le curren tly bein g disp layed is shown at thetop of the Code wind ow .

File Locate View Rum Po i nt Hon i tor Opt ions Window Help"

C:\CLIP53VS0UnCEN3imENTBDOl)l .PnGLOCAL oColLOCAL GetListLOCAL nKeyLOCAL nLenLOCAL 1AppendLOCAL bSauIns

358: LOCAL nSauRecNo := recnoOLOCAL xnewKeyLOCAL xSauKey

// If we're at EOF we're adding the first record, so turn on append moif EO FQ

- Command

usamThe Code window is initially set to display a cer tain number ofl ines but can be sized to display few er or more l ines (seeW indow Opera t ions ear l ie r in this chap ter for mo re inform ation) .The min imum number of displa y lines is ze ro , and the initial andm a x i m u m n u m b e r of lines depen d on the display mo de.

A scroll b ar appears o n the right side of the Code window whenthere is too mu ch code to see at once. Using the mouse , you canscroll:

• Line-by-l ine by c l icking on the Up and Dow n ar rows

• Screen-by-screen by c l icking the area abo ve or be low thescroll box

• Through a percentage of the co de b y clicking an d d raggingthe scroll box to the locat ion you wan t to v iew

Programming a n d Utilities G ui de 13 29




Inside the Code window is a highlight bar called the executionbar which is positioned on the line of code about to be executed.The execution bar mo ves as execution continues.

W hen the Code w indo w is act ive, the cursor appears in thewindow to indicate your current position in the file beingview ed. Initially the curso r and executio n bar app ear on thesame l ine, but the cursor can be mo ved up and do wn u sing theDirec tion key s. The curso r is used to show the result of Locatecommands, to mark (or delete) a line of code as a breakpoint,and to tel l the Run To com m and wh ere to s top.

To navigate w ithin the Code w ind ow , click on a source l ine orthe scroll bar, or use the keys shown in the following table:

Key Act ion

Up a r row /C t r l+E Move cursor up one l ine

D o w n a r r o w / C t r l + X Move cursor down one l ine

Le f t a r row/Ct r l+S Pan left one character

R igh t a r row/Ct r l+D Pan right one character

H o m e / C t r l + A Pan left one screen

En d/ Ct r l+ F Pan r igh t one screen

P g U p / C t r l + R Scrol l window contents up

P g D n / C t r l + C Scrol l window contents down

Ct r l+PgUp Move cursor to first l ine

Ctr l+PgDn Move cursor to last l ine

Enter Execute pending com man d

Tab Activate next window

Shif t+T ab Activate previous win dow

F2 Togg le ful l -screen /w in do w displayF3 Retype last command in command history

For detai ls on viewing the applicat ion code using the W orkbench ,see The Module Browser in the "Browsing Applicat ions, Modules,and En ti t ies" chapter of the Workbench User Guide.

13-30 CA-Clipper




Th e C o m m a n d W i n do w

C o m m a n d _w i n d o w

The Command window, ini t ial ly displayed at the bottom of thescreen, show s the debu gger com ma nd s that you enter. Theoutput of debugger commands (if any) is also displayed in thiswindow direct ly underneath the command.

File Locate Uiew Bun Point Monitor Options Window Ήεΐρ

0) nkey <wp, Local, U>: MIL

1) lflag <wp, Local, L>: .T.

- fetch •

ciNXiiPsassouncEsafmzsTBDatn.FnGftLTDO

// Lazy man'β error checkingbSaueHandler := errorblockC < x break(x) > )

BEGIN SEQUENCEuse (dbf) index (index)

RECOUER USING oErrorif C oError:genCode == EG_OPEN )

7? "Error opening file(s)"

> goto 56

> bp

• Comand «

SSI

The Command window is l ike most other debugger windows inthat it can be sized, moved, and zoomed to full-screen when it isthe active windo w (see W indo w O perat ions earl ier in thischapter for mo re inform ation).

Note , however, that the Command window does not have to beact ive in order to enter com ma nd s. Co m m an ds are entered inthe same manner no matter what window happens to be act iveat the t ime. To execute a com m an d, type the com ma nd andpress Enter or m ake the equivalent m enu selection.

The only difference between these two methods of command

execution is that commands you type appear in the Commandwin dow and are, therefore, avai lable in the com m and historybuffer discussed below—not so with menu select ions.

See the Menu Command Reference at the end of this chapter foran alphabetical l is t of debu gger com m and s. See The Deb ugg erMenus later in this chapter for a brief description of each of thedebugger menus and information regarding i ts use.





The fol low ing table gives a summ ary of keys that are avai lablewhen the Command window is ac t ive :

Key A c t i o nU p a r r o w / C t r l + E M ove cu rsor to previous l ine in

command h is tory

D o w n a r r o w / C t r l + X Move cursor to next l ine in commandhistory

Left arrow /C tr l +S M ove cursor one character to the left

R igh t a r row/Ct r l+D Move cursor one character to the right

H o m e / C t r l + A M ove cursor to the beginnin g of l ine

E n d / C t r l + F Move cursor to the end of line

Inser t / Ct r l+V Toggle the insert mode on or off

D e l e t e / C t r l + G Delete character under cursor

Bac ksp ace / C trl+ H De lete char acter to the left of cursor

Esc Clear command l ine

Enter Execute pending command

Tab Activate next win dowShif t+Tab Act iva te previous wind ow

F2 Toggle fu l l - screen/w indow disp lay

F3 Retype las t com man d in comm andhistory

13-32 CA-Clipper




History Co m m and s that you type are saved in a his tory buffer wh erethey can be accessed when the Command window is act ive.

T o execute a command in the his tory buffer :

1. Se lec t the Com ma nd wind ow .

2. Press Up arrow unti l the desired com ma nd app ears .

3. Press Enter to execute the com m and .

T o chan ge a com m and in the his tory buffer before executing i t:

1. Se lec t the Co mm and wind ow .

2. Press Up or Dow n arrow unti l the desired comm andappears .

3. Edi t the com ma nd to sui t you r needs.

4. Press Enter to execute the edi ted comm and .

Overwrite and Insert W hen the Co m m and w indo w is act ive, there are two data entryM o d e s m ode s: overw ri te and insert.

T o toggle between overwri te and insert modes:

1. Se lec t the Co mm and wind ow .

2. Press Insert.

The cursor chan ges to indicate the current mod e.

Overwri te mode ( the defaul t) is indicated by the underscorecursor. In this mo de, new characters that you type o verw ri teexist ing characters , causing one cha racter to be deleted for eac hcharacter typed.

Insert mo de is indicated by the block cursor. In this mo de, n ew

characters that you type are inserted to the right of the cursor,pushing existing characters to the right.





T he W a t c h Wi n d o w

The W atch w ind ow is ini t ia l ly displayed at the top of the screen,undernea th the menu bar and above the Code w indow . I tappears whenever a watchpoint or t racepoint is created.

Wa t c hw i n d o w

In this window, the number and name of each watchpoint andtracepoint is displayed along w ith i ts data type, value, andstorage class (for example, local) . Watchpoints and tracepointsare d is t inguished us ing the abbrevia t ions "w p " and " tp ."

fie Locate Uiew Ruin Point Hon it r Options Window Help

0) nkey <wp, Local, U>: MIL

1) If lag <wp, Local, L>: ,T.:>^LIP53NS0UhtSsSnmESlBDEMDl .PH6

ALTD Ο

// Lazy man's error checkingbSaueHandler := errorblockC { x break(x) > )

BEGIΜ SEQUENCEuse (db f ) index ( inde x)

RECOUER USING oErrorif C oError:genCode == EG_OPEN )

?? "Error opening file(sD"

Comand :

> goto 56> bp

Tracepoints and watchpoints are created using the PointTracep oint and Point W atchpo int com ma nds , respect ively. Toremove a point defini t ion, use the Point Delete command orpress Delete when the point is highl ighted in the Watch window.

When the Watch window is act ive, you can inspect the value ofalmost any variable or expression that appears in the window.Code blocks cannot be inspected, and inspect ing arrays andobjects is s l ightly mo re com plicated than other data types.

13-34 CA-Clipper




To inspect an array or object:

1. Select the W atch win dow .

2. Click on the array or object you wan t to inspec t, or press U por Down arrow to highlight it .

3. Press Enter to view the item in a dialog box.

The dialog box shows an iconic representation of the array orobject.

To inspect array elements or object instance variables:

1. Press Enter again.

An other dialog box opens in which the individual array orobject components can be viewed and changed.

2. Click on the elemen t you want to chan ge, or press Up orDown arrow to highlight it .

3. Press Enter to enter edit m od e, or simp ly type a new v alue .

4. Press Esc twice to close both dialog bo xes.

All changes that you have ma de are saved and controlreturns to the Watch window.

To inspect other data types:

1. Select the W atch win dow .

2. Click on the variab le you are interested in, or press Up orDown arrow to highlight it .

3. Press Enter to view the valu e in a dialog box.

4. Press Enter to enter edit m od e, or simp ly type a new v alue .

5. Press Enter to accep t the cha ng es or Esc to aban don th em .

The dialog box closes and control returns to the W atch win do w.

Program ming an d Utilities Gu ide 13 -3 5




The fol lowing table summarizes the keys that are avai lable whenthe Watch window is act ive:

Key Act ion

U p a r r o w / C t r l + E Move highl ight bar up one l ine

Dow n a rrow /C t r l+ X Move highl ight bar down one l ine


Pg D n/C tr l+ C Scro ll windo w contents down

Ctrl+ Pg Up M ove highl ight bar to f i rs t l ine

Ctr l+ Pg Dn M ove highl ight bar to last l ine

Enter Execute pending com man d or changeselected item

Tab Activate next win dow

Shif t+Tab Act iva te previous wind ow

Delete Delete current ly highl ighted watch pointor tracepoint

F2 Toggle fu l l - screen/w indow disp lay

For specif ics on using watchpoints with the Workbenchdebugger, see Using Watch Expressions in the ' 'DebuggingYour Applicat ions" chapter of the Workbench User G uide.

13-36 CA-Clipper



The De bu gg er D isplay

The Moni to r Window

The Monitor window is s imilar to the Watch window except that

it is used to monitor variables of a particular storage class ratherthan variables that are set as w atch po ints and tracepoin ts. Th eMonitor window appears on the screen only when one or moreof the storage classes in the Monitor menu is turned on(indicated by a checkmark next to the s torage class menuoption) .

Monitored variables relate to the program current ly displayed inthe Co de win do w. This is t rue regardless of wh ether theprogram is the current activation or a pending activation that is

being viewed using the Calls tack w indo w. The values displayedfor monitored variables are the values they held when theroutine in the Code window was act ive. Furthermore, the onlyvariables displayed in the Monitor window are those that arevisible to the rout ine in the Co de w indo w.

N o t e : Inspect ing monitored variables with the ? I ?? commandor specifying them as wa tchpo ints or t racepoints yields thecurrent value, which may be different from the value displayedin the Monitor window.

To m onitor a part icular s torage class (or s top m onitoring on e) ,use the associated Monitor command (for example, MonitorLoc al for local variables ). Each variab le na m e that is bein gmonitored is displayed along with its storage class, data type,and value.

By defaul t , the variables are grouped by storage class . I f Mo nitorSort is on ( indicated by a checkm ark besid e the Monitor Sortmenu option) , variables are l is ted in the Monitor window inalphabet ical order by variable name.

Pro gram m ing a nd Utilit ies G uid e 13-37




When the Monitor window is act ive, you can change the value ofalmost any variable in the window by highl ight ing i t andpres sing Enter. Editin g varia bles in this w ind ow is identical tothe method described above for the Watch window and with the

same exceptions—code blocks cannot be edi ted, and edi t ingarray values and objects is s l ight ly mo re comp licated than otherdata types.

The keys for this window are summarized in the table below:

Key A c t i o n

U p a r r o w / C t r l + E Move highl ight bar up one l ine

D o w n a r r o w / C t r l + X Move highl ight bar down one l ine



Ctrl +P gU p M ove highl ight bar to f i rs t l ine

Ct r l+PgDn Move highlight bar to last l ine

Enter Execute pending command or changeselected i tem

Tab Act iva te next window

Shif t+Tab Act iva te previous wind ow

F2 Toggle fu l l - screen/w indo w disp lay

You can monitor variables easi ly using the Workbenchdebu gger. For detai ls , see Evalu at ing Expressions and ViewingLocal and Private Variables in the "Debugging YourAp pl ica t ions" chap ter of the Workbench User Guide.

13-38 CA-Clipper




The Ca l l s t a ck W indow

The Callstack window initially appears on the right side of the

screen and contains the na m es of all pen din g activations. Th islist is called the call stack. Th e current activa tion is alw ays at thetop of the call stack.

I File Locate Uiew Hum Point Monitor Options Window Help• C:NCLIr53^H;I \DHiJ5i i€ . ITC •

RETURN(NIL)

PROCEDURE SecondProcFinalFuncORETURN

FUNCTION FinalFuncALTD Ο

: ? "we are at the deepest part of the callstack"RETURNCNILJ

- Corawnd

•WlWfrtrf lTI

Calls tack window

To view a pending activation in the call stack:

1. Ch oose the View Calls tack m enu option.

2. Select the Calls tack win dow .

Click the activation you are interested in, or press Up orDown arrow to highlight it .

The Code, Monitor, and Watch windows are updated toreflect the highlighted activation.

To return to the current activation, either highlight it or close theCalls tack window using the View Calls tack command.





The following is a list of keys available when the Callstackwindow is act ive:

Key Act ion

Up a r row /C t r l+E Move highl ight bar up one l ine

Down a r row /C t r l+X Move highl ight bar down one l ine



Ct r l+PgUp Move highlight bar to first l ine

Ct r l+PgDn Move highlight bar to last l ine

Enter Execute pending command

Tab Activate next win dow

Shif t+Tab Act iva te previous windo w

F2 Toggle fu l l - screen/window disp lay

You can view the cal l stack information easi ly wh en using theW orkb ench d ebug ger. For detai ls , see View ing the Call Stackin the "Deb ugg ing Y our Ap pl ica t ions" chapter of the Workbench

User Guide.

13-40 CA-Clipper




The He lp Window

The debugger offers onl ine help in the form of a Help window,w hic h is divid ed into tw o pa nes: the left pa ne contain s a list oftopics for which help is available, and the right pane contains thehelp text for the currently highlighted topic. You can activate theHelp window by select ing a specif ic choice on the Help menuusing the keyboard or mouse, pressing Fl , or enter ing the Helpcommand .

There are several main topics of discussion in the Help window,and when the window is first activated, one of these topics ishighlighted on the left with its associated help text displayed onthe r ight . The fol lowing table summ arizes the keys used tonavigate within the Help window:

Key Act ion

Up ar ro w /C tr l+ E M ove h ighl ight bar up one l ine

Dow n ar row /C tr l+ X M ove h ighl ight bar dow n one l ine



Esc Leave Help window

Prog ram m ing a n d Utilit ies Gu ide 13-41




In addition to an index of help topics and details on how to usethe Help system , the W orkb ench p rovides context-sensit ivehelp for all of its w ind ow s. To access He lp, press Fl or click onthe Help menu while working anywhere in the Workbench.

The View Sets Window

When the View Sets window is act ive, you can view and changethe status of the CA-Clipper system settings.

To change a system set t ing using the View Sets window:

1. Cho ose the View Sets me nu option.

2. Click on the setting you wa nt to chan ge, or press Up orDown arrow to highlight it .

3. Press Enter to enter edit m od e, or simp ly type a new v aluenext to the setting.

4. Press Enter to com plete the editing process and m ove on tothe next setting .

5. Do uble -click on the w ind ow close icon in the upp er leftcorner of the window, or press Esc to close the View Sets

windo w and cont inue debugging .

When you close the View Sets window, the new set t ings aresaved and take effect imm ediately in your pro gram .

To set system op tions using the Workb ench, see Sett ing SystemOptions in the "Working in the Workbench" chapter of theWorkbench User Guide.

13-42 CA-Clipper




T he Vi e w W o r k a r e a s Wi n d o w

The View Wo rkareas windo w a l lows you to v iew da tabase (.dbf)and other wo rk area informa tion. The wind ow is divided intothree panes cal led Area , Status, and Structure.

To act ivate the View Workareas window, cl ick on ViewWorkareas, or press F6 to execute the View Workareascom man d. Once the windo w is open:

• To move to the next win dow p ane , cl ick on i t , or press Tab.

• To m ove to the previous wind ow pan e, cl ick on i t, or pressShi f t+Tab.

• To mo ve the highl ight up or dow n within the currentwind ow p ane , press Up or Dow n ar row .

The Area pane display s the al ias nam e for each open databa sefile w ith the active file high lighte d. Inform ation rega rding th ecurrent ly highl ighted f i le is show n in the other two win do wpanes.

The Status pane shows the current database driver name and thestatus of most wor k area f lag set tings with information regarding

the selected database f i le unde rneath. The database inform ationis in the form of an out l ine that can be expa nded and col lapse d.

To expand or collapse an entry in the Status pane:

1. Click on the entry , or press Up or D ow n arrow to high ligh t it .

2. Press Enter .

Enter acts as a toggle, expanding the entry if i t is collapsed andcollap sing it if i t is exp and ed. For instanc e, high light Cu rren t

Record and press Enter. The f ield values usual ly displayedund erneath d isappear. Press Enter again, and the f ield valu esreappear.

The Structure pane lists the structure of the selected databasefile.





To close the View Workareas window and continue debugging,double-cl ick o n the windo w close icon in the upper lef t-handcorner of the w indo w , or press Esc.

The Workbench debugger provides you with the abi l i ty to viewwork areas too. Viewing Work Areas in the "Debugging YourApplicat ions" chapter of the Workbench User Guide explainshow to view work areas in detail .

The Set Colors Window

When the Set Colors window is act ive, you can view and changethe status of the debugger color settings.

To chang e a color set t ing using the Set Colors w indo w :

1. Cho ose the Op tions Colors me nu option.

2. Click on the color setting you w ant to cha nge , or press Up orDown arrow to highl ight i t .

3. Press Enter to enter edi t m od e, or s imply type a new valuenext to the setting.

Each set t ing is a foreground/background color s t r ing

enclosed in double quotes (see SETCOLOR() in the ReferenceGuide for a list of colors).

4. Press Enter to com plete the editing proce ss and m ove on tothe next setting .

5. Dou ble-cl ick on the w ind ow close icon in the upp er lef t -handcorner of the window, or press Esc to close the Set Colorswindow and cont inue debugging .

W hen you close the Set Colors w ind ow , the new colors takeeffect immediately but will be lost as soon as you exit thedeb ug ger. To save the new colors in a script file for future us e,execute the Options Save command.

To customize your Source Code Editor window when using theW orkbenc h, see Select ing Source Cod e Editor Colors in the"W orking in the W orkb ench " chapter of the Workbench UserGuide.

13-44 CA-Cl ipper




Dialog Boxes

Several menu options and window select ions require that youenter fur ther information into a dialog box before continuing.Menu options that require more input are always indicated by anellipsis (. . .) to the right of the option name. Some examples ofwindow select ions that require addit ional information are i temsin the Monitor and Watch windows.

Dialog boxes are also used i f you enter an incomplete command.For example, Locate Find with no search s tr ing opens a dialogbox to ask for the search string.

Dialogbox

18: DO SecondProc19. RETURNCNIL)20: j p n |

: PfiQCEPUJT22: FinalFun23: RETURN24:25: FUNCTION FinalFunc

mEwammmm ,,27: ? TJe ore at the deepest part of the callstack28: RETURNCNIL)29:3Θ:31:32:33: Demand *

> locate find





The fol lowing table summarizes the keys that are avai lable whena dialog box is open:

Key Act ion

Lef t a r row /C t r l+ S Move cursor one character to the left

R igh t a r row/Ct r l+D Move cursor one character to the right

H o m e / C t r l + A Move cursor to the beginning of line

E n d / C t r l + F Move cursor to the end of line

Inse r t /C t r l+V Toggle the insert mode on or off

De le te /Ct r l+G Dele te character under cursor

Bac kspa ce / C trl+ H De lete charac ter to the left of cursor

Esc Close dialog box without executing

Enter Execute and close dialog box

Debugging α Program

In order to make full use of the information presented so far inthis chapter, this section provides a more detailed study of themo st powerfu l features , together with suggest ions on the mo stappropriate places to use them .

When you are told how to accomplish a particular task, thissect ion often refers to the debugger co mm and withoutmentioning any of its shortcuts, such as a function keyequivalent . Keep in mind, howe ver, that there are almost alw aysmenu and key equivalents that you can use to make debuggercommand execution easier. The Debugger Display sect ion

earl ier in this chapter describes how com man ds are formed fromme nu options and discusses key equivalents . You can also usethe Menu Command Reference at the end of this chapter to lookup any command and quickly see i ts key equivalents .

13-46 CA-Clipper



Debugg ing α P rogram

Executing Program Code

The most basic function of a debugger is to execute an

application and display the results. This section describes thevarious w ays to run a prog ram an d explains how to control thespeed and view the output .

Modes o f Execu t ion

The debugger provides several different ways to execute aprog ram , cal led execution m ode s. The fol lowing table l ists eachof these modes together with the command and/or funct ion key

that is used to access the mode:

E x e c u t i o n M o d e C o m m a n d / F u n c t i o n K e y

Animate Run Animate

Run Run Go , F5

Run Next Run Next , Ctr l+F5

Run to Cursor Run To, F7

Single Step Run Step, F8

Trace Run Trace, F10

For the execution commands avai lable with the Workbenchdebugger, see Execution Com ma nds in the "Debu gging YourApplicat ions" chapter of the Workbench User Guide.

Animate M ode To run a progra m in animate m od e, use the Run An imatecom m and ( there is no funct ion key equivalent) . This execu tionmode al lows you to execute large port ions of an applicat ion,s topping w hen the value of a suspect variable or exp ression

changes.

In animate mode, the debugger executes the l ine of codecurrent ly highl ighted by the execution bar, moves the executionbar to the next l ine of code, and con tinues execu ting sequential lyin this manner until i t reaches a breakpoint or a tracepoint.

Prog ram ming an d Utilit ies Gu ide 13-47




When a program is executing in animate mode, you canvoluntar i ly terminate the program at any t ime by pressingAlt+D, assuming this key has not been disabled with ALTD(O).Do ing this returns control to the debugger w here the exe cution

bar will be positioned on the next line of code to be executed.

The Options Exchange command controls whether the debuggerdisplays program ou tput . By defaul t Options Exchang e is on,causing the debugger to display the output of each line of codeafter it is executed.

The Run Speed command controls the speed at which animatemode executes .

Run M ode Ru n mo de is the fastest mo de of execution offered by thedebu gger. In this mo de, the debu gger runs your applicat ion inmu ch the sam e manne r as i t wo uld in animate mod e. Thedifference between these two execution modes is that run modedoes not return to the debugger display after each line of code isexecuted.

If you hav e not set any breakp oints or t racepoints , wh en youexecute an application in run mode the application runs just as ifyou had executed i t witho ut using the debugger. The onlydifference is that when the application terminates, i t returnscontrol to the debugger rather than the operating system.

If you have set breakpoints or tracepoints, the application runsuntil i t reaches one then returns control to the debugger.

When a program is executing in run mode, you can voluntar i lyterminate the program at any t ime by pressing Alt+D, assumingthis key has not been disabled with ALTD(O). Doing this returnscontrol to the debu gger w here the execution bar wil l beposi t ioned on the next l ine of code to be executed.

The re are three version s of run mo de . The first is the onedescribed above which you enter by pressing F5 or selecting theRun Go comm and .

13-48 CA-Clipper



D e b u g g i n g α P r o g r a m

The second is identical to the first except that the debugger runsthe application only until the start of the next activation. Thismode is accessed by pressing Ctrl+F5 or selecting the Run Next

command and is equivalent to setting a tracepoint ofPROCLINE() = 0 .

The third is identical to the first except that the debugger runsthe application only to the current cursor position in the Codewin dow rather than to the applicat ion 's end. This mode isaccessed by pressing F7 or select ing the Run To c om ma nd.

Single Step Mode To run a pro gram in single step m od e, press F8 or select the Ru nStep command. This execution mode al lows you to s tep througheach l ine of code, viewing the output and exa mining variables asyou go. Ideally, you will use single step mode in situationswh ere the error you are looking for has been narrowed dow n toa few lines of code.

In single step mode, the debugger executes the line of programcode highl ighted by the execution bar, mo ves the execution barto the next line of code to be executed, and stops. As functionsare called by the current program, the debugger displays thefunct ion code in the Code window.

If a code block is evaluated when executing a program in singlestep mode, the debugger moves the execution bar to the line ofcod e wh ere the block w as created. This allows you to see thecontents of the block (which are unavailable during normalinspect ion) , and occurs regardless of wh ether the block w asdecla red in the current routine . Press F8 again to mo ve past thecode block definition to the next executable line.

You can control this behavior by select ing the Option s Co deblo ckcom ma nd. By defaul t , Options Code block is on and code blocktracing is ena bled . Turn Op tions Cod eblo ck off if you prefer notto view the code block definition.

Trace Mode To run a pro gram in trace m od e, press F10 or select the Ru nTrace com ma nd. This execution mod e is s imilar to s ingle s tepmode in that i t allows you to execute one line of program code ata t ime. Ho we ver, t race mod e does not display the code forfunct ions and procedures cal led by the current program nor doesit trace code blocks back to their definition.





Finding Program Errors

As you hav e already seen, the debugg er provides several way sto execute a progra m. The metho d you use depend s on how far

you have progressed in your debugging effort . The fol lowingsections explain three common debugging stages and suggest anappropriate m ethod for each stage.

Starting Out Th e easie st w ay to de bu g a pr og ram for the first time is toexecute the application in run mode to show the program outputin the context of the application. Yo u will use the Run Gocommand (or s imply press F5) to invoke run mode.

Simple runt im e errors can be ident if ied using run mo de. W hen aruntime error is encountered, control is automatically returnedto the debug ger w here yo u can see the offending line of code. Aruntime error normally causes the application to terminateprem aturely because continued execu tion is prohibi ted by theerror. Thus, you usually have to correct the error, recompile,and rel ink before you can continue debugging.

Cosmetic errors, such as mistakes in screen design, can also beidentified in run mode, but it usually is not necessary to correctthem before continuing since they do not affect the actualexec ution of the pro gram . As soon as you notice a cosm etic

error, press Alt +D to invoke the debugger and m ake note of thecode that needs to be changed.

After you have identified and noted all cosmetic errors, you willprobably want to go ahead and edit your source code to makethe nece ssary corrections. The n you mu st com pile and link theapplication again so that the changes will take effect the nextt ime you execute.

Note that all source code changes must take place outside of the

context of the debugger (that is, you must leave the debugger tomake them) since the debugger has no facility for correctingerrors on-the-fly.

For more complex problems such as mistakes in program logic orother runtime errors that do not have an obvious solution,continue to the next stage of debugging.

13-50 CA-Clipper



D e b u g g i n g α P r o g r a m

Taking a Closer Look W hen the cause of a pro blem is not imm edia tely obv iou s, thenext step is to examine the contents of suspected fields, variables,and expressio ns. Ofte n, you can use the ? I ?? command to reveal

an unexp ected valu e for one of these item s. If this is the case,specify the item as a wa tchpo int or tracepoin t. This allows y outo pinpoint exactly where in the application the erroneous valuewas s tored.

If you suspect that several variables in a particular storage classmay be at fault , use the options on the Monitor menu to displaythese variables in the Mo nitor wind ow . For exam ple, to displayprivate variables , select the Mo nitor Private comm and . As y oucontinue your debugging session, the private variables visible tothe rout ine displayed in the Code window are updated in theMoni tor window.

After set t ing up the necessary watchpo ints and tracepoints , u sethe Run Animate command to run the program slowly,displaying the code for each l ine executed (animate mod e). Usethe Run Speed c om ma nd to control the speed of the display.

Continue this process until the problem has been confined to afew lines of cod e. N ow it is t ime to m ov e on to the final stage.

Final Stag e W hen the cause of an error has been narrowed dow n to a fewlines of code, move the cursor in the Code window to the first ofthese lines and use the F9 key or the Point Breakpoint commandto set a break poi nt there. The n press F5 to exe cute theapplication in run mode up to that breakpoint.

When you have reached the suspect area of code, press F8 to stepthrough the code one line at a time (single step mode). If you arecertain that the error is in the current program and not in anysubsidiary proced ures or funct ions, use F10 instead ( t race m ode ).Remember that in t race mode the debugger does not display thecode for called routines.

Prog ram min g a n d Uti lit ies G uid e 13-51




Executing your application in single step or trace mode whilewatching the values of the items in the Watch window is usuallysufficient to unc ove r the cause of a prob lem . Ha ving don e that,simply alter your code, recompile, relink, and begin searching

for the next error.

You can easily set breakpoints then run your application fromthe debug ger whe n using the Wo rkbench . For detai ls , seeResolving Runtime Errors in the "Debugging YourApplicat ions" chapter of the Workbench User G uide.

Vi e w i n g P r o g r a m O u t p u t

There may be times when you want to look at the output of apro gram rather than the cod e. To do this, press F4, the functionkey equivalent for View App. When you do, the debuggererases the screen and displays the current output exactly as theperson running the application will see it . Press any key toreturn to the debugger display.

Alternat ively, you can view program output fol lowing executionof each individual line of code by running the application inanimate mode (using the Run Animate command) with OptionsExchange turned on.

13-52 CA-Cl ipper




Inspecting Data and Expressions

One of the most common uses for a debugger is examining

(inspect ing) and al ter ing the values of var iables and expressions.The debugger provides several ways to do this , each of which isexplained in the fol lowing sect ions.

Using the Workbench, you can inspect and modify the valuesof expression s quickly and easi ly. For detai ls , see ResolvingRunt ime Errors in the "Deb uggin g Your Ap pl ica t ions" chap terof the Workbench User Guide.

Using Watch po in t s an d Tracepo in t s

Watchpoints and t racepoints are two of the most valuablefeatures of the debu gger. The y al low you to exam ine f ie lds ,variables , and more complex expressions and to pinpoint exact lywh ere in your appl icat ion their values chang e. This sect ion givesa defini t ion of watchpoints and t racepoints and explains howthey are set , deleted , and insp ected.

Definition of A watch point is an expression wh ose current value is displaye dWatchpo in t s and in the W atch win dow . The value or each watch point is

Tracepoints upd ated as your appl icat ion executes .

A tracepoint is s imilar to a watchpoint ; however, whenever i tsvalue changes, program execut ion pauses and control passes tothe deb ugg er. In this respect, a tracep oint is similar to abreakpoint .

Prog ram min g a n d Uti li ties Gu ide 13-52




To set watchpoints and t racepoints use the Point Watchpointand Point Tracep oint m enu comm and s. I f you choose themenu opt ions, the debugger opens a dialog box where you are

prompted to enter an expression.

If you use the Point Watchpoint or Point Tracepoint commands,you can specify the expression on the command line as in thefol lowing examples:

Point Watchpoint nPageNumPoint Tracepoint nlnvNum = 1000

In either case, the debug ger creates the watchp oint or t racepointand displays i t in the Watch window, together with i ts type,va lue , and the abbrev ia t ion "wp" or " tp . "

Dele t ing W atchpo in t s To delete an individual watchpo int or t racepoint , use the Pointand Tracepoints Delete m enu opt ion. W hen the dialog box appe ars , enter the

number that appears on the far lef t -hand s ide of the Watchwindow.

Alternat ively, you can use the Point Delete command andspecify the watchpoint or t racepoint number on the commandline or s imp ly highl ight the point in the Watch w indo w andpress Delete . N o matter which meth od you use, the specified

entry is removed from the Watch window and the numbers of a l lthe remaining entr ies are updated.

To delete al l wa tchpoin ts an d t racepoints , use the Deletecommand as fo l lows:

Delete All WP

Note that s ince Delete does not dis t inguish between watchpointsand t racepoints , you could have used Delete All TP just aseffectively.

Warning Be careful not to use Delete All on its own unless you wantto delete all watchpoints, tracepoints, and breakpoints.

Set t ing Watchpointsand Tracepoints

13-54 CA-Cl ipper




Listing W atchp oints Yo u can alw ay s see wa tchp oint s and tracep oints in the W atchan d Tracepoints w ind ow as long as it is ope n. You can also displa y them in the

Command window us ing the Lis t command:List WP

No te that s ince List does not dis t inguish between watch pointsand t racepoints , you could have used List TP just as effect ively.

InspectingWatchpoints andTracepoints

To inspect a watchpoint or t racepoint and change i ts value,select the W atch win dow . Then , mo ve the highl ight bar to thei tem you wish to inspect and press Enter. The current value ofthe expression is displayed in a dialog box. Within the dialog

box, you can ei ther enter a new value a nd press En ter or pressEsc to leave the variable as i t is.

Note that a l though you can inspect the value of a lmost anyexpression that appears in the Watch window, code blockscanno t be inspected, and inspect ing arrays and objects is s l ight lymore complicated than other data types.

When you are f inished inspect ing i tems in the Watch window,you can select anothe r win dow . For more information on thekeys used to navigate the Watch window and for specif icinstruct ions on inspect ing arrays and objects , see The DebuggerDisplay earlier in this chapter.





C r e a t i n g N e w Va r i a b l e s

W hen y ou enter " ? " fol lowed by an expression, the expression isevaluated and the return value displayed in the Command

win dow . This is a useful feature that a l lows you to executepro ced ures and function s linked into you r app lication. It alsoal lows you to mak e inl ine assignmen ts to change exis tingvariables or create new one s, wh ich can be handy in cer tainsituations.

Sometimes, for example, an error may be caused by somethingas s imp le as a missp el led variable nam e. In this case, you m aywant to create the variable from within the debugger.Ultimately, you will have to address this type of error in yoursource cod e, but i t is very convenien t to make a temporary f ixfrom within the debugger so that you can cont inue thedebugging process without having to recompile and rel ink r ightaway.

Using the ? I ?? command, you can create a var iable and assign avalue to it . For example:

? myVar := 100

This creates a variable called myVar and assig ns to it a value of100. This var iable is pr ivate to the rout ine being executed wh enit was created.

N o t e : W he n at tem pting to create a var iable in this ma nner, youm ust use the inline assign m ent ope rator (:=). If you use the =operator, the debugger wil l perform a comparison and mostl ikely return an error m essage .

13-56 CA-Cl ipper




Inspecting Program C o d e

As you debug an applicat ion, you may need to examine the code

of progra ms other than the one current ly being executed. Thissection describes how to view other programs and header files,how to use the call stack to access programs that have alreadybeen executed, and how to use breakpoints .

Using B reakpoints

Breakpoints are similar to (and just as powerful as) watchpointsand tracepoints. H ow ev er, brea kpo ints refer to actual l ines of

code rather than variables and expressions.

Breakpoints allow you to return control to the debugger andexecute problem areas of code in single step mode (for anexplanat ion of the mo des of execution, see Executing Prog ramCode earlier in this chapter). This section explains whatbreakpoints are and how to set, delete, and list them.

Definition of α A brea kpo int is a line of pro gram code or a function orBreakpoint proced ure call that , wh en encou ntered, causes the debu gger to

hal t execution of the program. In other words, a breakpo int

defines a physical breaking point in a prog ram.





Sett ing B reakpoints To set a break point in the current pro gram , mov e the cursor tothe appropriate l ine in the Code window and execute the PointBreakpoint command (or s imply press F9) . The selected l ine ishighl ighted:

Locate Uiew Run Point Monitor Options Window Help

0) nkey <wp, Local, U>: NIL


Watch

C :\air ^sSOURCE\SflffTiN^ÂLTD Ο

// Lazy nan's error checkingbSaueHandler : = errorblockC { x break(x) > )

BEGIN SEQUENCEus e (dbf) index (index)

RECOUER USING oErrorif ( oError:genCode == EG_0PEN )

?? "Error opening f i le(s)"

> goto 56

: Comand

To define a funct ion or procedure as a breakpoint , use the BPcom ma nd ins tead of Poin t Breakpoin t . These comman ds a resimilar in that they both d efine breakp oints , but BP is moreflexible and powerful . The fol lowing command defines the

rout ine SayD ata() as a break point . W hen ever a call is ma de tothis rout ine, the debug ger hal ts execut ion:

BP SayData

You can also set breakpoints in programs other than the onecurrent ly displayed in the Code window using the BP command.This example sets a breakpoint a t l ine 15 in the programOpendbfs .prg :

BP 15 In OpenDbfs.prg

13-58 CA-Cl ipper



D e b u g g i n g α Program

Deleting a Breakpoint There are several ways to delete an individual break point . Thefirst is to mo ve the cursor to the app ropr iate line in the C odewindow and execute the Point Breakpoint command (or s imply

press F9 or i s sue BP comman d wi th no parameters ) . Wh en abreakpoin t is dele ted, the line returns to i ts norm al color.

Another way to delete a b reakpoin t is to use the D elete BPcom man d fo l lowed by the breakpoin t number on the commandl ine. Note that breakpoint numbering begins with zero. If youdo not know the number, use the List command.

To delete al l breakpoints , use the Delete command as fol low s:

Delete All BP

Warning Delete All without any other argum ents also deletes allwatchpoints and tracepoints.

Listing Brea kpoints To display all brea kpo ints, use the List BP com m an d. This listsand num bers breakpoin ts in the order they were entered, asshown in the Com ma nd wind ow below. Note tha t number ingbegins with zero:

File Locate Uiew Run Point Monitor Options Window Help

0) nkey <wp, Local, U>: NIL


- H a t c h

C:\aiF53sS0URaE\3rtf1ZSTHlMDl.™A LT D O

// Lazy man's error checkingbSaueHandler := errorblockt < xi break(x) > )

BEGIN SEQUENCEuse dbf) index index)

RECOUER USING oErrorif ( oError:genCode == EG_0PEN )

?? "Error opening file(s)"

: tomand :

> list bp0 ) 56 TBDEN01.PRG

I]SEESEj

Sett ing and viewing breakpoints is easy using the W orkbe nch.See Resolving Runtime Errors in the "Debuggin g YourAppl ica t ions" chapter of th e Workbench User Guide.


http://c/aiF53sS0URaE/3rtf1ZSTHlMDl.%E9%80%80

http://c/aiF53sS0URaE/3rtf1ZSTHlMDl.%E9%80%80



D e b u g g i n g α Program

Naviga t ing the Ca l l S tack

The call stack is a l ist of pending activations, includingprocedures, funct ions, code blocks, and message sends. It is

displayed in the Calls tack win dow on the r ight-hand side of thescreen, which is control led using the View Calls tack com man d.

W h e n it is act ive, the Calls tack wind ow al lows you to highl ight aprogram in the call stack an d vie w it in the Code win dow .

File Locate Uiew Run Point Monitor Options Window HelpIlatch

0) nkey <wp, Local, M>: 10011) If lag <wp, U>: Mot eualuated at this actiuation

C:SCLIP53\S0LRCEsS(WLBsTBraM)l.PRG

case nKey == KJffiTURMDoGetC oBrowse )

otherwiseKEYBOARD chr( nKey )DoGetC oBrowse )

endcase

RETURM

IfrBDEMO |

COVBIld> goto 357> goto 363>

W hen the Cal l stack window is active , the highlight bar appe arson the first item in the w indo w. You can use Up and D ow narrow to m o v e to the act ivation w hose co de you w ish to view.As you move the highl ight within the window, the Code,Mo ni tor, and Watch windo ws are immedia te ly updated to reflectthe highlighted activation.

If the activation you have chosen is a code block (denoted by alowercase "b ") , the name in the call stack is the nam e of theroutine in w hich the block wa s created. The cod e for this routine

appears in the Code windo w.

13-60 CA-Clipper




To return to the program original ly being debugged, use the Fi leRes um e com ma nd . For a l ist of the cal l s tack navigat ion keys,see The Debugger Display earl ier in this chapter.

The cal l s tack is concerne d only with execu table code. If youwant to view the contents of a header f i le you must use theprocedure out l ined in the next sect ion.

Viewing Files

Although inspect ing the cal l s tack provides an easy way to selectand view p rogram code , i t does not display header f i les . I f you

already know the name of the program you want to view or youwant to examine a header f i le , use the Fi le Open command.

The fol lowing example displays the code for the header f i leInkey.ch in the Co de wind ow . No tice that this exam ple gives afile extension; if none is supplied, a (.prg) extension is assumed:

File Open \CLIP53\ INCLUDE\Inkey.ch

You can also use the Fi le Open command to view other programfiles in yo ur application . This feature is con ve nien t if you w an t

to set a breakp oint in another prog ram b ut do not know the l inenumber and cannot , therefore, set i t using the BP command.

To return to the original program, use the Fi le Resumecom ma nd. The debugger saves any breakpoin ts tha t you ha veset and respects them the next time you run the application.

For a l is t of navigat ion keys used within the Code window, seeThe Debugger Display earl ier in this chapter.

For information on viewing and edi t ing various types of f i lesusing the Workbench, see the "Browsing Applicat ions,Modules , and Ent i t ies" and "Using the Source Code Edi tor"chapters of the Workbench User Guide.

Prog ram min g an d Utilit ies G uide 13-61

http://clip53/

http://clip53/




Accessing DOS

There may be t imes wh en you w ish to execute a DO S comm andwitho ut leaving the debu gger. For exam ple, you may want tosee a directory listing of all program (.prg) files. To do this, usethe Fi le DO S com ma nd. The DO S prom pt wil l be displayed, andyou can execute any DOS command you l ike.

Warning Accessing DO S invokes a temporary copy ofCOMMAND.COM. Make sure that you have sufficient mem oryavailable to load this file an d any others you m ay wish to execute.Remem ber that you are using a temporary copy of DO S, so anyenvironm ent variables you set will be lost upon returning to thedebugger.

When you have f inished and wish to continue executing yourapplicat ion, type "Exit" at the DOS prompt.

13-62 CA-Clipper

http://command.com/

http://command.com/



M e n u C o m m a n d R e f er e nc e

M e n u C o m m a n d R e f e re n c e

This section is a complete reference to the syntax and operationof al l the debu gger com ma nd s. Yo u can execute d ebugg ercommands by select ing opt ions from the menu bar or byentering com ma nds d i rec t ly in to the Com ma nd w indow . Youhave seen the former method described in The Debugger Displaysect ion and the lat ter method used in the examples in Debugginga Program earlier in this chapter.

The important thing to remember about the debugger is that anymenu option can be expressed in the form of a command usingthe m enu nam e fol lowed by the f i rs t w ord of the opt ion nam e. Ifrequired, arguments are placed at the end of the menu commandline. Select ing a me nu option and enter ing the equivalent m enucommand have the same effect .

All of the menu command equivalents and several othercommands that have no menu equivalents are explained in thissect ion. To execute a com m and , ei ther type the com ma nd andpress Enter to execute, or make the equivalen t me nu select ion i fone is avai lable. The only difference betwee n these two me thod sof command execution is that commands you type appear in the

Com ma nd w indow and are , therefore , ava i lab le in the co mm andhistory buffer, which is not so with m enu select ions.

When using the Workbench, the avai lable menu select ionsvaries dependin g on the object being view ed. For detai ls on themenu commands avai lable for each object , access theWorkbench onl ine Help system.





? | ? ?

Purpose

Syntax

A rg u m e n t s

<exp>

Descr ip t ion

Display the value of an expression

? I ?? <exp>

The expression to be displayed .

? causes the value of the specified expression to be displayed inthe Co m m and w indo w . ?? displays the value in a pop -upwin dow wh ich is closed by pressing Esc. The expression used asthe ? I ?? command l ine argument can be any val id CA-Clipperexpression, including user-defined funct ions, arrays, and inl ineassignments .

W hen the display expression is a code block, the value cannotactua lly be displa yed . For this data type, an icon is display edinstead.

If the expression is an array or an object, an icon is displayed ifthe valu e is displa yed w ith either ? or ??. ??, how eve r, will alsodisplay the array or object contents if you press Enter in the first

pop -up win dow . To close both pop-u ps, you must press Esctwice.

Both ? and ?? can be used to query individual array elements bysubs criptin g the array na m e. Sim ilarly, object instance variablescan be queried using the send operator (:) , as in<objName>:<idInstance>.

13-64 CA-Clipper




The ability to display the return value of a user-defined functionallow s you to extend the abilit ies of the deb ugg er. For exam ple ,you might want to modify the structure of a database file while

deb ugg ing an app lication. To do this, simp ly write a functio n toperform the modif icat ion, comp ile and l ink it with yourapplication, and execute it using the ? I ?? com man d. Anyfeature that does not already exist can be written as a user-defined funct ion and executed in this way.

Using the inline assignment operator (:=) with the ? I ??command al lows you to create new variables .

E x a m p l e s The fol lowing exam ples query various values (a f ield, a logical

exp ressio n, and a CA -Clip per fun ction ). In each case, the resultis shown below the ? command as i t would be in the Commandwindow:

? InvNum465

? X = Y.T.

? EOF().F.

In this example, the EVALQ function is used to execute a codeblock:

? EVAL(bSortBlock)

This example creates a new private variable called nPageNo,assigns it the value 2, and displays the variable in a pop-upwin dow . To close the w indo w , press Esc:

?? nPageNo : = 2





BP

Purpose Set or remo ve a breakp oint

Syntax BP [[At] [<lineNum>] [[In] <idProgramFile>]]]BP [<idFunction> I <idProcedure>]

A rg u m e n t s

A t <HneNum> The l ine num ber wh ere you wa nt prog ram execution to s top.

In <idProgramFile> Th e filenam e of the pro gra m in w hich to set the break poin t. If noextension is specif ied, (.prg) is assumed.

<idFunction> I <idProcedure>The nam e of a rout ine specified without parentheses. W hen y ouset a breakpoint in this manner, execution stops each time theroutine is called.

If no options are specified, BP refers to the line indicated by thecursor in the Code window.

Descr ip t ion BP design ates a line of pro gra m cod e or a call to a routine as abreakpo int . W hen you execute this com m and , the l ine of code is

indicated in a new color to distinguish it as a breakpoint andexecution will pause as soon as the line is encountered or theroutine is called.

BP a cts as a toggle so that if the specified line of cod e is alread y abreakpoint, the breakpoint is deleted and the color of the linereturns to norm al .

To delete a breakp oint , use the Delete com ma nd. To see al lbreakpoint set t ings in the Command window, use the List BPcom ma nd . For mo re informa tion on the use of breakpo ints , seeDeb ugg ing a Prog ram earl ier in this chapter.

13-66 CA-Clipper




E x a m p l e s This exa m ple toggles the break poin t setting at l ine 12 of theprogram displayed in the Code window:

BP 12

This example toggles the breakpoint setting at the current line inthe Code wind ow :

BP

This example toggles the breakpoint setting at l ine 15 ofFile2.prg:

BP At 15 In File2

Here , the breakp oint is designated using a funct ion na m e:

BP TestUdf

See Also Delete , List , Point Breakpo int , Run G o, Run Step





Callstack

Purpose

Syntax

A rg u m e n t s

O n

Off

Descr ip t ion

E x a m p l e s

Control the Calls tack window

Calls tack [on I Off]

Op ens the Calls tack w indo w on the r ight-hand side of the screen.

Closes the Calls tack window.

If no options are specified, Callstack acts as a toggle, changingthe current s tatus of the Calls tack wind ow . Executed w ithout an

option in this manner, Callstack is functionally equivalent to theView Cal l s tack command.

Calls tack toggles the display of the Calls tack win dow . Thiswindow contains the call stack, a list of pending activations withthe current activation at the top. For more information on thecall stack, see Debugging a Program earlier in this chapter.

To open the Calls tack window:

Callstack On

To close the window:

Callstack Off

See Also View Calls tack

13-68 CA-Clipper



M e n u C o m m a n d R e f er e n c e

Delete

Purpose

Syntax

Argument s

All

BP

TP

W P

<number>

Descr ip t ion

Delete debugger set t ings

Delete All [BP I T P I WP]Delete BP I T P I W P <number>

De letes all settings of a specified type or all settings if no typ e isspecif ied.

Specif ies breakpoints .

Specif ies t racepoints and watchpoints .

Specif ies watchpoints and tracepoints .

The number of the individual watchpoint , t racepoint , orbrea kp oin t to delete. If not specified, Delete opens a dialog bo xto prompt you for the i tem number.

Delete removes watchpoints , t racepoints , and breakpoints , e i ther

individual ly or as a who le.

To delete all i tems of a particular type, use the Delete All form ofthe command.

To perform a s ingle delet ion, specify the num ber an d type of theitem to be deleted. For watch po ints and tracep oints, this is thenumber that appears on the lef t -hand side of the Watch window.For breakpoints the List command must be used to determinethe number.

N o t e : Tracepo ints and wa tchpoin ts are not dis tinguished by theDelete com ma nd . Thu s, Delete TP and Delete W P aresynonymous as are Delete All TP and Delete All WP.

For a detai led explanat ion of break poin ts , tracepoints , andwatchpoints , see Debugging a Program earl ier in this chapter.

Prog ram min g a n d Utilit ies Gu ide 13-69




E x a m p l e s To delete a brea kpo int, you mu st first find out w here it falls inthe list of breakpoints:

List BP

If the breakpoint you want to delete is number three on the list:

Delete BP 3

This exam ple deletes all watch points (and tracepoints) :

Delete All WP

He re, a ll breakp oints , t racepoints , and wa tchpoints are deleted:

Delete All

See Also BP , List, Poin t Brea kpo int, Poin t De lete, Poin t Tracep oint, PointWatchpoin t

13-70 CA-Clipper




File DOS

Purpose

Syntax

Descr ip t ion

Access DOS without leaving the current applicat ion

File DOS

Shortcut Equivalent

Abbrevia t ion F D

Accelerator key Al t+F, D

Synonym DOS

File DOS loads a temporary copy ofC O M M A N D . C O M , al lowing you to enter DOS commands without leaving thecurrent applicat ion. To return to the debu gger, type "Ex it" at theDOS prompt .

When using this command, you must make sure suff icientm em ory is avai lable to loadC O M M A N D . C O Mand anyaddit ional program s you want to execute. I f the amo unt ofm em ory is insuff icient , an error message w il l be d isplayed.

File Exit

Purpose

Syntax

Terminate the debugger, close all files, and return to DOS

File Exit

Shor tcut Equivalent

Abbreviat ion F E

Accelerator key Al t+F, X

Shortcut key Al t+X

Synonym Quit


http://command.com/

http://command.com/

http://command.com/

http://command.com/




File Open

Purpose

Syntax

A rg u m e n t s

<idFileNarne>

Descr ip t ion

Vie w a f ile during the current debug ging session

File Open <idFileName>


Abbrevia t ion F O

Accelerator key Al t+F, Ο

Th e nam e of the file you w ant to vie w . If no extensio n isspecif ied, (.prg) is assum ed. If <idFileName> is not specified onthe command l ine, Fi le Open opens a dialog box to prompt youfor a filename.

File Open allows you to look at other files without leaving thecurrent debugging session, including header f i les specif ied withthe #inclu de preproce ssor direct ive. Breakpoints can be set andare saved when you return to the original program.

Un less you hav e defined a source f i le search path with theOptions Path command, the f i lename that you specify issearched for in the current directory only. I f, how eve r, you havedefined a search path, the directories in the path are searched inorder until the file is found.

When you view a f i le with Fi le Open, the current program iscleared from the Code window and the new fi le is displayed inits place . To continu e with the original prog ram , use FileResume.

N o t e : Fi le Op en is almost ident ical to the View com ma nd. Theonly difference between these two commands is that Fi le Openassumes a (.prg) extension whereas View assumes no f i leextension.

13-72 CA-Clipper




E x a m p l e s To view ListDbfs.prg:

File Open ListDbfs

To view another file, PrintDbf.prg, before returning to theoriginal program:

File Open PrintDbf

See Also Fi le Resu me , Op tions Path, View

File Resume

Purpose Return from view ing a f i le

Syntax Fi le Resu me

Shortcut Equivalent

Abbreviat ion F R

Accelerator key Alt+F, R

Synonym Resume

Descr ip t ion File Resume clears the file being viewed with the File Opencommand (or using the Calls tack window) and redisplays thefi le or iginal ly show n in the Cod e windo w. Any b reakpo intswhich have been set are saved.

Examples Suppose the program current ly being debugged is cal ledPrtData.prg. The fol lowing l ine temporari ly removesPrtData.prg from the Code window and displays Rpthead.prg inits place:

File Open RptHead

The fol lowing l ine returns PrtData.prg to the Code window:

File Resume

See Also File Open





Help

Purpose

Syntax

A rg u m e n t s

Keys

Windows

Menus

C o m m a n d s

Act iva te the Help wind ow

Help [Keys I Wi n d o w s I M e n u s I Commands ]

Shortcut Equivalent

Abb reviat ions Η Κ; Η W ; Η Μ ; Η C

Accelerator keys Al t+ H, Κ; Al t+ H, W ; Al t+H , Μ; Al t+H , C

Shortcut key F l

Highlights the Keys topic when the Help window is act ivated.

Highlights the Windows topic when the Help window isact ivated.

Highlights the Menus topic when the Help window is act ivated.

Highlights the Commands topic when the Help window isact ivated.

If issued without an argument , Help highl ights the About Helptopic when the Help window is act ivated.

13-74 CA-Clipper




Descr ip t ion The debug ger Help win dow is divided into two panes: the leftpane contains a list of topics for which help is available, and theright pane contains the help text for the currently highlightedtopic. W hen the Help windo w is act ivated with the Helpcommand, one of the topics in the left pane is highlighted, and ageneral discussion of the topic is displayed in the right pane ofHelp window.

The text that the debugger displays in the Help window iscontained in a separate f i le , CL D.H LP , which m ust be present o nyour disk. W hen yo u ask for help, the debugger searches thecurrent directory fol lowed by al l directories in the DO S PA TH .If CL D.H LP is not found in any of these locat ions, the debu gger

will prom pt you for a directory na m e. If CL D .H LP is still notfound, you will not have access to help text within the debugger.

For information on using the Help window, see The DebuggerDisplay earlier in this chapter.





List

Purpose

Syntax

A rg u m e n t s

BP

TP

W P

Descr ip t ion

E x a m p l e s

See Also

List wa tchpoin ts , t racepoints , and breakpoints

List BP I TP I W P

Specif ies breakpo ints .

Specif ies t racepoints and watchpoints .

Specif ies watchpoints and tracepoints .

List displays all watchpoints, tracepoints, or breakpoints in theCom ma nd w indow . This com man d i s usefu l when you want toDelete set tings by n um ber.

N o t e : Tracepoints and watchp oints are not dis tinguished by theList com m and . Thu s, List TP and List W P are synony mo us. TheWatch window can also be used to determine the number ofthese items.

For more information on the setting and deleting of these items,

see Debugging a Program earlier in this chapter.

If there are breakpoints at l ines 10 and 15 of AddData.prg andlines 2 and 6 of ViewData.prg, List BP displays the following:

0) 10 ADDDATA.PRG1) 15 ADDDATA.PRG2) 2 VIEWDATA.PRG3) 6 VIEWDATA.PRG

To list all watchpoints (and tracepoints):

List WP

BP, Delete, Point Breakpoint, Point Delete, Point Tracepoint,Point Watchpoint

13-76 CA-Clipper



Menu Command Reference

Locate Case

Purpose Toggl e search case-sensi ti vity setting

Syntax Locate Case

Shortcut Equivalent

Abbreviation L C

Accelerator key Alt+L, C

Description Locate Case changes the current case-sensitivity setting. This

setting is used by all the Locate search commands (that is, LocateFind, Locate Next, and Locate Previous) to determine whether toignore or respect the case of the letters in the search string whentesting for a match.

If case-sensitivity is on, a string must match the contents andcase of the specified search string. If off (the default ), only thecontents need be the same for a successful match.

The Locate Case Sensitive menu option can be used to check thestatus of the case-sensit ivity se tting. An on setting is indicatedby a chec kmark to the left of the menu option . An off setti ng isindicated by the absence of the checkmark in the menu.

Examples Suppose you want to locate all occur rences of the USE com mandin your program, but are not always consistent in usinguppercase letters for comma nds. If case-sensitivity is currentlyon, Locate Find USE will not find all occurrences of thecommand but only those in which all uppercase letters are used.To turn the case -2ens i t iv i ty setting off and locate the USEcommand in all its possible forms:

Locate CaseLocate Find USE

See Also Locate Find, Locate Next , Locate Previous

Programming and Utilities Guide 13 77




Locate Find

Purpose

Syntax

A rg u m e n t s

<searchString>

Descr ip t ion

Locate a string

Locate Find <searchString>

Shortcut Equivalent

Abbreviat ion L F

Accelerator key Al t+L , F

Synonym Find

Th e literal string you w ant to locate. If <searchString> is notspecified on the command line, a dialog box opens on the screento prompt you for a search string.

Locate Find searches the file displayed in the Code window for aspecified search string.

The search always begins at the first l ine of code and movesdown through the file, regardless of the current cursor positionin the Co de win do w . If the search string is fou nd , the debu ggermoves the cursor to the line containing the first occurrence of thestring in the Code window; otherwise, the cursor remains at i tscurrent location.

N o t e : I f the Co m ma nd w indo w is act ive wh en Locate Find isexecuted, you will not see the cursor move to its new location inthe Cod e windo w. You m ust select the Cod e win dow in order tosee the new cursor position in the file.

This com m an d obeys the Loca te Cas e Sensitive m enu setting. Ifthis menu setting is on (indicated by a checkmark), Locate Findlooks for a string that matches the contents and case of thespecified sea rch string. If off, only the contents need be the sam efor a success ful match . The Locate Case com m and is used totoggle this menu setting on and off.

13-78 CA-Clipper



M e n u C o m m a n d R e f e r en c e

Examples

See Also

If you suspect that the error you are trying to eliminate relates toa database (.dbf) fi le that is not open, search for the keywordUSE:

Locate Find USE

Locate Case, Locate Next, Locate Previous

Locate Goto

Purpose

Syntax

Move the cursor to a specified line in the Code window

Locate Goto <HneNum>

Shortcut Equivalent

Abbreviat ion L G

Accelerator key Al t+L, G

Synonym Goto

Argument s

<UneNum> The nu m ber of the line wh ere you w ant to m ove the curso r. If<UneNum> is not specified on the com m an d line, Locate G otoopens a dialog box to prompt you for a line number.

Descr ip t ion Locate Go to m ove s the cursor from its current position in theCode window to the specif ied l ine number.

This command works regardless of whether l ine numbers arecurrent ly displayed in the Cod e windo w. Ho we ver, for the sake

of readabil i ty we recommend that l ine numbers be displayed.For more inform ation refer to the Options Line com ma nd in thissection.

N o t e : I f the Co m ma nd w indo w is act ive wh en Locate Go to isexecuted, you will not see the cursor move to its new location inthe Cod e windo w. You mu st select the Cod e win dow in order tosee the new cursor position in the file.




Menu Com man d Re fe rence

E x a m p l e s

See Also

This exam ple m oves the cursor to l ine 30 of the pro gramcurrent ly being debugged:

Locate Goto 30

Num, Opt ions Line

Locate Next

Purpose

Syntax

Descr ip t ion

Locate the next occurrence of a string

Locate Next

Shortcut Equivalent

Abbrevia t ion L N

Accelerator key Al t+L, Ν

Synonym Next

Locate Next locates the next occurrence of the most recentlydefin ed search string. A search string is define d using LocateFind . If no search string has been defin ed, Locate Next opens a

dialog box to prompt you for one.

The search begins at the current cursor position in the Codewin dow and move s dow n through the f i le . I f a match is found ,the debugger moves the cursor to the line containing the nextoccurrence of the string; otherwise, the cursor remains at i tscurrent location.

See Also

N o t e : I f the Co m ma nd w indo w is act ive wh en Locate Next isexecuted, you will not see the cursor move to its new location in

the Co de wind ow . You m ust select the Cod e win dow in order tosee the new cursor position in the file.

Like Locate Find , Locate Next obeys the current Locate CaseSensi t ive menu set t ing. The Locate Case com ma nd is used totoggle this menu setting on and off.

Locate Case, Locate Find, Locate Previous

13-80 CA-Clipper



M e n u C o m m a n d R e f e r e nc e

Locate Previous

Purpose Locate the prev ious occu rrence of a string

Syntax Locate Previous

Shortcut Equivalent

Abbreviat ion L P

Accelerator key Al t+L, Ρ

Synonym Prev

Descr ip t ion Locate Previou s searches for the previous occurrence of the mo strecen tly defined search string. A search string is define d us ingthe Locate Find com ma nd or the Locate Find menu option. I f nosearch s tr ing has been defined, Locate Previous opens a dialogbox to prompt you for one.

The search begins at the current cursor position in the Codewindow and moves up through the f i le .

If a match is found, the debugger moves the cursor to the linecontaining the previous occurrence of the string; otherwise, thecursor remains at i ts current location.

N o t e : I f the Co m ma nd wind ow is act ive wh en Locate Previousis executed, you will not see the cursor move to its new locationin the Co de wind ow . You m ust select the Cod e window in orderto see the new cursor position in the file.

Like Locate Find, Locate Previous obeys the current Locate CaseSensi t ive menu set t ing. The Locate Case comm and is used to

toggle this menu setting on and off.

See Also Locate Ca se, Locate Find, Locate Nex t

Pro gra mm ing a n d Utilities G uid e 13-81




Monitor All

Purpose

Syntax

Descr ip t ion

E x a m p l e s

See Also

To ggle the display of variables in all storage classes in the

Moni tor window

Monitor All

Shortcut Equivalent

Abbreviat ion M A

Accelerator key Al t+M, A

Monitor All acts as a toggle by changing the current displaystatus of all storage classe s (that is, local, private, public, andstatic) in the M onito r w ind ow . The default setting for Mon itorAll is off.

Monitored variables relate to the routine currently displayed inthe Cod e windo w. W hen a pending act ivat ion is viewed via theCalls tack wind ow , the values displayed for the m onitoredvariables are the values that they held when the pending routinewas active.

Inspecting the variables with the ? I ?? com ma nd or specifyingthem as watchpoints or tracepoints yields the current value,which may be different from the value displayed in the Monitorw ind ow . An y existing variab les that are not visible to theact ivat ion in the Co de win dow do not appear in the Monitorwindow.

To view all variables in all storage classes in the Monitorwindow:

Monitor All

M onitor Lo cal , Mo nitor Private , Monitor Public , Monitor Sort ,Monitor Static

13-82 CA-Clipper



M e n u C o m m a n d R e f e r e nc e

Monitor Local

Purpose Tog gle the display of local var iables in the Mon itor w indo w

Syntax Monitor Local

Shortcut Equivalent

Abbrevia t ion M L

Accelerator key Al t+M , L

Description M onitor L ocal acts as a toggle by chan ging the current display

status of local variables in the Monitor window (for example, iflocal var iables are not being monitored, Monitor Local beginsmo nitor ing them ). The defaul t set ting for M onitor Local is off ,meaning that local var iables are not monitored.

Examples

The Monitor window indicates that local var iables are beingmonitored using the word "Local" in i ts window t i t le .

Monitored variables relate to the rout ine current ly displayed inthe Co de wind ow . W he n a pend ing act ivat ion is viewe d via theCalls tack window, the values displayed for the monitoredvariables are the values that they held whe n the pending rout inewas act ive.

Inspecting the variables with the ? I ?? command or specifyingthem as watchpoints or t racepoints yields the current value,which may be different f rom the value displayed in the Monitorwin dow . An y exis t ing variables that are not vis ible to theact ivat ion in the Code window do not appear in the Monitorwindow.

To change the display status of local variables in the Monitorwindow:

Monitor Local

See Also Monitor All , Monitor Private , Monitor Public , Monitor Sort ,Monitor Stat ic

Pro gram m ing a n d Utilities G uid e 13-83



M e n u C o m m a n d R e fe r en c e

Monitor Private

Purpose Togg le the display of pr ivate var iables in the M onitor wind ow

Syntax Monitor Private

Shortcut Equivalent

Abbrevia t ion M P r

Accelerator key Al t+M, V

Descr ip t ion Monitor Private acts as a toggle by changing the current displaystatus of pr ivate var iables in the Mo nitor win dow (for exam ple,

i f pr ivate var iables are not being mo nitored , M onitor Privatebegins monitor ing them). The defaul t set t ing for Monitor Privateis off, meaning that private variables are not monitored.

E x a m p l e s

The Monitor window indicates that pr ivate var iables are beingmonitored using the word "Private" in i ts window t i t le .

M onitored variables relate to the rout ine current ly displayed inthe Co de wind ow . W hen a pend ing act ivation is view ed via theCalls tack window, the values displayed for the monitoredvariables are the values that they held when the pending rout inewas act ive.

Inspecting the variables with the ? I ?? command or specifyingthem as watch points or t racepoints yields the current value,which may be different f rom the value displayed in the Monitorwi nd ow . An y existing variable s that are not visible to theact ivat ion in the Code window do not appear in the Monitorwindow.

To change the display status of private variables in the Monitor

window:Monitor Private

See Also Monitor All , Monitor Local , Monitor Public , Monitor Sort ,Monitor Static

13-84 CA-Cl ipper




Monitor Public

Purpose Toggle the display of publ ic var iables in the Monitor window

Syntax Monitor Public

Shortcut Equivalent

Abbrev ia t ion M P

Accelerator key Al t+M, Ρ

Descr ip t ion

Examples

Mo nitor Public acts as a toggle by changing the current display

status of publ ic var iables in the Monitor w indo w (for exam ple, i fpubl ic var iables are not being monitored, Monitor Public beginsmon itor ing them ). The defaul t set t ing for M onitor Public is off ,meaning that publ ic var iables are not monitored.

The Monitor window indicates that publ ic var iables are beingmonitored using the word "Public" in i ts window t i t le .

Monitored variables relate to the rout ine current ly displayed inthe Cod e windo w. W hen a pend ing act ivat ion is viewe d via theCalls tack window, the values displayed for the monitored

variables are the values that they held when the pend ing rout inewas act ive.

Inspect ing the variables with the ? I ?? command or specifyingthem as watchpoints or t racepoints yields the current value,which may be different f rom the value displayed in the Monitorwin dow . An y exis t ing variables that are not vis ible to theact ivat ion in the Code window do not appear in the Monitorwindow.

To chan ge the display s tatus of publ ic var iables in the M onitorwindow:

Monitor Public

See Also Monitor All , Monitor Local , Monitor Private , Monitor Sort ,Monitor Stat ic

Pro gram min g a n d Utilit ies Gu ide 13-8£




Monitor Sort

Purpose Con trol the orde r in wh ich varia bles are displa yed in theMoni tor window

Syn tax Mo nitor Sort

Shortcut Equivalent

Abbrevia t ion Μ So

Accelerator key Al t+M, Ο

Descr ip t ion When Monitor Sort is on (indicated by a checkmark to the left of

the Monitor Sort menu opt ion) , i tems in the Monitor window aredisplayed in alphabet ical order according to variable name.

E x a m p l e s

W hen Mo nitor Sort is off (the defaul t ) , the monitored variablesare grouped by s torage class .

To sort monitored variables by nam e if they are current lygrouped by s torage class:Monitor Sort

See Also Monitor All , Monitor Local , Monitor Private , Monitor Public ,Monitor Stat ic

13-86 CA-Cl ipper



M e n u C o m m a n d R e f e r e n ce

Monitor Static

PurposeTogg le the display of s ta tic var iables in the M onitor win dow

Syntax Monitor Static

Shortcut Equ iva len t

Abbreviat ion M S

Accelerator key Al t+M , S

Descr ip t ion Monitor Static acts as a toggle by changing the current displaystatus of static variables in the Monitor window (for example, ifs ta tic var iables are not being m onitored , Monitor Stat ic begin smonitoring them). The default setting for Monitor Static is off,me aning that sta tic var iables are not m onitored .

The Monitor window indicates that s ta t ic var iables are beingmonitored using the word "Stat ic" in i ts window t i t le .

M onitored variables relate to the rout ine current ly displayed inthe Cod e win dow . W hen a pen ding act ivat ion is view ed via the

Calls tack window, the values displayed for the monitoredvariables are the values that they held wh en the pendin g rout inewas active.

Inspecting the variables with the ? I ?? command or specifyingthem as watch points or t racepoints yields the current value,which may be different f rom the value displayed in the Monitorwi nd ow . An y existing variables that are not visible to theact ivat ion in the Code window do not appear in the Monitorwindow.

E x a m p l e s To cha nge the display status of static variab les in the M on itorwindow:

Monitor Static

See Also Mo nitor All , Mo nitor Local , M onitor Private , M onitor Public ,Monitor Sort

Pro gram min g a n d Util it ies Gu ide 13-87



M e n u C o m m a n d R e fe re n c e

Num

Purpose

Syntax

A rg u m e n t s

O n

Off

Descr ip t ion

Toggle the display of l ine numbers

Num [On I off]

Displays line numbers at the beginning of each line of code.

Removes the l ine numbers .

If no options are specified, Num acts as a toggle by changing thel ine num ber s tatus . Executed w ithout an opt ion in this mann er,Num is funct ional ly equivalent to the Options Line command.

N um toggles the display of l ine numb ers at the beginning ofeach line of code in the Co de win do w . W he n you first start thedebu gger, Nu m is On and l ine num bers are displayed. This ispart icular ly useful when using the Locate Goto command tom ove the cursor to a cer tain l ine in the Code win dow .

See Also Locate Goto, Options Line

13-88 CA-Clipper



M e n u C o m m a n d R e f e r e n ce

Options Co deb lock

PurposeControl the t racing of code blocks during s ingle s tep mode

Syntax Opt ions Codeblock


Abbrevia t ion o c

Accelera tor key Al t+ O, Β

Descr ip t ion Options Codeblock acts as a toggle to control whether thedebugger t races code blocks in s ingle s tep mode.

By defaul t , Options Codeblock is on ( indicated by a checkmarknext to the Options Codeblock Trace menu opt ion) , causingsingle step mode to trace a code block back to its definition eacht ime the code block is evalua ted. I t does this by m oving theexecut ion bar to the l ine where the code block was defined,al lowing you to see the code block defini t ion.

Tracing code blocks involves an extra s tep each t ime a code block

is evaluated b ecau se you also have to s tep over the l ine of codedefining the code block. I f you do not want to t race code b lockdefini t ions, turn Options Codeblock off .

For more information on modes of execut ion, see Debugging aProgram earl ier in this chapter.

E x a m p l e s To change the current code block t race s tatus:

Options Codeblock

See Also Run Step

Pro gram min g a n d Util it ies Gu ide 13-89




Options Color

Purpose Open the Set Colors window

Syntax Options Color

Shortcut Equivalent

Abbreviat ion O C o l

Accelerator key Al t+O, C

Descr ip t ion Options Color act ivates the Set Colors window where you caninspect and change the debugger color settings. For informationon using the Set Colors window, see The Debugger Displayearlier in this chapter.

Note that although Options Color expects additional input, thecolor settings cannot be specified on the command line as witho ther menu commands .

N o t e : W hen the display mo de is mo noch rom e (see OptionsM o n o ) , the Options Color command is not operat ional .

E x a m p l e s To inspect the debugger color settings:Options Color

See Also Opt ions Mo no, View Sets , View Workareas

13-90 CA-Cl ipper




Options Exchange

Purpose Control the display of program output while in animate mode

Syntax Options Exchange

Shortcut Equivalent

Abbreviat ion O E

Accelerator key Al t+O, Ε

Description Options Exchange acts as a toggle to control the display of

program output while in animate mode.

By default, this option is on (indicated by a checkmark next tothe Options Exchange Screens menu option) , causing animatemode to display the application output for each line of codeexecuted.

If Options Exchange is off, the debugger displays the applicationscreen only wh en input is required. For mo re information o nmo des of execution, see Debugg ing a Program earl ier in thischapter.

Examples To change the current program output display status:

Options Exchange

See Also Opt ions Swap, Run Anim ate , View App

Pro gra mm ing a n d Utilities G uid e 13-91




Options Line

Purpose Toggle the display of l ine numbers in the Code window

Syn tax Options Line


Abbrev i at ion O L

Accelerator key Al t+O, L

Descr ip t ion Op tions Line toggles the display of l ine num bers at thebeginning of each l ine of code in the Code window (for example,

i f l ine num bers are being d isplayed, Op tions Line turns theirdisplay off). The default setting for Options Line is on, meaningthat l ine numbers are displayed.

Having line numbers in the code listing is particularly usefulwhen using the Locate Goto command to move the cursor to acertain l ine in the Code window.

Options Line is funct ional ly equivalent to the Num commandspecified without an option.

E x a m p l e s

See Also

To chan ge the display s tatus of l ine num bers in the Co dewindow:

Options Line

Locate Goto , Num

13-92 CA-Cl ipper



M e n u C o m m a n d R e f er e n ce

Options Menu

Purpose Togg le the debug ger m enu bar display

Syntax Opt ions Menu


Abbrev ia ti on O M

Accelerator key Al t+O, Μ

Descr ip t ion Options Menu toggles the display of the debugger menu bar.The defaul t set t ing for Options Menu is on, meaning that them enu b ar is vis ible .

N o t e : Menu options can be executed using the appropriateaccelerator key even when the menu bar is hidden from view.The menu bar wil l be displayed while the menu select ion isbeing made but wil l disappear af ter the opt ion is executed.

Examples To change the display s tatus of the menu bar:

Options Menu





Options M ono

Purpose

Syntax

Descr ip t ion

E x a m p l e s

See Also

Toggle the debugger display mode between color andmonochrome

Opt ions Mono


Abbrevia t ion Ο Mo

Accelera tor key Al t+ O, D

Options Mono toggles the debugger display mode between colorand m ono chro me . This com ma nd is effect ive for color monitorsonly.

The defaul t set t ing for Options Mono depends on the kind ofmonitor you are using (that is, for color monitors the default isoff , whereas for monochrome monitors i t is on) .

N o t e : W hen the display m ode is set to mo noc hrom e, theOptions Color command is not avai lable.

To change the debugger display mode:Options Mono

Options Color

13-94 CA-Clipper




Options Path

Purpose

Syntax

A rg u m e n t s

<idPathList>

Descr ip t ion

Examples

See Also

Define the search path for source files

Options Path <idPathList>


Abbreviat ion Ο Pa

Accelerator key Al t+O, F

A list of one or more directory names separated by semicolons.This option specifies the path used by the debugger to search forsource files if they cann ot be found in the default directory . If<idPathList> is not specif ied on the com ma nd l ine, Options P athopens a dialog box to prompt you for a search path.

Options Path allows you to specify one or more alternativedirectories to be searched if a particular source file cannot befound in the default directory.

The search path that you specify pertains to source files only(that is, the View and File Open commands). Other file searchesare not affected.

To specify the DBU and RL source code directories:

Options Path \CLIP53 \SOURCE\DBU; \CLIP53 \SOURCE\RL

File Open , View


http://clip53/

http://source/DBU

http://clip53/

http://source/RL

http://source/RL

http://clip53/

http://source/DBU

http://clip53/




Options Preprocessed

Purpose Toggle the display of preprocessed code in the Code window

Syntax Opt ions Preprocessed

Shortcut Equivalent

Abbrevia t ion O P

Accelerator key Al t+O, Ρ

Descr ip t ion Options Preprocessed acts as a toggle by changing the currentdisplay s tatus of prep rocessed cod e in the Cod e window . By

defaul t , Options Preprocessed is off , meaning that preprocessedcode is not displayed .

When Options Preprocessed is on ( indicated by a checkmark tothe lef t of the Options Preprocessed Code menu option) ,preprocessed code for the current program appears underneatheach l ine of source code . Since the prepro cessed cod e is takenfrom the corresponding (.ppo) f i le , the program in the C odewindow must be compiled with the /P opt ion or, f rom theWorkbench, with Generate PPO File checked in the CompilerOptions dialog box.

The Code window indicates the display s tatus of preprocessedcod e in its w ind ow title as we ll as in the w ind ow itself. Thepresence of the corresponding (.ppo) f i lename in the windowti tle indicates that prepro cessed code is being displayed.

E x a m p l e s To change the display s tatus of preprocessed code in the Codewindow:

Options Preprocessed

13-96 CA-Clipper




Options Restore

Purpose

Syntax

A rg u m e n t s

<idScriptFile>

Descr ip t ion

Examples

Read commands from a scr ipt f i le

Options Restore <idScriptFile>

Shortcut Equivalent

Abbreviat ion O R

Accelerator key Al t+O, R

Synonym Input

The nam e of the scr ipt f i le from wh ich to read comm and s. I f noextension is specif ied, (.eld) is assum ed. If <idScriptFile> is no tspecif ied on the command l ine, Options Restore opens a dialogbox to prompt you for a f i lename.

Op tions Restore causes the debug ger to read and execute al lcom m and s in the specif ied scr ipt f i le then resum e acceptinginput from the keyboard.

Script fi les can be created autom atical ly using the Op tions Savecom m and and can also be wri t ten using a text edi tor or wo rdpro cesso r. For a full exp lana tion of script files and their us es, seeStarting the Debugger earlier in this chapter.

To execute the commands in the scr ipt f i le Viewbug.cld:

Options Restore ViewBug

See Also Options Save





Options Sav e

Purpose

Syntax

A rg u m e n t s

<idScriptFile>

Descr ip t ion

E x a m p l e s

Save the current debugger settings to a script file

Opt ions Save <idScriptFile>

Shortcut Equivalent

Abbreviat ion O S a

Accelerator key Al t+O, S

The name of the script file to which you want to save the currentdebu gger set t ings. I f no extension is specif ied, (.eld) is assumed .If <idScriptFile> is not specif ied on the com ma nd l ine, OptionsSave ope ns a dialog box to prom pt you for a f i lename.

Options Save writes the current debugger settings to a script file.The settings are written to the script file using standard menucommands .

The script file can be executed using the Options Restorecommand or from the CLD command l ine the next t ime youexecu te the deb ug ger. For m ore inform ation on script files, seeStarting the Debugger earlier in this chapter.

To save the current debugger settings to a file namedViewbug.c ld :

Options Save ViewBug

See Also Options Restore

13-98 CA-Clipper




Options Swap

Purpose

Syntax

Descr ip t ion

E x a m p l e s

Control the display of the application screen when input isrequired

Opt ions Swap

Shortcut Equivalent

Abbreviat ion O S

Accelerator key Al t+ O, I

If Op tions Exc hang e is on, Op tions Sw ap has no effect . I f,however, Options Exchange is off , Options Swap acts as a toggleto control wh ether the applicat ion screen is displayed wh eninput is required.

By defaul t , Options Swap is on ( indicated by a checkmark next tothe Options Swap on Input menu option) , which causes RunAnimate to swap to the applicat ion screen when input isrequ ired. If Op tion s Sw ap is off, the app lication screen is notdisplayed during animate mode.

For more information on modes of execution, see Debugging aProgram earlier in this chapter.

To chan ge the current applicat ion screen display s tatus:

Options Swap

See Also Opt ions Exchange , Run Animate , View App





Options Tab

Purpose

Syntax

A rg u m e n t s

<tabSize>

Descr ip t ion

E x a m p l e s

See Also

Set the tab size for the Code window

Options Tab <tabSize>

Shortcut Equivalent

Accelerator key Al t+O, Τ

Abbrevia t ion O T

A numeric value indicating the size to which the tabs areexpa nde d when displayed in the Cod e win dow . The default tabsize is 4. If <tabSize> is not specified on the com m an d line,Options Tab opens a dialog box to prompt you for the tab size.

Options Tab allows you to set the tab size for the Code window.This command is effective only if the file you are viewingconta ins tabs. Lines that are inde nted with spac es are notaffected.

To change the tab size to ten:Options Tab 10

Options Color, Options Mono

13-100 CA-Clipper




Point Breakpoint

Purpose

Syntax

Descr ipt ion

Examples

Set or remove a breakpoint at the current cursor position

Point Breakpoint

Shortcut Equivalent

Abbreviat ion Ρ Β

Accelerator key Al t+P, Β

Shortcut key F9

Point Breakpoint designates the line of code indicated by thecursor in the Cod e win dow as a breakp oint . W hen you e xecutethis command, the line of code is indicated in a new color todistinguish it as a breakpoint.

Point Breakpoint acts as a toggle so that if the current line ofcode is already a breakpoint, the breakpoint is deleted and thecolor of the line returns to normal.

To see al l breakpoint set t ings in the Command window, use theList BP comm and . For mo re information on the use ofbreakpoints , see Debugging a Program earl ier in this chapter.

To toggle the breakpoint setting for the current line of code:

Point Breakpoint

See Also BP , Delete, List , Point Tracepoint , Point W atchp oint

Prog ram ming a nd Utilities Gu ide 13-101




Point Delete

Purpose

Syntax

A rg u m e n t s

<number>

Descr ipt ion

E x a m p l e s

Delete a tracepoint or watchpoint setting

Point Delete <number>

Shortcut Equivalent

Abbreviat ion P D

Accelerator key Alt +P , D

Synonyms Delete TP, Delete W P

The number of the individual watchpoint or tracepoint to delete.If <mimber> is not specified on the com ma nd line, Point Deleteopens a dialog box to prom pt you for a num ber.

Point Delete allows you to delete a single watchpoint ortracepoint by specifying i ts associated num ber. The num ber thatyou specify appears to the left of the watchpoint or tracepointdefini t ion in the W atch win dow . Alternat ively, you could useList TP or List WP to show the numbers and point definitions inthe Com mand window.

For a detailed explanation of tracepoints and watchpoints, seeDeb ugg ing a Prog ram earl ier in this chapter.

This example deletes the first watchpoint or tracepoint defined inthe Watch window:Point Delete 0

See AlsoDelete, List, Point Tracepoint, Point Watchpoint

13-102 CA-Clipper



M e n u C o m m a n d R e fe re n c e

Point Tracepoint

Purpose

Syntax

A rg u m e n t s

<exp>

Descr ipt ion

E x a m p l e s

Specify an exp ression as a t racepoint

Point Tracepoint <exp>

Shortcut Equivalent

Abbrevia t ion P T

Accelerator key Alt +P , Τ

Synonym TP

An expression of any data type to be traced. The expression canbe as simple as a field or variable name, or it can be morecom plex, including function cal ls and operators . I f <exp> is no tspecif ied on the command l ine, Point Tracepoint opens a dialogbox to prom pt you for an exp ression.

Point Tracepoint designates the specif ied expression as atracepoint . The tracepoint is then added to the W atch w ind ow ,

along with i ts type, value, and the abbreviat ion "t p ."A tracepoint can be thought of as a condit ional breakpo int . Thetwo are very similar, except that a tracepoint halts programexecution as soon as i ts value change s. For more information ontracepoints , see Debu gging a Program earl ier in this chapter.

This example halts execution as soon as the value of the variablenlnvNum changes :

Point Tracepoint nlnvNum

This pau ses wh en en d of f ile is reache d:Point Tracepoint EOF()

This example halts as soon as the value of i exceed s 10 and isvery useful in looping operat ions:

Point Tracepoint i > 10

See Also Delete, Point Breakpo int , Point Delete, Point W atchp oint





Point W atchp oint

Purpose

Syntax

A rg u m e n t s

<exp>

Descr ipt ion

E x a m p l e s

Specify an expression as a watch point

Point Watchpoint <exp>

Shortcut Equivalent

Abbreviat ion P W

Accelerator key Alt +P , W

Synonym W P

An expression of any data type to be watche d. The expressioncan be as simple as a field or variable name, or it can be morecom plex, including fun ction calls and operators . I f <exp> is notspecif ied on the com ma nd l ine, Point Watchp oint opens a d ialogbox to prompt you for an expression.

Point Watch point designates the specif ied expression as awa tchp oint. Th e wa tchp oint is then add ed to the list in theW atch w ind ow , along with its type, value, and the abbreviat ion" w p . " As each line of the current prog ram is exe cute d, the valueof the watc hpoin t is upda ted in the Watch win dow .

A watchpoint is identical to a tracepoint, except that it does notcause a break in program execution every t ime i ts value ch anges.For more information on watchpoints , see Debugging a Programearlier in this chapter.

This example specifies the field CustNum as a wa tchpo int:

Point Watchpoint CustNum

In this example, the current record number is displayed as eachline of code is executed:

Point Watchpoint RECNO()

See Also Delete, Point Breakpoint, Point Delete, Point Tracepoint

13-104 CA-Clipper




Run Anim ate

Purpose

Syntax

Descr ip t ion

Run applicat ion in animate mode

Run Animate


Abbreviat ion R A

Accelerator key Al t+R , A

Synonym Anima te

In animate mo de, the debugg er executes a s ingle l ine, m oves theexecu tion bar to the next line, exec utes it , and so on. If Opt ion sExchange Screens is on ( indicated by a checkmark) , the output ofeach line is displayed after the line has been executed.

Execution continues in this ma nner u nt i l a breakp oint ortracep oint is reac hed . To contro l the speed of this pro cess, usethe Run Speed co m m and . Press any key to s top execution.

For more information on execution modes, see Debugging aProg ram earl ier in this chapter.

See Also Run Speed





Run G o

Purpose

Syntax

Descr ip t ion

E x a m p l e s

Execute the applicat ion in run mode

Run Go

Shortcut Equivalent

Abbreviat ion R G

Accelerator key Al t+R, G

Shortcut key F5

Synonym G o

See Also

Run Go displays your applicat ion screen and executes theapplication until a breakpoint or tracepoint is reached, or untilthe debugg er is del iberately invok ed ( that is , by pressing Al t+Dor using AL TD ()) . At that point , the debugger screen isredisplayed and program execution hal ts .

This is kno wn as run mod e. Using Ru n Go again causes theapplication to be executed from the current position to the nextbrea kp oin t or tracep oint. To reload the app lication so that i t can

be executed fro m the beginning, use Run Restar t .

For more information on modes of execution and the use ofbreakpoints and tracepoints , see Debugging a Program earl ier inthis chapter.

Assu min g break poin ts have been set a t l ines 15 and 30 of thecurrent program, the fol lowing command executes theapplication as far as line 15:

Run Go

Entering Run Go again executes up to line 30, and so on.

Run Next , Run Restar t , Run To

13-106 CA-Clipper




Run N ext

Purpose

Syntax

Descr ip t ion

Examples

Execute the application in run mode up to the start of the nextactivation

Run Next


Abbrevia tion R N

Accelerator key Alt +R , Ν

Shortcut key Ctr l+F5

See Also

Run Ne xt displays your applicat ion screen and executes theapplication until i t reaches line zero of the next activation (that is,funct ion, proce dure, code block, or me ssage send). Theapplication is executed in run mode until that point is reached.This is equivalent to set t ing a t racepoint of "PRO CL INE () = 0 .

Assuming the current program contains its first function call online 15, the following command executes the application as far asline 15:

Run Next

Entering Run Next again executes up to the next activation.

Run Go, Run Restart , Run To





Run Restart

Purpose

Syntax

Descr ip t ion

E x a m p l e s

Reload the current applicat ion

Run Restar t


Abbreviat ion R R

Accelerator key Alt+ R, R

Synonym Res tar t

See Also

Run Restart reloads the current application in preparation to bere-executed, keeping intact a l l debugger set t ings. This commandis the only way to execute an applicat ion wh ich has already beenrun.

In this example, the current application is executed:

Run Go

If errors are discovered, you may want to make changes and runthe applicat ion again:

Run Restart

Run Next , Run Go

13-108 CA-Clipper




Run Sp eed

Purpose

Syntax

A rg u m e n t s

<delay>

Descr ip t ion

Set s tep delay for animate mode

Run Speed <delay>

Shortcut Equivalent

Abbrevia t ion R S p

Acce lerator key Al t+R , Ρ

Synonym Speed

The increm ent of delay for animation in tenths of second s. I f<delay> is not specif ied, Run Spee d opens a dialog box w hichdisplays the current setting and allows you to enter a new one.

Run Speed controls the speed of display while in animate mode(for an explanat ion of this mode, see Debugging a Programearlier in this cha pte r). Re m em ber that this setting is expre ssedin tenths of seconds so that smaller settings are faster than largerones.

See Also Run Animate

Pro gram ming an d Utilit ies G uid e 13-109




Run Step

Purpose

Syntax

Descr ip t ion

E x a m p l e s

Execute the current program in single s tep m ode

Run Step

Shortcut Equivalent

Abbreviat ion R S

Accelerator key Al t+R, S

Shortcut key F8

Synonym Step

See Also

In single step mode, the debugger executes the line of code at theexecution bar, moves the execution bar to the next line, andstops. As functio ns are called by the curren t pro gram , their codeis displayed in the Code window.

This example executes the next line of the application beingdebu gged . The debu gger s tops with the execution bar on thenext line to be executed:

Run Step

Options Codeblock, Run Trace

13-110 CA-Clipper




Run To

Purpose

Syntax

Descr ip t ion

Execute the current program up to the current cursor position

Run To

Shortcut Equivalent

Abbreviat ion R To

Accelerator key Alt+ R, C

Shortcut key F7

Run To executes only those lines of code up to the line indicatedby the current cursor posi t ion in the Cod e windo w. Theapplication is executed in run mode until that l ine is reached.

If the line indicated by the current cursor position is neverexecuted, the debugger continues to the end of the application.

See Also Run Go, Run Next





Run Trace

Purpose Execu te the current prog ram in t race mo de

Syntax Run Trace


Abbrevia t ion R T

Accelerator key Al t+R, Τ

Shortcut key F10

Descr ip t ion Th e Ru n Trace com m an d is similar to Ru n Step in that i t execu tesone l ine of prog ram co de at a t ime. Ho we ver, Run Trace doesnot display the code for functions called by the current program.

See Also Run Step

View

Purpose Exam ine a f i le in the Co de win dow during the currentdebugging session

Syntax View <idFileName>

A rg u m e n t s

<idFileName> The nam e of the f i le you wan t to exam ine. Unless one isexplicitly specified as part of <idFileName>, no exten sion isassumed. I f <idFileName> is not specified on the com m an d line,View opens a dialog box to prompt you for a f i lename.

13-112 CA-Clipper




Descr ip t ion View allow s you to look at other files with out leaving the curren tdeb ugg ing session. It can also be used to view hea der filesspecified with the #inc lud e prep rocess or directive. Break poin ts

can be set and are saved when you return to the originalprogram.

Unless you have defined a source file search path with theOptions Path command, View searches for <idFileName> in thecurren t directory only. If, ho w eve r, you have defined a searchpath, the directories in the path are searched in order until thefile is found.

When you view a file with View, the current program is cleared

from the Code window and the new file is displayed in its place.To continue with the original program, use File Resume.

N o t e : View is almost ident ical to the Fi le Op en com ma nd. Theonly difference between these two comm and s is that Fi le O penassumes a (.prg) extension, whereas View assumes no f i leextension.

E x a m p l e s To view ListDbfs.prg:

View ListDbfs.prg

To view another file, PrintDbf.prg, before returning to theoriginal program:

View PrintDbf.prg

See Also Fi le Op en, Fi le Resu me , Options Path




Menu Com man d Refe rence

View App

Purpose

Syntax

Descr ip t ion

Display program output

View App

Shortcut Equivalent

Abbreviat ion V A

Accelerator key Al t+V , A

Shortcu t key F4

Synonym Output

View A pp tem porari ly clears the debugger screen and displaysyou r application scre en in its place. This allows you to see theoutp ut of the application itself. To return to the debugg er, pressany key.

13-114 CA-Clipper




View Callstack

Purpose Control the Cal ls tack window

Syntax View Calls tack


Abbreviat ion v

Accelerator key Al t+V, C

Descr ip t ion View Callstack acts as a toggle by changing the current status of

the Cal ls tack wind ow . By defaul t , View Calls tack is off, me anin gthat the Cal ls tack wind ow is c losed.

The Cal ls tack win dow contains a lis t of pend ing act ivat ions w iththe current activation at the top. For more information on thecall stack, see Debugging a Program earlier in this chapter.

View Callstack is functionally equivalent to the Callstackcommand specif ied without an opt ion.

E x a m p l e s To change the current s ta tus of the Cal ls tack window:

View Callstack

See Also Calls tack





View Sets

Purpose Display the View Sets win dow

Syn tax View Sets

Shortcut Equivalent

Abbrevia t ion v s

Accelerator key Al t+V, S

Descr ip t ion View Sets act ivates the View Sets win dow . W hen this win dow isact ive, you can view and chan ge the s tatus of the CA -Clipper

system settings.

For information on using the View Sets window, see TheDebugger Display ear l ier in this chapter.

Se e Also Opt ions Color, View Wo rkareas

13-116 CA-Clipper




View Workareas

Purpose

Syntax

Descr ip t ion

Display the View W orkareas wind ow

View Workareas


Abbreviat ion V w

Accelerator key Al t+V, W

Shortcut key F6

View Workareas ac t iva tes the View W orkareas window . Thiswindow al lows you to view information regarding al l databasefiles that are currently in use.

For information on using the View Workareas window, see TheDeb ugger Display ear l ier in this chapter.

See Also Options Color, View Sets

Pro gram min g a n d Util it ies Gu ide 13-11 >




Window Iconize

Purpose Toggle ac tive debugger wind ow be tween icon and windo wdisplay

Syn tax W indow Iconize

Shortcut Equivalent

Abbrevia t ion W I

Accelerator key Al t+W, I

Descr ip t ion Window Iconize reduces the act ive window to an icon ( i ts name).

This command acts as a toggle between the icon and windowdisplay modes so that when the act ive window is iconized,execut ing Window Iconize resumes the or iginal window display.

A window that is iconized remains open, but you cannot see thewindow contents . Certain window operat ions such as moving,however, are possible .

E x a m p l e s To iconize the act ive window:

Window Iconize

See Also Windo w M ove , W indow S ize , Window Ti le , Window Zoom

13-118 CA-Cl ipper



M e n u C o m m a n d R e f e r e n c e

Window Move

Purpose Move the act ive debugger window

Syntax Window Move

Shortcut Equivalent

Accelera tor key Al t+W , Μ

Abbrev ia t ion W M

Description Window Move al lows you to move the act ive window around on

the screen. W hen yo u execute this com ma nd, the border of theactive window changes to a different pattern and the cursor keysare used to mo ve the win dow . Enter comp letes the mo vingprocess.

N o t e : You cannot mov e a win dow that is zoom ed to ful l -screen.

Examples To move the act ive window:

Window Move

See Also Window Iconize , Window Size , Window Ti le , Window Zoom

Window Next

Purpose Select the next debug ger win dow

Syntax Wind ow Next

See Also

Shortcut Equivalent

Abbrev ia t ion W N

Accelera tor key Al t+ W , Ν

Shortcut key Tab

Window Prev

Prog ram ming an d Utilities Gu ide 13-119




Window Prev

Purpose Select the previous debu^ ger win dow

Syntax Window Prev

Shortcut Equivalent

Abbreviat ion W P

Accelerator key Al t+W, Ρ

Shortcut key Shi f t+Tab

See Also Window Next

Window Size

Purpose Change the s ize of the act ive debugger window

Syntax Window Size

Shortcut Equivalent

Abbreviat ion w s

Accelerator key Al t+W , S

Descr ip t ion Window Size al lows you to change both the height and thewidth of the act ive window. When you execute this command,the border of the active window changes to a different patternand the cursor keys are used to change the size of the window.Enter completes the sizing process.

N o t e : You cann ot size a w ind ow that is zoo me d to full-screen.

E x a m p l e s To size the act ive window:

Window Size

See Also Window Iconize , Window Move, Window Ti le , Window Zoom

13-120 CA-Clipper




Window Tile

Purpose Restore debug ger win dow s to defaul t s ize and locat ion

Syntax Wind ow Ti le

Shortcut Equivalent

Abbrev ia t ion W T

Accelera tor key Al t+W , Τ

Description Window Tile provides a quick way to clean up the debugger

screen by restoring each window to its default location and size.Any windows that have been zoomed or iconized are alsorestored to the original window display mode.

Examples To restore debugger windows:

Window Tile

See Also Wind ow Iconize , Wind ow Mo ve, Wind ow Size , Wind ow Zoo m

Prog ram ming an d Utilit ies Gu ide 13-121




Window Zoom

Purpose Toggle ac tive debugger windo w be tween window andfull-screen display

Syntax Window Zoom

Shortcut Equivalent

Abbreviat ion w z

Accelerator key Al t+W, Ζ

Shortcut key F2

Descr ip t ion Window Zoom al lows you to zoom the act ive window toful l-screen. This comm and acts as a toggle betw een theful l-screen and window display modes so that when the act ivewindow is zoomed to ful l -screen, executing Window Zoomresumes the original window display.

N o t e : W hen a windo w is zoom ed, some window opera t ions ,such as moving and sizing, are not al low ed.

E x a m p l e s To zoom the act ive window to ful l -screen:

Window Zoom

See Also Win dow Iconize , W indow Mo ve, Win dow Size , Wind ow Ti le

13-122 CA-Clipper



Chapter 14

Program Maintenance—RMAKE.EXE


CA-Clipper provides a program maintenance faci l i ty withRM AK E.EXE . RM AK E is a pow erfu l too l for keeping program sinvolving several source, header, object, and library files up-to-date. It does this by com pa ring the date and time stamp s of filesrelated to one another and performing a series of actions if theydo not match .

A make facility is generally used to speed the process ofcompil ing a program system composed of several source f i les bycompiling only those files that have changed since the last

program bui ld .

This chapter describes the operat ion of RMAKE. The fol lowinggeneral subjects are covered:

• Invoking RM AK E

• The RM AK E envi ronment var iab le

• RM AK E opt ions

• How RM AKE works

• Ho w RM AK E searches for f i les• Th e m ake file




Invok ing RMAKE

Invoking RMAKE

If you installed the default configuration of the CA-Clipperdevelopment system, RMAKE.EXE is located in the\CLIP53\BIN directory. To execute RM AK E from DOS, use thefol lowing syntax:

RMAKE [<makeFile list>] [<macroDef list>][<option list>]

<makeFile list> is a list (separated b y spaces) of one or m ore m akefiles to proc ess. If no extensio n is specified , ( .RMK ) is assum ed.Each f i lenam e can opt ional ly includ e a dr ive designator and apath referen ce. Yo u can specify a m ax im um of 16 files in the<makeFile list>.

<macroDef list> is a list of one or m ore m acro d efinitions of theform <macroName>=[<value>]. If yo u specify m ore than onem acro defin ition, separate them with a space . If you define ama cro on the com ma nd l ine, you canno t redefine it in the mak efile with ou t first und efinin g it. In this w ay, com m an d linemacros take precedence over make f i le macros of the same name.

<option list> is a list of one or m ore op tions to control the courseof the ma ke. All avai lable opt ions are discussed under R M AK E

Op tions later in this chapter. To get a list of options, specify theRMAKE command l ine wi th no arguments .

Like all other CA -Clipp er ut i l i ties , you can execute RM AK E fromany drive or directory since the appropriate directory was placedin the PATH list during installation.

14-2 CA-Clipper

http://clip53/BIN

http://clip53/BIN



The RMAKE Environment Va riab le

The RMAKE Environment V a ria b le

In addit ion to specifying opt ions on the RMAKE command l ine,you can specify them using the RMAKE environment variable.To def ine RM AK E, use the DO S SET comm and as fo llows:

SET RMAKE=[<option list>]

<option list> is a list of one or m ore op tions that is read andprocessed each t ime RMAKE is invoked. You specify theseoptions just as you would on the RMAKE command l ine.

To save yourself f rom having to enter this SET command

repeatedly, you can place i t in your AUTOEXEC.BAT fi le wherei t wil l be processe d au tomatical ly each t ime you reset you rcomputer.

The fo l lowing exam ple causes RM AK E to d isp lay warningmessages and debugging information:

SET RMAKE=/W /B

N o t e : In addit ion to com m and l ine opt ions, you can use theRMAKE environment variable to specify one or more make f i les ,

just as you can on the RMAKE command l ine. You cannot ,however, define macros l ike you can on the command l inebecause the DOS SET syntax does not permit using an equalsign—use the /D option instead.




RMAKE Options

RMAKE Options

The options described in this section control the behavior of

RM AK E. As already discussed, you can specify opt ions on theRMAKE command l ine and in the RMAKE envi ronmentvariable. Co m m an d l ine opt ions take precede nce i f there is aconflict.

All opt ions are shown in uppercase preceded by a s lash ( / ) .No te , how ever, that opt ions are not case-sensit ive and that youcan replace the slash with a dash (-) if you prefer.

Som e options have argum ents . I f an opt ion has argumen ts ,specify them after the opt ion, with no space between the opt ionand its first argument.

/B Displays debu gging informa tion.

/ D /O<macroName>[:<value>]

Defines a macro an d an opt ional value. I f you do not supply thevalue , the macro is defined w ith a nul l value.

As with command l ine macros, i f you define a macro using the

/D option, you cannot redefine it in the make file without firstundefining i t . In this way, /D macros take precedence overmake f i le macros of the same name.

/F Forces RM AK E to perfo rm al l act ions defined in the ma ke f i le(s)without regard to the date and time stamps of the files in thedependency and inference rules (see How RMAKE Works laterin this chapter for mo re inform ation) . In other w ord s, theapplicat ion w il l be rebuil t , regardless of whether yo u h aveupdated any files since the last build.

14-4 CA-Clipper



RMAKE Options

/I Cause s RM AK E to continue if a com ma nd executed from themake file causes an error (that is, a DOS return code greater thanzero) . By default, errors of this natu re halt the m ak e proc ess.Note that fatal errors produced by RMAKE terminate the makeprocess, regardless of / I .

/N Displays the com ma nd s to be executed withou t actual lyexecuting them.

/Q Prevents the RM AK E copyright me ssage from displaying.

/U Ena bles the # char acter as a com me nt indicator . If this option isspecif ied, you m ust preced e ma ke f i le direct ives (explained in

the Directive s section later in this chapter) by the exclam ation ( )symbol instead of the hash (#) symbol.

/W Displays warn ing mess ages wh ile processing.

/XS /XS<nwnSymbols>

Sets the size of the internal sym bol table. The de fault size is 500symbols.

/X W /XW<numBytes>

Sets the size of the internal work spa ce. The de fault size is 2048bytes.




How RMAKE Works

How RMAKE Works

If you are famil iar with UN IX M ake , you will probably f ind

RMAKE easy to understand and use. General ly, i t is upwardlycom patible with U NIX M ake and w il l, in most cases, successful lyprocess UNIX make f i les; however, RMAKE provides severaladditional features.

In general , you describe you r program in terms of dep enden cyrules using a text file called a m ake file. The n, instead ofdetermining the compiling and linking steps to build theprogram each time you make a change to a source file, you useRM AK E w ith one or mo re make f i les designed for that part icularprogram.

RMAKE performs only the compil ing and l inking stepsnecessary to bring the executable version of the program up-to-date.

The basic element of a make system is the dependency ruleconsisting of a dependency statement that establishes a relationshipbetween a target file and a series of dependent files. Thedepe nden cy statement is then fol lowed by a series of actions toupdate the target file if any of its dependent files are more

recent.

RM A KE is a two-pass sy stem. The f irs t pass, cal led the parsingphase, parses the make files. The second pass, called the makephase, examines the dependency rules and performs thenecessary actions .

Parsing Phase W hen invok ed, RM AK E firs t performs the parsing phase byprocessing each make file sequentially in the order encountered.Files specif ied on the RMAKE command l ine are processed from

left to right. All file search ing is perfo rm ed d uring the parsingph ase, and all inferen ce rules are applied. If ma cros or rules areredefined , the new defini t ions ap ply to the d ependen ciesspecified after them.

14-6 CA-Clipper



How RMAKE Works

Make Phase After the parsing pha se, RM AK E perform s the ma ke phaseduring which all of the rules defined in all of the files are appliedin order to pro du ce the target files. For each rule in the ma ke

file, the date of the target file is compared to the ciate of eachdep end ent file. If any dep end ent file has a m ore recent date andtime stamp than its associated target file, the accompanyingaction s are exec uted . If no ne of the dep end ent files hav e beenchanged since the target file was last updated, the rule isbypassed and the process is repeated for the next rule.

N o t e : I f you specify the /F opt ion, al l act ions are perform edregardless of the date and time stamps of the files specified inthe dependency and inference rules .

RMAKE correct ly handles the case where two input f i les definedep end enci es (and pos sibly actions) for the sam e target. Italways builds all target files to ensure that multiple-specifiedtargets (for example, .LIB files) are not time stamped before allma ke f i les get a chanc e to specify dependen cies . Although nopart icular order is guaranteed during the make phase, RMAKEdoes guarantee that no target will be built until all of itsdependencies have been bui l t .

Error Handling W hen RM AK E terminates , i t sets the DO S return code to indicatethe state of the m ak e pro cess at term inatio n. A return cod e of 0means that the make was successful (that is, there were noerrors), and a return code of 1 me ans that errors w ereencountered during processing.

You can test the RMAKE return code within a batch f i le usingthe DOS ERRORLEVEL condi t ion . For example :

RMAKE RLIF ERRORLEVEL 1 GOTO ERROR

.<commands>

GOTO END:ERROR

.<commands>

: END




How RMAKE Searches for Files

How RMAKE Se arc he s for Files

There are only a few types of files that serve as input to RMAKE.This section describes each input file type and any special rulesgoverning how RMAKE searches for f i les of that type.

Make Files

W hen RM AK E is fi rst executed, it a t tempts to locate the makefi les specif ied on the command l ine and in the RMAKEenviro nm ent variable. By defaul t , these f i les are assum ed tohave an extension of .RMK, which you can overr ide byspecifying another extension as part of the ma ke f i lenam e. Toindicate a file with no extension, include a period at the end ofthe f i lenam e.

You can specify a full or partial path as part of any makefilename to force RMAKE to look for the file in a particular drivean d /o r directory. I f you specify no path, RM AK E searches onlythe current directory.

Target and Dependency Files

In addit ion to f inding make f i les , RMAKE must f ind the targetand dependency f i les referenced in dependency statements inthe ma ke f i le. By defaul t , RM AK E searches only the currentdirectory for these files. However, there are special macros thatyou can define to specify wh ere target and depen dency f i les areto be found an d /o r created. The form of these special macrodefinitions is:

makepath[. <extension>] = <pathSpec>

<exten$ion> specifies the file type and <pathSpec> specifies one ormore paths to be searched when trying to find or create files of

the given type. To avoid problems with the backslash (\)character in a make file, enclose the path list in quotes as in thefol lowing examples.

14-8 CA-Clipper



How RMAKE Searches for Files

If you define a makepath macro for a particular file type, thecurrent directory is not searched unless it is explicitly included inthe <pathSpec>. On ly the paths specified in the <pathSpec> are

searched, and they are searched in the order specified during theparsing phase.

If a file is not found along any of those paths, RMAKE attachesthe path at the front of the list to the filenam e. For a target file,this mean s that the first path in the list for its file type dete rm ineswhere the f i le is created when the make act ions are performed.For depend ent f i les , i t mea ns that RM AK E w il l not be able tofind the file and will result in an error.

You can spec i fy makepath macros on the RMAKE commandline, in the RMAKE environment variable (using the /D option) ,and in make f i les . Some examples fol low:

makepath[.h] = "C: \CLIP53 \SOURCE;C: \CLIP53\ INCLUDE"makepath[.obj] = "C: \CLIP53\ OBJ"makepath[.lib] = "C: \CLIP53\ LIB;C: \MSC\LIB" makepath[.exe] = " C:\CLIP53\BIN"

To access a ma kepa th m acro in a ma ke f i le , enclose the m acronam e in parenth eses precede d by a dol lar s ign. This is thestandard m ake f i le syntax for accessing ma cro values. Forexam ple, to aug me nt a path l is t:

makepath[.h] := "C:\MSC\INCLUDE;$(make path[.h])"

No te that here you use the im med iate assignm ent operator ( :=)rather than the assignment operator (=) that you used toorigina lly create the m acr o. This is to prev ent the norm al d elaythat would occur in expanding the referenced makepath[ .h]m acro . (See the M acro s section later in this chap ter for mo reinformation.)

Pro gram ming a n d Utilit ies G uid e 14-9

http://clip53/

http://source/

http://clip53/

http://clip53/

http://clip53/

http://msc/LIB

http://c/CLIP53/BIN

http://c/CLIP53/BIN

http://msc/LIB

http://clip53/

http://clip53/

http://clip53/

http://source/

http://clip53/



The Make File

If you specify target and dependency files with a path as part ofthe f i lename, RMAKE searches only the explici t ly nameddirectory regardless of the existence of an appropriate ma kepathmacro .

N o t e : Act ions are executed during the ma ke phase and thushav e no effect on file search es. This me an s, for exa mp le, thatyou cannot have an action line that places a file in a subdirectoryspecified with a path name with the intent of triggering asubsequent dependency rule .

The Make File

The fun dam ental e lem ent of a m ake system is the make f i le , anAS CII text file created w ith a stand ard text editor. This filedefines which files update other files and the update actions toperform w hen f i les are out-of-date . W ith a typical CA-C lipperpro gram , a ma ke f i le l ists the program and header f i les requiredto create each object file and all the object files necessary to createthe executable file. The make file also lists the commandsrequired to build each file.

A m ake f i le consis ts of the fol lowing basic co mp onen ts:• Dependency rules that define how each file is built

• Inference rules that define what to do if a dependency rule hasno accompany ing ac t ions

• Macros that a l low variable information to be used wh enconstruct ing rules

• Directives that allow yo u to further control the m ann er inwhich the make f i le is processed

14-10 CA-Clipper



The Make File

Using Quotation Marks

There are instances when quote marks are necessary to forceR M A K E no t to interpret cer tain symbols as commands. You canuse either single or double quotes.

For instance, both the colon and the backslash have specialmeaning to RMAKE; therefore, when you specify a f i lenamewith a dr ive and/or path specif icat ion in a dependency orinference rule , you m ust enclose the f i lename in quotes . An othe rinstance is a m acro na me defini t ion containing these same orother special symbo ls . As a general pr inciple , use qu oteswh enev er you are in doubt , s ince they are never interpreted

literally.

N o t e : Using quo tat ion marks does not affect the ma nner inwhich RMAKE interprets the macro character ($) . Macros areexpanded both inside and outside of quotes .

Line C ontinuation

You can continue a ny com me nt, rule , or act ion in a ma ke f i le to

the next line w ith a bac ksla sh (\) cha racter at the end of a line. Ifthere is a com me nt on a continued l ine, you mu st place i t af terthe continuat ion symbol. For example:

TEST.OBJ: Test1.prg Test2.prg \ // line continuedTest3.prg Test4.prg

CLIPPER ©Test, d p

Pro gram m ing an d Utilit ies G uid e 14-11



The Make File

Comments

You can specify comments in a make file using C-style inlinecomment s ( / * . . . * / ) or C-style l ine com men ts ( / / ) or, i f you usethe /U option, UNIX make-style comments (#) . You can place acomment on a line by itself or embedded at the end of acommand l ine in a dependency rule . For example:

/* This is a comment line */TEST.OBJ: Test.prg

CLIPPER Test.prg // This is an embedded comment

You cannot nest comments .

De pen den cy RulesThe key co mp onen t of the ma ke f i le is the dependency rule whichconsists of a dependency statement fol lowed by one or moreact ions. The depen denc y statement establishes a relat ionshipbetween a target file and one or more dependent files. If any ofthe depend ent f i les has a date and t ime stamp new er than thetarget file, the actions that follow the dependency statement areperform ed to bring the target fi le up-to-date.

N o t e : If yo u specify the / F op tion, all actions are perf orm edregardless of the date and time stamps of the files specified inthe dependency statement .

A dependency rule has the fol lowing basic form:

<targetFile>: <dependentFile list>[<action>][<action>]...

You can specify up to 128 files in the <dependentFile list>. Youcan specify up to 32 <action> l ines per depen dency rule ,

provided that the maximum number of bytes in al l <action> linesdoes not exceed 1024.

14-12 CA-Clipper



The Make File

M a k e p a t h E x a m p l e s

You can specify any filename that is part of a dependency rulewith a path and d rive reference. If you spe cify no path or drive ,RM AK E assu mes the current directory or the path l ist defined bythe appropriate makepath macro (see How RMAKE Searches forFiles earlier in this cha pter for m ore inform ation ). Use quo tes todelimit a filename that contains special characters—since thecolon has special mean ing in a depen dency rule, you mu stenclose any filename with a drive letter in quotes. You mustspecify extensions for all filenames in a dependency rule.

The <targetFile> is the na m e of the file to build follow ed by a

colon and at least one spa ce. For exam ple, this target file is builtin the current directory:

MYAPP.ΕΧΕ: ΜΥΟΒJ.OBJ BIOS.OBJ

This target file is built in the specified directory:

" C:\CLIP53\APPS\MYAPP.EXE": ΜΥΟΒJ.OBJ BIOS.OBJ

T he <dependentFile list> is a list of one or m ore filenam esseparated by spaces. The fol lowing dependency statementdefines two dependent files:

MYAPP. ΕΧΕ: ΜΥΟΒ J . OB J 11 \ CLIP53 \ OBJ \ IBM\BIOS . OBJ"

RMAKE searches for MYOBJ.OBJ in the current directory and forBIOS.OBJ in the\CLIP53\OBJ\ IBM directory of the currentdrive.

The <action> s tatements are val id DO S com m and l ines witharguments. You must place each <action> on a line by itself an dm ust indent it using spa ces or tab char acters. Th e action linesare assumed to end at the first l ine that is not indented, but you

can also terminate them using a blank line.


http://c/CLIP53/APPS/MYAPP.EXE

http://clip53/

http://clip53/OBJ/IBM

http://clip53/OBJ/IBM

http://clip53/

http://c/CLIP53/APPS/MYAPP.EXE



The Make File

N o t e : If you specify no <actions>, you should create acorre spo ndi ng infere nce rule that defines the actions to take. SeeInference Rules below for more information.

Tip: Because RMAKE genera tes DOS executable commandsfrom them, act ion l ines cannot exceed the DOS commandline limit of 128 cha racters. This is particu larly imp ortant ifthe action line contains macros because the limit appliesafter macro expansion (see the Macros section later in thischapter for mo re information ) . For examp le, i f an executablefile depends on a large number of object files, the action lineto link the object files m ay be too long. In this case, you cancreate a linker script file (.LNK) containing the list of

dependent object files to link and use the script file in placeof the object file list on the linker action line. A goo dexample of linking with a script file can be found in theDBU.RMK make f i le loca ted in the \CLIP53\SOURCE\DBUdirectory.

The fol lowing dependency rule recompiles Test .prg only i fsom eone has changed i t s ince i t w as last com piled. RM AK Eaccomplishes this by comparing Test .prg to i ts correspondingobject f ile , TES T.OB J, and perform ing the compilat ion o nly i f the

date and time stamp for the source file is more recent than that ofthe object file:

TEST.OBJ: Test.prgCLIPPER Test

Likewise, you can create the target .EXE file with a similardependency ru le . This example assumes tha t WINDOW.OBJmust also be linked to create the executable file. The rule tocreate TEST.EX E wh en e i ther TEST.OB J or W IND OW .OBJ i smore recent is as follows:

TEST.EXE: TEST.OBJ WINDOW.OBJEXOSPACE FILE TEST, WINDOW

14-14 CA-Clipper



The Make File

Error Handling It is not nec essa ry for each <action> to result in the creation of atarget file. In fact, after the action s are exe cu ted , RM A KE do esnot verify that the target f i le wa s successful ly created. H ow ever ,RMAKE does check the DOS ERRORLEVEL var iab le uponcom plet ion of each i tem in the <action> list.

I f i t contains a non zero valu e, RM AK E w il l hal t processing andprod uce an error m essage . The CA -Clipp er com piler and mo stl inkers properly set ERRORLEVEL so that RMAKE wil l hal t inthe event that any errors are en coun tered.

N o t e : Y o u can disable this default error processing using the /Iopt ion. With this opt ion, RMAKE does not s top when DOS's

ER RO RL EV EL is set . Instead, i t cont inu es processing as i fnoth ing had happened .

Inference Rules

A n inference rule specif ies a ser ies of act ions for a dep end encystatem ent that is no t follo w ed by an action list . Yo u can use it asa shortcut to perform the same set of actions for several differentdep end ency statements . The basic form of an inference rule is as

fol lows:.<dependentExtension>.< targetExtension>:

[<action>][<action>].. .

In comparison with a dependency statement , you specify aninference rule with the order of the target and dependent filereversed. You can specify up to 32 <action> l ines per infere ncerule, provided that the maximum number of bytes in al l <action>l ines does not exceed 1024.

When RMAKE encounters a dependency s ta tement wi thout anaction list , i t searches for an inference rule that matches theextensions of the target and dependent f i les in the dependencystatement . I f an inference rule is foun d, RM A KE p erform s theaccomp anying ac t ions , inc luding expanding any macros .




The Make File

When searching for an inference rule, the actual filenames in thedependency statement are insignif icant—only the extensions arecom pare d. If a dep end ency statem ent refers to mo re than onede pe nd en t file, the ex ten sion o f the first file in the list is us ed . Ifthe extensions match, the rule applies.

As in a dependency rule, the <action> statements are val id DO Scom m and l ines with argum ents. You must place each <action>on a line by itself and must indent it using spaces or tabcha racter s. Th e action lines are assu m ed to end at the first l inethat is not indented, but you can also terminate th em using ablank line.

For exam ple, the fol lowing inference rule compiles a s ingle (.prg)

file defined in a dependency statement to an .OBJ file:.prg.obj:

CLIPPER $< /Μ /N

N o t e : The $< sym bol on the com piler com ma nd l ine is apredefined RMAKE macro described in the Macros sect ion laterin this cha pter. Bas ically, i t caus es the dep end ent filenam e to besubs tituted on the com m an d line. It is espec ially useful ininference rules because you usual ly have no way of knowingwhich dependency statement t r iggered the rule.

Using an inference rule such as this one, you could specify eachindividual object /source in your applicat ion as a separatedependency s ta tement :

RLFRONT.OBJ: Rlfront.prgRLBACK.OBJ: Rlback.prgRLDIALG.OBJ: Rldialg.prg

The resulting action would be to compile only .prg files withoutdated .OBJ counterparts .

14-16 CA-Clipper



The Make File

You can see that this is easier than specifying equivalentdep ende ncy rules, as in:

RLFRONT.OBJ: Rlfront.prgCLIPPER Rlfront /Μ /N

RLBACK.OBJ: Rlback.prgCLIPPER Rlback /Μ /N

RLDIALG.OBJ: Rldialg.prgCLIPPER Rldialg /Μ /N

Using an inference rule, you not only save on the number of linesin the m ak e file, bu t you also m ak e it easier to m aintain . Forexample, if you add a source file to your application, you addonly one line (the dependency statement) to the make file insteadof two.

Setting Environment Variables

If an action line in either a dependency or an inference rulecontains a DOS SET command, i t is interpreted direct ly byRMAKE during the make phase rather than being passed to theDO S com m and p rocessor l ike other act ion lines. This allows y outo set env iron m ent varia bles as part of an action. For exa m ple :

.prg.obj:

SET CLIPPERCMD=/M /NCLIPPER $<

Each program that runs under DOS receives a local copy of theDO S environment var iab les . RM AK E al lows you to mak echanges to its copy so that programs in action lines can inherit amo dified environm ent. An y chan ges ma de are discarded onceRM AK E terminates. (Like most programs, RM AK E is unable tochange i ts parent 's environment.)

If RM A KE sees a DOS c om m and in an act ion lis t, i t s imply shel ls

to execute the com m and . Ho we ver, the DO S shell does notinheri t the modif ied environment, so the lone SET commandbelow displays the INCLUDE set t ing prior to running RMAKE:

.prg.obj:SET INCLUDE=$(makepath[.ch])SET // << THIS COMMANDCLIPPER $<




The Make File

The SE T com m and is internal to DO S (there is noSET.COM orSET.EXE file). Therefore, SET can access only the initial (DOS)copy of the environ men t. Ho we ver, CA-Clipper wil l see the newsetting of INCLUDE because it is an application in its own rightand wil l inheri t a copy of RMAKE's modif ied environment.

Therefore, if you are distributing a make file, you do not have toma ke any assum ptions about the environm ent. Simp ly set upeverything you need in the make file and trust that the user 'senvironment wil l be undisturbed when the make process iscomplete.

You can access any env ironm ent variable in a mak e f ile bysurroun ding i t with parenthe ses precede d by a dollar s ign. For

example, the fol lowing code shows how to temporari ly appendthe makepath[ .ch] l is t to the current DOS INCLUDE variable:

.prg.obj:SET INCLUDE=$(include);$(makepath[.ch])CLIPPER $<

N o t e : In the sense that you can expan d them using the syntax$(<envVariable>), environment variables are t reated l ike makefile m acro s. H ow ev er, this is wh ere the similarity end s. In noother way are environ me nt variables treated l ike macros. Forexample, you cannot test for their existence with #if directives,and you cannot undefine them w ith the #und ef directive. Seethe Macros section later in this chapter for more information onmacros.

14-18 CA-Clipper

http://set.com/

http://set.com/



The Make File

Directives

Several direct ives are prov ided for use in m ake f i les . Yo u mu stspecify each directive on a separate line in the make file.

Direct ives are handled during the parsing phase of the make.Therefore, you cannot use direct ives in dependency or inferencerule act ion l ines, and macros encountered in direct ive argumentsare always expanded immediately (see the Macros sect ion laterin this chapter for more information about macro expansion) .

The syntax for all directives in this section includes an initialhash (#) sym bol that you m ust specify. No te, how ever, that yo u

can use the exclam ation ( ) symbo l interchangeab ly with the hash(#) sym bol unless you specify the / U option. In this instance,yo u m ust use the sym bo l or the directive s will be treated ascomments .

Execute Action #\<action>

# direct ly executes the <action> during the parsing pha se. Likeother actions specified in make files, this one can be any validDOS command wi th a rguments . For example :

# DIR *.OBJ

Pro cess if M ac ro Exists #ifd ef <macroName><statements>...

[#else]<statements>...

#end[if]

#ifdef processes sub seque nt l ines i f the na m ed ma cro exists . Donot use a dol lar s ign in front of the mac ro nam e unless you are

trying to test for the existence of the m acro w hos e nam e w il lresul t f rom the expa nsion of the ma cro you are specifying. Forexample :

#ifdef prgpathmakepath[.prg] := "$(prgpath);$(mak epath[.prg])"

#endif

Progra mm ing an d Utilities G uid e 14 -1 9



The Make File

#ifeq <wordl> <word2><statements>...


#end[if]

#ifeq processes subsequent lines if the two words are identical.For example:

#ifeq $(os) windows.obj.exe:

EXOSPACE FILE $(objs) OUTPUT RL.EXE#endif

The wo rds m ust be enclosed in quotes i f they contain any spacessince a space is used to separate them . No te that the com pariso nis not case-sensitive.

Process If Sp ec ified #iffile <fileSpec>File Exists <statements>...


#end[if]

#iffile processes subsequent lines if the specified file exists.Wildcards are al lowed in the <fileSpec> so that yo u can test tosee, for exam ple, if there are an y files in a particular directory .Spe cifying the directory nam e by itself, how eve r, will fail. Forexample:

#iffile "C : \MYDIR\* . * 1

prgpath="C: \MYDIR" #endif

Remember that direct ives are handled during the parsing phase;therefore, you cannot use #iffile to check for the presence of a file

as part of an act ion. Also, makepa th mac ros do not apply w hensearching for the #iffile.

Process If Two Wordsare Ident ica l

14-20 CA-Clipper

http://mydir/

http://mydir/



The Make File

#i fndef <macroName><statements>...


#end[if]

#ifndef is the sam e as #ifdef except that #ifndef processessubsequent l ines i f the named macro does not exist . For example:

#ifndef "makepath[.prg]"makepath[.prg] := "$(src)"

#endif

Include File # inc lude "<fiIeName>"

#include inserts and processes the contents of the specified file inplac e of the #in clu de direc tive as part of the m ak e file. Th efi lename can include a path and/or extension, but no defaul tsare assum ed. For exam ple:

#include 11 RMAKE . INI"

The #include direct ive does not use the INCLUDE environmentvariable nor wil l i t use a makepath macro when searching for thespecified file. Unless you explicitly specify a path as part of thefi lenam e, only the current directory is searched.

Display Error Message #s tder r "<text>"

#stderr wri tes <text> to the stand ard error file or devic e. Forexample :

#stderr "Error in compile step."

Display Message #s tdout "<text>"

#stdout wri tes <text> to the stand ard outpu t file or dev ice. Forexample :

#stdout "Making new version..."

Process If Macro DoesNot Exist




The Make File

Undefine M acro #un def <macroName>

#undef removes any previous defini t ion of the macro, includingone supplied on the command l ine or in the RMAKE

environment variable.

N o t e : Exc ept for the fact that you can expan d them ,env iron m ent varia bles are not treated like m ake file m acro s. It ispossible , therefore, to define a macro with the sam e nam e as anenvironment variable and effect ively hide an environmentsetting within the context of the make file. As soon as you#undef the macro, the environment variable wil l once again bevisible . You cannot , however, #undef an environment variablesetting.

Macros

RMAKE provides a macro faci l i ty that a l lows you to associate astr ing of characters with a ma cro nam e. Ma cros are used in anu mb er of s ituat ions, including the fol lowing:

• To define com m a-sepa rated f ile l ists as required by mostlinkers

• For ma intenan ce purp oses, to define any value that is usedmore than once in the make file

• To condit ional ly control the course of a ma ke

• To allow user -defi ned variab les in the m ake file

With RMAKE, there are three types of macros: makepath,user-defined, and predefined. Makepath macros were discussedearl ier in this chapter under How RMAKE Searches for Fi les .User-defined and predefined macros are discussed in thissection.

N o t e : Exc ept for the fact that you can expan d them ,enviro nm ent variables are not t reated l ike ma ke f ile mac ros. Forexample, you cannot test for their existence with #if directives,and you cannot undefine them with the #undef direct ive.

14-22

CA-Clipper



The Make File

User-Def ined Macros

In a make file, a macro definition occurs on a line by itself and

takes the fol lowing form:<macroName>=[<value>]

The macro <value> can be any string of chara cters, includin gem bedd ed spa ces. I f you do not supply the value, the ma cro isdefined with a null value. You can nest macro definitions (thatis, you can reference another macro name within the macro<value>).

Warning Do not use the following characters in a macro name: do

sign, parentheses, colon, period, and the percent sign.

To subsequently use the macro, refer to it as follows:

<macroName>)

Wh en RMA KE encoun te r s a $(<macroName>), i t replace s thena m e with the associated string. If the m acro is not defin ed, it isreplac ed with a null string. A mac ro rem ains in effect until i t isredefined or undefined, or unti l RM AK E terminates .

As an example, the fol lowing statement creates a macrodefinition for a dependent file list:

files=RLFRONT.OBJ RLBACK.OBJ RLDIALG.OBJ

Later in the make file, you can use the macro as a substitute forthe file list in a rule:

RL.EXE: $(files)

Prog ram ming a nd Utilit ies G uide 14-23



The Make File

M acro Expansion There are two cases in wh ich ma cros are not imm ediatelyexpan ded wh en they are encou ntered. Firs t, macro s in inferencerule actions are not expanded until those actions are attached toa dependen cy rule . Secon d, ma cros within ma cro defini t ions are

not expanded unt i l the macro which contains them is expanded.For example:

macl = $(cfile) // cfile is not defined yetcfile = Xfile.prgXFILE.O BJ: $(macl) // XFILE.0BJ depends cfile

Delayed expansion makes i t possible for a command l ine macroto refer to a make file macro, as long as the make file macro hasbeen defined by the time the com m and l ine ma cro is used. Forexam ple , m ac l could have been def ined on the RM AK Ecommand l ine (or in the RMAKE environment variable) .

H ow ever, s ince this behavior cau ses diff icul ty in some si tuat ions,you can cause macros to be expanded without delay using theimmediate assignment operator ( :=) . For example:

macl := $(cfile) // Won't work unless cfile exists

Tip: When making assignments to makepath macros inwhich you reference a macro, you wil l a lways use theimmediate assignment operator.

N o t e : You can define ma cros on the RM AK E comm and l ineusing the same syntax as in a make file or using the /D option(which you can also specify in the RMAKE environmentvaria ble). If yo u define a m acro like this, you can not redefine itin the m ak e file w itho ut first un defin ing it . In this way ,command l ine and environment variable macros take precedenceover make f i le macros of the same name.

14-24 CA-Clipper



The Make File

P r e d e f i n e d M a c r o s

In addition to user-defined macros, there are several predefined

macros that allow you to access the target and dependent fileinformation from the last dependency statement encountered.You use predefined macros when specifying commandsassociated with a dep enden cy statemen t or inference rule. Thepredefined macros are listed in the following table:

M a c r o M e a n i n g

$* Exp and to target f i lename w ithout path or extension

$@ Exp and to target f i lename including path and extension

$** Exp and to comp lete l is t of full depend ency f i lenames

$ < Expand to full name of first file in dependent file list

$? Exp and to lis t of depen dencies that hav e a more recentdate and time stamp than target file

As an exam ple, the fol lowing inference rule uses the $< m acro tocompile a single program file (.prg) dependent on an object file(.OBJ) in a corresponding dependency statement:

.prg.obj:CLIPPER $< /Μ /N

This example does not make any assumptions about yourdependency statements and wil l compile successful ly even if youspecify more than one depen dent f i le , becau se the $< ma croextracts only the first file from the dep end enc y list . H ow ev er,when using this technique to compile a single file at a time, youwould normally specify a separate dependency statement foreach .OBJ file.




The Make File

To compile more than one source file into the same object file,use a compiler script file to list all source files to compile into thetarget object file. To use this techn iqu e, give the script file thesam e nam e as the object f ile but w ith a (.clp) extension. Then ,

w hen y ou create your m ake f i le , define the inference an ddependency rules for the compile operat ion as fol lows:

// Standard inference rule for compiling// with a script file.prg.obj:

CLIPPER @$*

// Typical dependency rule to maintain an// object fileRL.OBJ: Rlfront.prg Rlback.prg Rldialg.prg

The file, Rl.clp, simply lists the three dependent (.prg) files tocompile into RL.OBJ.

Specifying the compiler command using the $* macro is the keybecause this macro substitutes the root portion of the targetf i lenam e. This resul ts in the com m and CL IPPE R @R L w hen theinference rule is evalu ated, which tel ls CA-Clip per to read thesource f i lenames from Rl.clp.

14-26 CA-Clipper



The Make File

A Complete Make File

So far in this chapter, you have seen only bits and pieces of the

various components that compr ise a make file. The followingexample is a complete make file (RL.RMK) designed to maintainRL. EXE, the CA-Clipper report and label utility. This file, alongwith the source code files necessary to build RL.EXE, are locatedin \CLIP53\SOURCE\RL:

//// RL.RMK//// Make file for RL, CA-Clipper report and// label utility

// Define comma-separated obj list as a macroobj S =RLFR0NT RLBACK, RLDIALG

// Inference rule for compiling (.prg) to .OBJ files.prg.obj:

CLIPPER $< /Μ /N

// Dependency statements for .OBJ filesRLFRONT.OBJ: Rlfront.prgRLBACK.OBJ: Rlback.prgRLDIALG.OBJ: Rldialg.prg

// Dependency rule for linking .OBJ files to .EXEfileRL.EXE: RLFRONT.OBJ RLBACK.OBJ RLDIALG.OBJ

EXOSPACE FILE $(objs) OUTPUT $@

The following source files are compiled individually to make upthis application:

• Rlfront.prg

• Rlback.prg

• Rldialg.prg

Programming an d Utilities Gui de 14-27

http://clip53/SOURCE/RL

http://clip53/SOURCE/RL



The Make File

Thus, RL.RMK defines dependency statements for each objectfile, making it dependent on a corresponding source file. It thensets up an inference rule that will be triggered if any of thedep end ent object files is out-o f-date. The inference rule calls

CLIPPER.EXE to compile a single file at a time.

For the l ink phase , RL .RM K sets up a dependen cy rule m akingthe executable file, RL .EX E, depen den t on all three object files. Ifany o ne of these files is out-o f-date , the rule triggers its actionl ine wh ich cal ls EXO SPA CE .EXE . The FILE list on theEXOSPACE command l ine is defined with a user-defined macro.Since the name of the executable file is not the same as the firstobject file in this list , the OUTPUT file is designated using thepredefined macro, $@, which gets the full path for the executablef i lename from the dependency statement .

Assu ming y our current DO S directory is \CL IP53\ SOU RC E \RL,you can easi ly rebuild RL .EXE after you mak e source codechanges with the fol lowing command:

RMAKE RL

14-28 CA-Clipper



Chapter 15

Program Editor—PE.EXE


CA -Clipp er gives you the abil i ty to create and mod ify sourcecode and head er f i les by supp lying a s imple prog ram editor,

PE .EXE . PE is a s tand-alone applicat ion wri t ten in C A-C lipperthat provides basic editing features for text and source files.

This chapter provides a br ief overview of the C A-C lipperprog ram edi tor and general usage information. The fol low ingtopics are covered:

• Invoking the prog ram edi tor

• Nav igat ion and edi t ing

• Leaving the prog ram edi tor

• The PE system archi tecture

The CA-Clipper Workbench provides s imilar funct ional i tythrough i ts Source Cod e Editor. For more information, refer to"Using the Source Code Editor" in the Workbench User Guide.




Invoking the Program Editor

Invoking the Program Editor

If you installed the default configuration of the CA-Clipperdevelopment system, PE.EXE is located in\CLIP53\BIN. Toexecute PE from D OS , use the fol lowing syntax:

PE [<filename>]

<filename> is the nam e of the text file to edit and can includ e adrive, path, an d/ or extension. If you specify no extension, a(.prg) extension is assum ed. If the specified filename exists, it isloaded for editing; otherwise, a new file is created and you arepresented with an emp ty edi t win dow . If you do not specify afilename, you are queried for the name of a file to edit .

Like all other CA-Clipper utili t ies, you can execute PE from anydrive or directory since the appropriate directory was placed inthe PATH list during installation.

15-2 CA-Clipper

http://clip53/BIN

http://clip53/BIN



Navigat ion and Edi t ing

Navigation and Edit ing

When you load PE, the file specified on the command line iseither loaded or created, and you are presented with the editw ind ow . On ce in the edit w ind ow , the conten ts of the file aredisp layed . You can now add new or mo dify existing text bymoving the cursor to the location of the change and typing justas you wo uld w ith another text editor or wo rd processor. PE ,how ever, is fairly s imple and does not implem ent any blo ckoper ations such as select, cut, cop y, pas te, or replace. W hile y ouare edi t ing, you can save changes with Alt+W.

The following table lists the editing keys for PE. Navigation keys

are the same as those used by ME M OE DIT () . See theM EM OE DIT() en t ry in the "Langu age R eference" chapter of theReference Guide for a com plete list of these keys.

Key Act ion

Up arrow, Ctr l+E Line up

Dow n ar row, Ct r l+X Line dow n

Left arrow, Ctr l+S Character left

Right arrow , Ctr l+D Character r ight

Ctr l+Left arrow, Ctr l+A Word left

Ctr l+R ight arrow , Ctr l +F W ord r ight

Home Beginning of line

End End of line

Ct r l+Home Top of window

Ctr l+End End of window

PgUp Previous window

PgDn Next wind owContinued




Navigation and Edit ing

Continued

Key Act ion

Ct r l+PgUp Top of file

Ct r l+PgDn End of file

Return Begin next line

Delete Delete character

Bac ksp ace Delete character left

Tab Insert tab/spaces

Ctr l+Y Delete line

Ctr l+T Delete word right

Al t+H, F l Display help screen

Ct r l+W Save and exit

A l t+W Save and continue

Al t+O New output f i lename

Alt +X , Esc Exit

Al t+F Display f i lename

Al t+S SearchAl t+A Search again

Alt+I, Insert Toggle insert mode

15-4 CA-Clipper



Leaving the Program Editor

Leaving the Program Editor

To exi t the edi t window and save your most recent changes,press Ctr l+W . To exit the edi t win dow witho ut saving chang es,press Esc. I f you hav e mad e changes to the f i le witho ut sa vingthem, you are prompted to save changes before the edi t windowis closed.

In ei ther case, the edi t w ind ow closes and you are returned to theinitialization screen . On the initialization screen , you can eitherspecify an oth er file to edit or return to D O S. To edit ano ther file,enter its nam e at the File To Edit prom pt. Oth erw ise, press Escto return to DOS.

The PE System A rch itec ture

PE is prov ided in source code form . Ha ving access to the sourcecode al lows you to modify the program to sui t your own needsand serves as a mo del for program min g the M EM OE DIT ()funct ion. I f you instal led CA -Clipp er in the defaul tconfiguration, the source files are located in the\ C L I P 5 3 \ S O U R C E \ P E directory.

To faci l i ta te maintenance of the PE program fi les , the make f i le ,PE .RM K, is also instal led with the PE source f iles . Ass um ingyour cur ren t DOS d i rectory is \CL IP53\ SO UR CE \PE, you caneasi ly rebuild PE.EXE after you make source code changes withthe fo l lowing command:

RMAKE PE

If your changes involve addit ional source modules or changes inthe exist ing f i le dependencies , you wil l need to update PE.RMKto reflec t those changes . See the "Prog ram M ainte nan ce—RM AK E.E XE " chapter in th is gu ide for mo re informat ion aboutmake f i les .


http://clip53/SOURCE/PE

http://clip53/SOURCE/PE





Chapter 16

Database Utility-DBU.EXE


In order to provide you with an interact ive database designenvi ronment , CA-Cl ipper inc ludes the DB U sys tem. The sys tem

is a s tand-alone applicat ion wri t ten in CA-Clipper that a l lowsyou to bui ld databa se f i les , add d ata to the f iles , brow se exist ingdata, create and at tach inde x f i les , and co nstruct view s using acompletely menu-driven system. This chapter explains how touse al l of the features prov ided in D BU .

In this chapter, the following topics are discussed:

• Invoking the database ut i l ity

• The ma in DBU screen

• Leaving DB U

• The DB U men us

• The DB U system archi tecture




Invoking the Database Util i ty

Invoking the Database Uti l i ty

If you instal led the defaul t configurat ion o f the C A-C lipperdevelopment system, DBU.EXE and i ts help f i le , DBU.HLP, arelocated in \CLIP53 \BIN. To execute DB U from DO S, use thefol lowing syntax:

DBU [ /<colorString>] [<fi1ename>] /E

You can specify the DBU command l ine arguments in any order.

<colorString> determ ines wh ether the DB U screen display iscolor or m ono chro m e. Colo r is specif ied using / C andm ono chro m e using / M . If a color opt ion is not specif ied, thedefaul t color mode is the resul t of ISCOLOR().

<filename> is the na m e of a view file (.vew) prev iou sly created inD BU or a data base file (.dbf). If a view a nd data base file hav ethe same n am e, the view f i le is assumed unless you explici tlyspecify the database file with an extension.

Spec i fy ing <filename> on the DB U com m and line opens thenamed f i le in the Browse window after DBU is loaded (see F5Browse in The DBU Menus sect ion later in this chapter forinformation on how to use the Browse window). Otherwise, themain screen is active where you can open files and access theDBU menu bar.

/ E op ens the f i le EX CL US IVE . The param eter is not case-sensitive.

Like al l other CA-Clipper ut i l i t ies , you can execute DBU fromany drive or directory s ince the appropriate directory was placedin the PA TH l ist during instal lat ion.

The DBU Uti l i ty can also be accessed from the CA-ClipperWorkbench by double-cl icking on the DBU Uti l i ty icon in theCA-Cl ipper program group in the Windows Program Manager.

16-2 CA-Clipper

http://clip53/BIN

http://clip53/BIN



The Main DBU Screen

The M ain DBU Scre en

If you invoke DBU without a <filename> arg um ent, the first thingyou see is the main screen w hich gives yo u a visual image of thecurren t view . As you op en and close files, the m ain screen isupdated to show the current view defini t ion.

A view consists of one or more database files open in separatework areas, their associated index files, the relationshipsbetween the files, the active fields, and a logical record filter foreach w ork area . In fact, i t onl y takes a single ope n databa se fileto com prise a view— all other parts of the view are opt iona l .

W hile on the ma in screen you can ad d, chan ge, or delete i tems inone of three ways :

• Ty pin g the na m e of a file or a field

• Pressing a com m and key (Enter, Insert , or Delete)

• Pressing a m enu key to act ivate one of the pul l-d ow n m enu srepresented on the menu bar

This section describes the various com pon ents of the DB U screen

and how each one operates .

The Menu Bar

T he menu bar at the top of the screen consists of several menunames with menu keys that you press to act ivate associated pul ldow n menus . The menu bar is a lways ava i lab le except wh enthere is a pend ing prom pt.

The menu names on the me nu bar are designed to give you a briefdescript ion of what operat ions you can perform with theassoc ia ted pul l -down menu. The menu key is a function keywhose name is displayed direct ly above the menu name.Pressing i t act ivates the pul l-down menu.




The Main DBU Screen

A pull-down menu is a vertical menu that is displayed directlybelow the menu n am e. W hen one is act ive, you can see al l of themenu items that i t has to offer. Av ailab le items are display ed inhigh intensi ty, while i tems that are disabled appear dimm er.

T he highlight m ark s the curren t item and does not appear in them enu if all of the item s are disa bled . The figure belo w sho ws theDBU menu bar and al l of i ts components:

Menu Name Menu Key Drop Down Menu

Fl F2 1 F3 F4Help Open Create Save

F5 F6 F7 F8Brouse I H I H Moue Set

CopyAppend —ReplacPackZap

Menu //en?

Highlight

When a menu is act ive, the Up and Down arrows move thehighlight within the menu and Enter selects, or executes, thecurrent ly highl ighted i tem. W hen using the Direct ion keys tonaviga te within a m enu , navigat ion is not circular (for example,pressing the Down arrow on the last menu i tem does not wraparound to the first i tem).

A shortcut for navigating to a particular menu item is to type thefirst letter of its na m e. W hen u sing the first letter shortcut, m enunavigat ion is c ircular, wh ich m eans that the highl ight mov es pastthe last i tem by wra ppin g aro und to the top of the menu ifnecessary.

The Left and Right arrows act ivate the previous and next menu,respect ively, on the menu bar. Pressing Esc terminates the menuand returns control to the previous operation.

N o t e : Pressin g the sam e m enu key twice activates the specifiedmenu and selects the current ly highl ighted menu i tem, al lowingyou to perform the same operat ion repet i tively.

16-4 CA-Clipper



The Main DBU Screen

The Message a nd Prompt Area

The message and prompt a rea is located in the uppe r lef t -handarea of the main screen, just below the menu ba r. This area isused to display s tatus messa ges w hile DBU p erform s certainoperat ions and error messages when an error condit ion isenco untere d. Error me ssages remain on the screen until y oupress a key.

In addit ion to me ssage s, this area of the sc reen is used forprom pts , which are messages requi r ing a user response.General ly, these are warnings requir ing you to verify that yo uw a n t to per form a potent ial ly destruct ive act ion. Pressing Esc or

Ν termina tes a prom pt without performin g the act ion. PressingY executes the selected action.

Dialog Boxes

Most select ions that you make from the menu bar cause a dialogbox to open on the main screen , promp ting yo u for add it ionalinformation that is needed to comple te a selection.

Dialog boxes are s imilar to

pu l l -down men us in that you use theDirect ion keys to mo ve the highl ight from one i tem to anotherand use Enter to m a k e a select ion. They are different in thatselect ing an i tem does not necessari ly close the dialog box, s inceit is l ikely that you w il l want to m ake several select ions. Thei t ems in a dialog box are cal led controls. The f igure belowil lustrates the components of a typical DBU dialog box:

Fi/HnFie/d

Buttons

Open data file... *.DBFCUSTOMER.DBFINUENTRV.DBF_

B J Q T S C U S T O M E R. DBF • ORDERS.DBFSUPPLIER.DBF

Ok Cancel

Scrolling List




The Main DBU Screen

N o t e : W hen a dialog box is open on the screen, you can performonly the actions availa ble in the bo x. An attem pt to activate am enu (with the exception of Fl H elp, wh ich is alway s avai lable)will reveal that all options are disabled.

All dialog boxes in DBU are s imilar in their behav ior, a l thoughsl ight ly different in appearan ce dep ending on the informationnee ded . This section describ es each possib le type of control. No tal l dialog boxe s have each type of control described but , wh en apart icular control is present , it a lways behav es in the man nerdescribed.

Buttons

Buttons are con trols in a dialog box that are usu ally gro up edtogether and displayed side-by-side. In DB U, there are pushbuttons to per form s om e sort of action and radio buttons to makeone of several mutual ly ex clusive select ions.

Push Buttons O K and Ca nce l are exam ples of pu sh butto ns. Selecting OKconfirms the choices you hav e mad e within the dialog box andperform s the associated menu act ion. Select ing Cancel cancelsthe dialog box, as well as the associated menu action.

Radio Buttons SD F and DE LIM ITE D are exam ples of radio but tons which donot perform an act ion, but rather set some param eter. Selectinga radio but ton surroun ds i t with a box as an indicator anddeselects any other one that mig ht have been selected. You candeselect a button in the same manner as you selected it , therebyleaving al l but ton s in the group unselected.

16-6 CA-Clipper



The Main DBU Screen

Fill-in Fields

A fill-in field is a contro l in w hich y ou type text from the

key boa rd into a data entry area. Data is entered in the sam ema nner as al l data entry is perform ed in CA -Clipp er. Forexample, the Direct ion keys are used to move the cursor aroundwithin the entry area, Insert is used to toggle inse rt /ov erw ri temode, Delete is to delete the current character, and Esc undoesany change s that were mad e. Fi l l- in fields are used, for exam ple,to enter file names and expressions.

Unlike other controls, you do not have to press Enter to select afill-in field— you can just start typing o nce it is high ligh ted. Ifthe fill-in field already ha s conten ts, i t is overw ritten. To edit afill-in field, however, you must press Enter before you begin totype, move the cursor to the correct location, and make thechange.

In many cases, the information you enter into a fil l-in field willbe a logical conditio n or som e other type of expre ssion . In thesecases, you must enter a valid expression according to the rulesestabl ished by the CA -Clipp er langu age. For mo re inform ationon expressions, see the "Basic Concepts" chapter in this guide.

Scrolling Lists

A scrolling list is a con trol that displays a list of items. Selectin g ascrolling list i tem places the item in the currently highlighted fill-in field. The list is called a scrolling list bec au se if there are m oreitems than will fit in the dialog box (there are small arrows toindicate this situation), the list scrolls to bring those items intoview.

There are several examples of scrolling lists in the DBU interface,including file and field lists. Navigation and selection in ascrolling list are the same as in a pull-down menu.

Pro gram m ing an d Utilit ies G uid e 16-7



The Main DBU Screen

Closing a Dia log Box

To close a dialog box, you can select either the OK or the Cancelbu tton at the bo ttom of the box . Selec ting OK closes the dialog

box and performs the action which activated it using all of thecontrols that you have set. Selecting Cancel (or pressing Esc)closes the box w ithout perform ing the action. Both select ionsreturn you to the main screen.

Windows

Other me nu select ions open a win dow on the main screen. Aw ind ow is s imilar in appearance to a dialog box but has a special

purpose. Several windows are avai lable in the DBU interface(for example, F3 Create Database and F5 Browse Database) , andeach behaves more or less independently to accomplish i tsspecif ic task. Un like a dialog box, cer tain men u i tems other thanF l H elp are avai lable w hen a w indo w is act ive. The f igurebe low shows a typ ica l DBU window:

S t r u c t u r e o f < n e u f i l e > F i e l d 1

F i e l d N a n e Ty p e U i d t h D e c

C h a r a c t e r 1 Θ

Ho w you nav iga te and what you can do ins ide a windo wdep ends on the wi ndo w . Each w ind ow is described individual lyin The DBU Menus sect ion later in this chapter.

16-8 CA-Clipper



The Main DBU Screen

Work A reas

The screen is divided into columns with each columnrepresent ing a database work area. Up to six wo rk areas areavailab le in DB U. Each wo rk area is divided into three separa tesections on the screen which identify its attributes and theda tab ase file , an index file list, and a field list. Th e files from allwork areas, taken together with relations and filters comprise thecurrent view.

The f igure below shows the DBU work areas with two opendatabase files:

F i l e s

O R D E R S |

I n d e x e s

C U S T N U M O R D N U M

F i e l d s

C U S T N U M O R D N U MN A M E C U S T N U MA D D R E S S ITEMC I T V Q U A N T I T V

S TAT EZIP




The Main DBU Screen

Files

The Files area is for opening and closing database files (.dbf).Pressing Enter when the Files area is highlighted allows you to

open an existing database file (.dbf) either by selecting a filename from a scrolling list or by typing a file name in a dialogbox . Yo u can open up to six datab ase files at one time in DBU.

When you open a database file, an unused Files column is alsoopened to represent the next available work area (unless all sixwork areas are already occupied). When the highlight is locatedin the unused work area, you cannot move it to the Indexes orFields areas, nor can you select any menu item that requires anopen database file. Other operations, such as opening orcreating a database file, however, are allowed.

Indexes

Highlighting the Indexes area allows you to open up to seveninde x files per w ork area. Op eni ng an inde x file is accom plishedin the same manner as opening a database file. To open morethan one index file, move the highlight below the current indexfile name and press Enter.

Opening database and index files in this manner (that is, withEnter) closes any other open files that happened to occupy thatw ork area . Insert, on the other han d, allows you to open a file bypushing the other files across one column—if necessary, closingthe file occupying the last work area to make room for the newone . Op enin g databa se and index files using Insert is equivalentto using the F2 Open m enu . Delete closes the file in the currentlyhighl ighted work area.

16-10 CA-Clipper



The Main DBU Screen

Fields

Highlighting the Fields area allows you to delete, insert, and

overwrite fields in the field list for the active database file.Operations on the Fields area do not affect the database filestructure—only the field list that is used when you edit with theF5 Browse menu.

To delete a field from the list , highlight the field name and pressDelete.

To insert a field, highlight the proper location for the field andpres s Insert. The Set Fields dialog bo x ope ns allowin g you toselect the field to insert from a scrollin g list. Th is action isequivalent to selecting F8 Set Fields from the menu bar.

You can combine the actions of inserting a new field and deletingthe current one by highlighting the field you want to delete andpres sing En ter. Sim ilar to pressin g Insert, this action open s theSet Fields dialog box; however, pressing Enter causes the fieldthat you select to overwrite the current field—thereby deletingthe current f ie ld and insert ing a new one. Using a com binat ionof these actions, you can construct a field list for the currentdatabase file that is reflected when you select F5 Browse

Database.

N o t e : Beside s using Insert, De lete, and Enter to m anip ula te filesand fields, you can type file and field names directly on the mainscreen in the approp riate work area sections. Typing n am es inthis manner is equivalent to selecting them from a dialog box.

Prog ram min g an d Utilit ies G uide 16-11



The Main DBU Screen

N a v i g a t i o n o n t h e M a i n S c r e e n

The following table summarizes the keys that are available foruse when op erat ing on the ma in screen in DB U. These keys

apply only when the main screen is active and you are dealingdirectly with the variou s wor k area attributes. In short, they donot apply when a menu, dialog box, or window is act ive.

Key Act ion Attribute

Left arrow Previous column All

Right arrow Next co lumn All

Up arrow Previous row All

Dow n ar row Next row Al l

PgUp First row or previous section All

PgD n Last row or next sect ion All

C t r l+PgUp First row in currentco lumn/ sec t ion

All

C t r l+PgDn Last row in currentco lumn/ sec t ion

All

H o m e First column in current section All

End Last column in current section All

Enter Open file and close current;select field and delete current

Files; indexes;fields

Insert O pen file wi tho ut closingcurrent; select field withoutdeleting current

Files; indexes;fields

Delete Close file; delete field Files; indexes;fields

Esc Qui t DBU All

Menu Key Act iva te pul l -dow n m enu All

16-12 CA-Clipper



Leaving DBU

Leaving DBU

When you are f inished with DBU, you can exi t the ut i l i ty bypressin g Esc and respo ndi ng with Y at the pro mp t. All files thatyou created and any data that you added or changed areautom atical ly saved. You m ust , on the other han d, save a viewto disk if you plan to use it again without having to set up all ofthe com pon ents in the next DBU session.

Once a view is set up on the main screen with all the necessaryfiles and fields represented, you can save the image to a view file(.vew). To do this, select F4 Save View and enter the requ estedinform ation into the dialog box . Later on, you can select F2

Op en View and enter the view file nam e as it w as saved . Allfiles in the view are open ed an d all field lists establish ed. Formo re information o n view f i les, see F4 Save in The DBU M enu ssection later in this chapter.

The DBU M en us

The DBU menu bar has a menu name and funct ion key for eachm enu in the system . The men us are alwa ys avai lable and areact ivated by pressing the correspo nding me nu k ey to act ivate apul l -down menu.

A highl ight indicates the current men u i tem. I tems that appearin bold are avai lable for selection, while dim me r i tems aredisabled. I f a l l i tems are disabled, no highl ight app ears and youcannot make a select ion from that menu.




The DBU M enus

The fol lowing table summarizes the keys used to navigate andmake select ions when a menu is act ive:

Key Act ion

Enter Select current item

Esc Abandon menu without select ing

Up arrow High light previou s i tem

Down ar row Highlight next i tem

Left arrow Activate previous menu

Right arrow Activate next me nu

H o m e Highlight first i tem

End Highlight last i tem

In addit ion to these keys, you can naviga te to a part icular m enuitem by typ ing the first letter of its na m e. If there are severalitems in the menu beginning with the same first letter, thisme thod n avigates to the next one, wra ppin g arou nd to the top ofthe menu if necessary.

DB U uses the highl ight on the main screen to ma ke decisionsabout how certain men u select ions operate . For exam ple if you

select F6 Uti l i ty Copy, DBU assumes you want to copy from thecurrent ly highl ighted database f i le .

N o t e : You can press a me nu key wh en a m enu is act ive toquickly open another me nu. Pressing the same menu key twicein succession activates the menu and selects the currentlyhighl ighted i tem, al lowing you to perform the same operat ionrepetitively.

16-14 CA-Clipper



The DBU Menus

l Help

The Fl Help menu contains only a s ingle menu i tem, also namedHelp . Select ing it gives you context-sensi t ive help, dep endin g onwh at you are t rying to do when yo u ma ke the m enu select ion.For instance, if you are trying to open a database file and theOpen dialog box is active on the screen, requesting help givesyou information on opening a database f i le :

O P E N D ATA B A S EA d a t a b a s e f i l e n a y b e o p e n e d b y u s i n g a f i l e s b o x ,

o r b y j u s t t y p i n g t h e n a n e i n t o t h e s p a c e o n t h e s c r e e n .T h e f i l e s b o x M a y b e o p e n e d b y s e l e c t i n g " D a t a b a s e " f r o nthe "Ope n" r ienu , o r by p re ss i ng Ins e r t o r En te r. En te ro r j u s t t y p i n g i n t h e n a n e u i l l c a u s e t h e c u r r e n t d a t a

f i l e t o b e c l o s e d b e f o r e a n o t h e r o n e i s o p e n e d i n i t sp l a c e . P r e s s i n g I n s e r t o r s e l e c t i n g f r o n t h e p u l l - d o u nn e n u u i l l c a u s e a l l o p e n f i l e s i n u o r k a r e a s e q u a l t o o rg r e a t e r t h a n t h e c u r r e n t a r e a t o b e s h i f t e d t o a h i g h e ra r e a b e f o r e a n o t h e r f i l e i s o p e n e d , t h u s p r e u e n t i n g a n yf i l e f r o M b e i n g c l o s e d . A l l i n d e x e s , f i l t e r s , e t c . u i l lb e n o u e d u i t h t h e d a t a f i l e s . A f i l e M a y b e c l o s e d b yp r e s s i n g D e l e t e u h i l e t h e c u r s o r i s o n t h e f i l e n a M e .

Th e help text is disp layed in a w ind ow . If there is mor einformation than wil l f i t in the window, use Up arrow, Downarrow , Pg Up , and PgD n to scroll through the text . Press Escwhen you have f inished and want to close the window.




The DBU M enus

F2 Op en

F2 Open al low s you to open f i les . The men u contains thefol lowing i tems:

• Database

• Index

• View

All men u i tems act ivate an Op en dialog box sim ilar to the onesho w n bel ow . Th e scrolling list conta ins a different file typedepe nding on the i tem you select.

O p e n d a t a f i l e . . . * . D B Fp e n d a t a f i l e . . .

• C U S T O M E R . D B F |I N U E N T RV. D B F

F i l e O R D E R S . D B FS U P P L I E R . D B F

O k C a n c e l

If the highlight on the main screen is located in the Indexes area,Index is the current i tem wh en yo u act ivate the Op en m enu.Oth erw ise, the current i tem is Databa se.

For all Open menu items, selecting an already open file orentering the name of a nonexistent file causes an error.

D a t a b a s e

Database opens a database f i le (.dbf) in the currently highlightedw ork area on the ma in screen. Select ing this m enu i tem act ivatesan Op en dialog bo x wh ere you can ei ther select a database f i lename from a scrolling list or type one directly into a fil l-in field.

When you select OK, the file is opened in the currentlyhighlighted work area, pushing all other open files to the rightby one w ork area. An y f i le occupying w ork area s ix is c losed.

Yo u can act ivate the Ope n Da tabase dialog box by pressing Enteror Insert instead of usin g the m enu . If yo u know the nam e of thefile that you want to open, you can also type it directly on themain screen.

16-16 CA-Clipper



The DBU Menus

Index

Index opens an index f i le (.ntx) in the current ly highl ighted wo rk

area. This me nu i tem is avai lable only i f there is a co rrespon dingopen database f i le . Select ing Index act ivates an Open dialog boxwhere you can ei ther select an index f i le name from a scrol l inglist or type one directly into a fil l-in field .

W hen you select O K, the f ile is open ed in the current lyhighl ighted s lot , push ing al l other open f i les across one s lot. An yfile occupying slot seven is closed.

You can act ivate the Open Index dialog box by pressing Enter orInsert instead of using the menu . If you kno w the nam e of thefile that you want to open, you can also type it directly on them ain screen . Th e index file at the top of the co lum n is thecontrol l ing index.

Vi e w

View open s a view f i le ( .vew) by o pening al l i ts associateddatabase and index files, establishing the field lists for eachdatabase f i le , establ ishing the relat ions betw een the f i les , andact ivat ing f il ters for each wo rk area. Select ing this m enu i temactivates an Open dialog box where you can ei ther select a viewfile name from a scrolling list or type one directly into a fil l-infield.

N o t e : Yo u can design, save, and open a view f i le only in D B U —you cannot use i t subsequently in a CA-Clipper applicat ionwi thout fur ther programming.




The DBU M enus

F3 Cre ate

F3 Create al lows you to create and mo dify database and indexfiles. The menu contains the fol lowing i tems:

• Database

• Index

If the highlight on the main screen is located in the Indexes area,Index is the current i tem whe n you act ivate the Create men u.Otherw ise, the current i tem is Database.

D a t a b a s e

Select ing Database opens the Structure window in which youenter field definitions to define a data base file structure . If adatabase file is open in the current work area on the main screen,its structure is displayed in the window for you to modify, asshow n below . Othe rwise, the win dow is em pty, under theassum ption that you w ant to create a new fi le .

S t r u c t u r e o f C U S T O M E R . D B F F i e l d

F i e l d N a Me Ty p e Wi d t h

1

D e c

C h a r a c t e r 5C U S T N U M • C h a r a c t e r 5N A M E C h a r a c t e r 5 0A D D R E S S C h a r a c t e r 3 ΘC I T V C h a r a c t e r 3 ΘS TAT E C h a r a c t e r 2Z I P C h a r a c t e r 9

16-18 CA-Clipper



The DBU Menus

The fol lowing table summ arizes the keys that are avai lable w henthe Structure wind ow is active:

Key Act ionEnter Enter input mod e; go to next colum n

Esc Ab and on input mo de without saving;close Structure window without saving

F4 Close Structure window and save

Space bar Select next value in Type colum n

Up arrow Go to previous field definition

Down ar row Go to next field definition

Left arrow Go to previous column

Right arrow Go to next column

Insert Insert new field definition

Delete Delete current field definition

Home Go to first column

End Go to last column

Ctr l+H om e Go to f irs t colum n

Ctr l+End Go to last columnPgUp Scroll field definitions back

PgDn Scroll field definitions forward

Ct r l+PgUp Go to first field definition

Ct r l+PgDn Go to last field definition




The DBU Menus

For each field in the database file, you must define a field nameand data type. Then , depending on the data type, you may alsohave to define the field width and number of decimal places.

A field definition is checked for validity when you attempt tomove the highlight to another field (for example, by pressingDo w n arrow to mov e to the next f ield) . I f you have m ade anymistakes an error message is displayed, and the highlight ismoved to the erroneous column.

Field Name To create a new field in the Structure win dow , mo ve thehighlight to an empty ro w in the Field Nam e column and typethe field na m e. Field nam es can be up to ten characters inlength, must begin with a letter, and can contain letters,

numbers, and the underscore character only.

To edit an existing field name, highlight it and press Enter beforetyping . This places you in inpu t m od e w her e data is entered inthe same manner as all data entry is performed in CA-Clipper.For exam ple, the Direct ion keys are used to move the cursoraround within the entry area, Insert is used to toggleinsert /overwri te mode, and Esc undoes changes. Enter is usedto term inate inpu t m od e. Field Na m e is essentially the sam e as afill-in field in a dialog box.

Type The Typ e colu m n define s the data type of the field. InCA-Clipper, the valid field types are as follows:

• Character

• Date

• Logical

• Memo

• Numer ic

To select a data type for a field, highlight the Type column of thefield and type the first letter of the type you w ant. As analternative, you can press the Space bar to move through theavailable data types until the one that you want is displayed.

16-20 CA-Clipper



The DBU Menus

Width Th e W idth col um n define s the length of the field. For dat e,logical , and memo f ields, DBU assigns the column widthautomatical ly as 8,1, and 10, respect ively.

To enter a field width for a character or numeric field, move thehighlight to the W idth colum n and type a num ber. For charac terf ields, the number must be between one and 1024, and thedefaul t is ten. For numeric f ields, the width m ust be b etw eenone and 19, and the default is also ten.

To edit an existing field width, highlight it and press Enterbefore typing. This places you in input mod e where data isentered in the same manner as all data entry is performed inCA -Clip per. W idth is essentially th e sam e as a fil l-in field in adialog box.

Decimals The Dec colum n is for num eric f ields only. I t defines the nu m berof decimal places allowed in the field.

The nu m ber that you enter in this column mu st be at least twoless than the field w idth . Th us, i t can range betw een on e and 17,but the actual range depend s on the current f ield width . LikeField Name and Width, Dec behaves like a fil l-in field in a dialogbox—just start typing for a new value or press Enter first to edit

the current value.

Inserting an d Deleting To insert a new f ield w hen you have one or m ore f ieldFields def ini t ions already in the Structure win dow , highl ight the f ield

before w hich yo u w ant to insert the new field and press Insert .An empty row opens up, and al l exis t ing f ields move down onespace.

To delete a field defin ition, high light it and press Delete. Th efield is deleted, and all fields following it move up to close the

space.




The DBU Menus

Saving the File Structure W he n you h ave m ad e all of the chan ges that you wa nt to thedatabase file structure, you can choose to either save the changesor abandon them al together.

To abandon all changes and return to the main screen, press Esc.A prompt is displayed for you to confirm your choice.

To save the data base file struc ture, select F4 Sav e Struct. A Sav edialog box op ens on the screen where yo u can enter the name ofa new data base file or accept the curren t file na m e. If you selectOK, the file is created and opened in the currently highlightedw ork area. This dialog box is descr ibed und er F4 Save later inthis section.

Warning When you are modifying a database file structure, certainchanges cause data to be lost when you save the file. In all cases, DBUattempts to save as much data as possible and prompts you if it has adecision to make regarding whether or not to preserve data. To m akesure that you do not lose anything important, make backup copies of tdatabase file before mod ifying its structure significantly.

16-22 CA-Clipper



The DBU Menus

Index

Index allows you to create a new index file or modify the key

expression of an existing one for the database file in the currentwork area. To create a new file, move the highlight to an unusedslot in the Indexes column; to modify an existing index keyexpression, make sure the index file is open in one of the Indexescolum ns and highl ight i ts f ile nam e. Select ing this men u i temactivates a dialog box w here you can enter an index f i le n am eand key expression:

I n d e x C U S TO M E R . D B F t o . . . * . N T XC U S T N U M . N T XO R D N U M . N T X

F i l e C U S T N U M . N T X

K E V C U S T N U M

Mn m C a n c e l

You can select the file name from a scrolling list or type itdirectly into a fil l-in field. If an open in dex file is cu rrentlyhighl ighted on the main screen, its nam e (and key expression)auto m atically a pp ear in the dialog box . If you cha nge the filenam e, a new index f i le is created with that nam e; otherwise, the

curren t index file is recrea ted. If there is no curre nt index filewhen you make the menu select ion, no f i le name appears , andyou must provide one.

Yo u type the index key ex pressio n into a fil l-in field. If there isalready a key expression present, you can edit i t by pressingEnter before you begin typing.

When you select OK in the Create Index dialog box, the file iscreated and opened in the currently highlighted slot.

N o t e : Yo u can use Create Index to reind ex a data base file. Todo this, go through the steps as if you were going to modify thekey expression without changing anything. Simply select OK,and the index is recreated.




The DBU Menus

F4 Sa ve

F4 Save al lows yo u save a new ly created or mo dif ied databasefile structure to a (.dbf) fi le or to save the view defined on the

main screen to a (.vew) file. The menu contains the followingitems:

• View

• Struct

Vi e w

View saves the database environment defined on the mainscreen, including open database and index files, relations, fil ters,and field lists. Selecting this men u item open s a dialog box assho w n below . Yo u can select a file na m e from a scrolling list ortype one directly into a fil l-in field. Usin g an existing file nam eoverwrites the file, while typing a new file name creates a newfile:

S a u e u i e u a s . . . * . U E UC U S T. U E U

F i l e I N U O I C E S UEU

BTl C a n c e l

When you select OK, a view file (.vew) is created which you canopen and mod ify in DB U. You can not , how ever, use a view f i leoutside of DBU in a CA-Clipper applicat ion without fur therprogramming.

Struct

Struct saves the database file structure that you are activelycreat ing or mo difying in the Structure wind ow . Select ing this

me nu i tem opens a dialog box in which you can select a fi lename from a scrolling list or type one directly into a fil l-in field.

Select ing OK saves the named database f i le (.dbf) and appendsthe original data back into the file, if necessary.

Struct is not available unless you have an open Structurewindow on the screen (see F3 Create earlier in this section).

16-24 CA-Clipper



The DBU Menus

F5 Browse

F5 Browse allows you to view and edit data in a database file or

a view. The menu contains the fol lowing i tems:• Database

• View

Each of these menu i tems opens a Browse window on the screen,and this sect ion describes how to operate within that window.To close the wi ndo w , press Esc. Cha nges that you ma ke areautomatical ly saved.

N o t e : Search funct ions are avai lable for quick navigat ion within

the Brow se wind ow . See F7 M ove later in this sect ion for m oreinformation.

D a t a b a s e

Database opens a Browse window for the database f i le in thecurrent ly highl ighted work area:

<Insert> Record 1/7CUSTNUM NAME

MM Maruin Green1249 Robert Robertson28Θ3 Sharon Black3648 Uanessa Sanuels

Only those fields shown in the Fields area on the main screen areavai lable for edi t ing. You can m ake chan ges to the exist ingrecord s imply by typing over the old information, and you canadd new records by moving the highl ight below the last recordin the file. Pressing Delete marks the current record for deletionor reinstates the record if i t is alrea dy m ark ed . (See Pack in theF6 Utility section later in this chapter for information on how topermanently remove records marked for delet ion.)

Program ming an d Utilities Gu ide 16 -2 5



The DBU Menus

Vi e w

View opens a Browse window for the ent ire view defined on them ain sc reen. All fields in the Fields area for all files in the Files

area are available for editing. The win do w beh aves as if youwere editing a database file, except that you can neither edit datafrom m ult iple f iles nor appen d new records.

Navigat ion and Edi t ing The fol lowing table sum marizes the keys that you can use whena Browse window is act ive:

Key Act ion

Enter Enter input mode; go to next field

Esc Abandon input mode without saving;c lose Browse window

Up arrow Go to previous record

Down ar row Go to next record

Left arrow Go to prev ious field

Right arrow Go to next field

Ctr l+Left arrow Pan screen to the right

Ctrl +R igh t arrow Pan screen to the left

Insert Toggle insert modeDelete Tog gle record delete status

H om e Go to first field on the screen

End G o to last field on the screen

Ctrl+ H om e Go to f i rs t f ie ld

Ctr l+E nd G o to last field

PgUp Scroll records back

PgDn Scrol l records forward

Ctrl+ Pg Up Go to f i rs t record

Ctr l+PgDn Go to last record

16-26 CA-Clipper



The DBU Menus

Editing M em o Fields Yo u edit m em o fields in a po p-u p w ind ow . T o ope n thew ind ow , highl ight the m em o f ield. Then , press Enter or just s tar ttyping.

The fol low ing table summ arizes al l of the edi t ing and navigat ionkeys avai lable when a memo edi t ing window is act ive:

Key Act ion

Ente r Go to nex t line

Esc Close pop-up window wi thout sav ing

Up arrow Go to previous l ine

D ow n arrow Go to next l ine

Left arrow Go to previou s character

Right arrow Go to next character

Ct r l+Lef t a r row Go to fi rst character of previou s w ord

Ctr l+Right a r row Go to first character of next word

Insert Toggle insert mode

Delete Delete current ch aracter

Backspace Delete previous character

H o m e Go to beginning of l ineEn d Go to end of line

C t r l + H o m e Go to beginning of file

Ctr l +En d Go to end of f i le

PgUp Scroll screen back

PgD n Scrol l screen forward

Ct r l+PgUp Go to beginning of screen

Ct r l+PgDn Go to end of screen

Ctr l+B Reformat cur ren t paragraph

Ct r l+N Insert blank line

Ctr l +T Delete next w ord

Ctr l+ W Close pop-up wind ow and save

Ctr l+Y Delete current l ine




The DBU Menus

F6 Utility

F6 Uti li ty provides yo u with several batch database operat ions.Each of the menu items listed below directly corresponds to a

CA-Cl ipper command of the same name:

• Copy

• Append

• Replace

• Pack

• Zap

• Run

C o p y

Co py al low s you to copy the current database f i le to anotherda tab ase file or a text file. A ny filter cond ition th at is in effect isrespected, but the field list is ignored as are any file relations.Only the active database file is copied, and it is copied in orderaccording to the first index file in the Indexes column, if any.

To copy a file, move the highlight to the database file work areathat you want to copy—you cannot select Copy if the unusedwork area is highl ighted.

Select ing this me nu i tem act ivates a dialog box where yo u canenter a f i le name , FO R and W H ILE condit ions, a record scop e,and specify a text f i le by select ing SD F or DE LIM ITED :

C o p y C U S T O M E R . D B F t o . . . * . D B FC U S T O M E R . D B FI N U E N T RV. D B FO R D E R S . D B F

FOR S U P P L I E R . D B FU H I L ES C O P E A L L

S D F D E L I M I T E D

Ok Cance l

16-28 CA-Clipper



The DBU Menus

You can select the file name from a scrolling list or type itdirectly into a fill-in field.

Text Files If SD F or D EL IM IT ED is selected , the scrolling list sho ws textfiles (. txt); oth erw ise, i t sho w s databas e files (.dbf). SD F andDELIMITED are radio but tons—you can select only one at atime. If one is selected , i t is surr ou nde d by a bo x as an indica tor.To select (or deselect) one of these buttons, highlight it and pressEnter.

SDF indicates a text file that is undelimited and withoutseparators between f ields. DE LIM ITE D indicates a text f i le inwhich f ields are separated by commas and character f ie lds areenclosed in quotat ion marks.

The rem aining controls in the dialog box are used to designate asubset to operate on in lieu of all records in the current databasefile.

Sc o pe The SC OP E can be ei ther AL L records or a specif ic num ber ofrecord s. This contro l acts like a kind of specia lized fill-in field. Ifyou select i t , the ALL changes to NEXT with a 0 to the right of it ,and you are expected to enter a posi t ive numb er. Pressing Enterwith the number set at zero returns the scope to the default, ALLrecords. An y other num ber changes the scope to NE XT <n>(where <n > is the num ber you entered) , causing the operat ion tobegin with the current record and continue unt i l <n > recordshave been processed or until the end of file is encountered.

FOR and WHILE are both f i l l - in f ields where you enterexpressions to extract a logical subset of records from the file.You mu st enter a val id logical exp ression.

For Condition A FO R con dition is evalu ated as each new record is con sid ered ,

and those records that evaluate to false (.F.) are not processed.This process continues until the end of file is reached.

Program ming an d Utilities G uid e 16 -2 9



The DBU Menus

While Condition A W H ILE condit ion causes processing to begin with the currentrecord and co ntinue on ly while the condit ion evaluates to t rue( .T.). I f both FO R and W H ILE cond it ions are entered, WH ILEtakes precedence over FOR.

After all controls are set, selecting OK creates the new file butdoes not open it on the main screen.

A p p e n d

Append allows you to add records to the active database filefrom either a database file or a text file.

To add records from one file to another, move the highlight tothe w ork area containing the f i le that you want to append to —you cannot select Append if the unused work area ishighl ighted.

Selecting this menu item activates a dialog box that is almostidentical to the Copy dialog box, which you can refer to fordetails on all controls. Selecting OK appends the designatedrecords to the end of the current file and updates all open indexfiles in the same work area.

R e p l a c e

Replace perfo rms co ndit ional or global f ie ld replacemen ts in theactive datab ase file. In D BU , yo u can replace only one field at atime.

To replace a field in a database file, move the highlight to theappropriate work area—you cannot select Replace i f the Uti l i tymenu is act ivated when the unused work area is highl ighted.

16-30 CA-Clipper



The DBU Menus

Select ing this menu i tem act ivates the dialog box show n below .To perform the replace, you must select a f ield nam e from thescrolling list and ente r a W ITH exp ression in the fill-in field. Yo u

can optional ly designate FOR and WHILE condit ions and arecord scope.

R e p l a c e i n C U S TO M E R . D B F. . . — F i e l d s —e p l a c e i n C U S T O M E R . D B F. . .• C U S T N U M •

F i e l d N A M EU I T H A D D R E S S

C I T VFOR S TAT EU H I L E Z I PS C O P E A L L

O k C a n c e l

Th e Field area in this dialog bo x is not a fill-in field; you m ustselect the field from th e scro lling list. Th is is do ne as aprecaution to ma ke sure that only val id f ield nam es are used .

WITH is a fill-in field, and you must enter a valid expression ofthe same data type as the field you select.

The rem aining con trols were de scribed earl ier in the d iscussionof the Copy dialog box, which you can refer to for moreinform ation. Selecting OK repla ces the indica ted field in thespecified records and updates all index files in the same workarea.

P a c k

Pack permanently removes records that are marked for delet ionin the active database files. In DBU, records are marked fordelet ion in the Browse window using the Delete key.

To pack a database f i le , m ove the highlight to the ap propriatework area—you cannot select Pack if the unused work area ishighlighted.

Select ing this menu i tem displays a prompt which you mustansw er before the operat ion can proce ed. Typ ing Y pack s thedatabase file and updates all open index files. Typing Ν orpressing Esc abandons the operat ion without packing the f i le .




The DBU Menus

Z a p

Zap permanently removes al l records from the act ive databasefile, regardles s of their delete status. This item is useful for

getting rid of test data in a file.

To zap a database file, move the highlight to the appropriatework area—you cannot select Zap if the unused work area ishighlighted.

Select ing this menu i tem displays a prompt which you mustansw er before the operat ion can proceed. Typ ing Y zaps thedatabase file and updates all open index files. Typing Ν orpressing Esc abandons the operat ion.

Run

Run al lows you to execute another program from within DBU.Selecting Ru n displays a pro m pt at the bot tom of the screen. Tothe right of the prompt is a large fill-in field where you can enterany DOS command, just as i f the DOS prompt were on thescreen. Press Enter to execute the comm and .

After the command that you enter has completed execution, you

are returned to DB U with a new p rom pt. At this point , you canexecute another co m m and or press Esc to go back to the m ainscreen.

Warning In order to use this menu item, you mu st have enoughavailable memory to load the other program.

16-32 CA-Clipper



The DBU Menus

F7 M ov e

F7 Move gives you a quick way to move around in a Browsew indo w. The m enu i tems are as fol lows:

• Seek

• Goto

• Locate

• Skip

No ne of the i tems in this men u are avai lable unless you hav e anopen Brow se win dow on the screen (see F5 Brow se earl ier in this

sect ion) . All record pointer m ove me nt is perform ed in thecurrent work area or the first work area if you are browsing aview.

Seek

Seek locates a part icular index key value in the Browse window.This menu item is available only if there is an open index file.

When you select Seek, a dialog box opens and al lows you toenter an exp ressio n into a fil l-in field. Yo u mu st enter a validexpression that ma tches the data type of the control l ing indexkey expression. Do not use quotes wh en seeking a characterexpression:

S e e k i n f i l e C U S TO M E R . D B F. . .

O k C a n c e l

Selecting OK locates the first record in the file with a matchinginde x key and highlights it for editing in the w ind ow . If notfound, an error message is displayed, and the dialog box remainsop en on the screen. Yo u can either Ca ncel or enter a new keyvalue.

Pro gram min g a nd Utilit ies G uid e 16-33



The DBU M enus

G o t o

Goto jumps to a part icular record number in the Browsew ind ow . W hen yo u select this me nu i tem, a dialog box opens in

which you enter a number:

M o u e p o i n t e r i n f i l e C U S TO M E R . D B F t o . . .

Recordtt

Ok Cance l

Select ing O K locates the record w ith the indicated recordnu m ber an d highlights it for editing in the w ind ow . If there isno such record number, an error message is displayed, and thedialog box remains o pen on the screen. You can ei ther Cancel orenter a new number.

L o c a t e

Locate searches forw ard fro m the current record posi t ion for thefirs t record match ing a logical search condit ion. W hen you selectthis m enu i tem , a dialog bo x open s and al lows you to enter a

logical expression into a fil l-in field:

L o c a t e i n f i l e C U S TO M E R . D B F. . .

Ok Cance l

Selecting OK locates the next record in the file that meets thesearch cond ition and highlig hts it for editing in the w ind ow . Ifnot fou nd, an error me ssage is displayed, and the dialog boxrem ain s open on the screen. Yo u can either Can cel or enter anew search condit ion.

16-34 CA-Clipper



The DBU Menus

Skip

Skip moves the record pointer forward or backward in the

current work area. W hen yo u select this me nu i tem, a dialog b oxopens in which you enter the number of records to skip:

S k i p r e c o r d s i n f i l e C U S TO M E R . D B F. . .

Ok C a n c e l

Enter a posi t ive number to move the record pointer forward anda negat ive number to move i t backward.

Select ing OK u pdates the record pointer by skipping thespecified number of records and highlights it for editing in thewin dow . Specifying a num ber wh ich wou ld advance the recordpointer beyond the beginning or end of file selects the first or lastrecord—no error message is displayed.

F8 Set

F8 Set al lows you to establish relat ionships between database

files and to set up a field list and filter condition to define a view.The menu i tems are as fol lows:

• Relation

• Filter

• Fields

All of these menu items require at least one open database file.Relation requires at least two, in addition to the possiblerequirement of an index file.

To save the Set me nu set t ings, you m ust select F4 Save View .Othe rwise, the set tings wil l be lost w hen y ou exi t D BU .




The DBU M enus

Rela t ion

Relat ion al lows you to model relat ionships between the opendatabase files in the Files area, just as you would with the SET

REL AT ION c om ma nd but f rom an in terac tive wind ow. To usethis item, make sure that all the necessary database and indexfiles are open in an order that reflects the hierarchy of therelat ionship you w ant to establ ish— this is important s ince youcan only establish relations from left to right.

Select ing Relat ion opens the Set Relat ion wind ow in wh ich youselect files and enter exp ressio ns to relate them . If there arealready relations established between the files on the mainscreen, they appear in the Set Relation window for you to edit.Othe rwise, the w ind ow is em pty and yo u have to s tart f romscratch.

The f igure below show s a w indo w in wh ich a relation is beingestablished:

Rela t ions

16-36 CA-Clipper



The DBU Menus

To establish a relation between a parent and a child:

1. M ove the highl ight in the w indo w to the wo rk area colu mncontaining the parent file and press Enter.

The f i le name appears in the window.

2. To select a child file, press Enter again.

An arrow appea rs to visual ly indicate that a conne ct ion isbeing made between the two f i les .

3. M ove the highl ight to the wo rk area colum n containing thechild file and press Enter.

A fill-in field opens up just beneath the file names.

4. Typ e the relation expression , and press Enter wh en you arefinished.

Depending on whether or not the child file is indexed, thevalu e that you enter here takes on a differen t signif icanc e. Ifthe file is indexed, the two files are related based on thecontrolling index key of the child; if not, they are relatedbased on record num ber. In the former ( indexed ) case, enterthe field (or expression) in the parent that you wantcom pa red to the index key in the child. In the latter(unindexed) case, enter a numeric value (usual ly the

RECNO() funct ion) that you want compared to the recordnum ber in the chi ld.

At this point , you can press Do w n arrow and establ ish ano therrelation by repea ting the steps abov e. If a partic ular data bas e fileis the parent of more than one relation, a multiple parent-childrelation is establis hed . Insert inserts a relation definition andpushes exist ing ones down in the window, and Delete deletes thecurren t relation. Yo u can establish up to 15 relations per vie w inDBU.

Progra mm ing an d Utilities Gu ide 16 -37



The DBU Menus

The fol lowing table summarizes the keys that are avai lable foruse when a Set Relat ion window is act ive.

Key Act ion

Enter Enter select mode; select parent or child;exit select mode

Esc Exit select mode without saving; close SetRela t ion window

Up arrow Go to previou s relat ion

Down a r row Go to next relation

Left arrow In input m od e, go to previous f ile

Right arrow In input mode, go to next file

Insert Insert new relation

Delete Delete current relation

PgUp Scroll relations back

PgDn Scrol l relat ions forward

After a relation is established, selecting F5 Browse View reflectsthe relat ion by show ing ho w the records in the various databasefiles are conn ected . For exam ple , if two files are related using anindex key , records with m atching key values in the parent an dchild file are on the same line, appearing as one record in theBrowse window .

16-38 CA-Clipper



The DBU Menus

Filter

Filter allows you to impose a logical condition that each record in

the database file must meet, just as you would with the SETFILTER command. This menu i tem operates on the current lyhighlighted database file, allowing you to set a fil ter conditionfor each open file.

When you select Filter, a dialog box opens and allows you toenter a logical expression into a fil l-in field:

S e t f i l t e r f o r C U S TO M E R . D B F t o . . .

^ H H B H I H U H i lOk Cance l

Selecting OK activates the filter for the current file so that onlythose records meeting the condition are available for processing.If there is an error in the condition, an error message isdisplay ed, and the dialog box remains open on the screen. Youcan either Cancel or enter a new condition.

After a fil ter is established, selecting F5 Browse Database reflects

the filter condition by showing only those records that meet thecriteria. The filter con dition is also reflected in the operatio n o fcertain F6 Utility m enu item s such as Co py and Replace . Th efilter remains in effect until you remove it by selecting F8 SetFilter and deleting the condition.

Prog ram m ing an d Utilit ies G uide 16-39



The DBU M enus

Fields

Fields allows you to establish a field list for the current databasefile. This menu i tem operates on the current ly highl ighted

database file, allowing you to set a field list for each open file.

Selecting Fields activates the Set Fields dialog box where you canselect a single field name to add to the current field list:

S e l e c t f i e l d . . — F i e l d s —e l e c t f i e l d . .• C U S T N U M •

Fie ld N A M EA D D R E S S

Ok C a n c e l C I T Y I

When you select OK, the field is inserted in the Fields section forthe current work area, pushing all other fields down one slot.

You can activate the Set Fields dialog box by pressing Enter orInsert instead of using the men u. If you kn ow the nam e of thefield that you want to include, you can also type it directly on themain screen.

The fields list that you see on the main screen and that youestablish with the F8 Set Fields dialog box is used by F5 Browseto determine which f ields to show in the Browse window and inw ha t order. All other opera tions in D BU use all fields defined inthe database file structure.

16-40 CA-Clipper



The DBU System Arc hite ctu re

The DBU System A rch itectu re

D BU is pro vide d in sou rce cod e form . If you in stalledCA -Clipper in the defaul t configurat ion, the fol lowing sourcefi les are located in the \CLIP53\SOURCE\DBU directory:

• Dbu.prg

• Dbu.hlp

• Dbucopy.prg

• Dbuedit .prg

• Dbuhelp.prg

• Dbuindx.prg• Dbunet .prg

• Dbustru.prg

• Dbuuti l .prg

• Dbuview.prg

The system is provided as source code so you can modify it tosui t your specif ic needs. You ma y want to ma ke enhan cem entsspecif ic to your develo pm ent environ men t or s imply add theDBU system to your application, thereby giving your users thepower to create and modify their own database file structures.

To faci li ta te maintena nce of the DBU pro gram fi les, the m akefile, DB U.R M K, is also instal led with the DBU source f i les .Assuming your current DOS directory is\ C L I P 5 3 \ S O U R C E \ D B U , you can easi ly rebuild DBU.EXE afteryou make source code changes with the fol lowing command:

RMAKE DBU

If your chan ges involve addit ional source mo dules or changes inthe existing file dependencies, you will need to updateDBU.RMK to ref lect those changes. See the "ProgramM ainten ance— RM AK E.EX E" chapter in th i s gu ide for moreinformation about make f i les .


http://clip53/SOURCE/DBU

http://clip53/SOURCE/DBU





Chapter 17

Report an d Label Utility—RL.EXE


CA -Clipp er gives you the abil i ty to create and modify s tandarddB ASE III PL US report and label defini tions by supplying a

report and label utili ty, RL . RL is a stand -alon e ap plicatio nwri t ten in CA-Clipper that emulates the dBASE CREATE IMODIFY REPORT and LABEL commands .

RL creates a binary report (.frm) or label (.lbl) fi le, which you canla te r use wi th the REPORT FORM or LABEL FORM commandsto format and print data on a record by record basis from one ormore open database f i les .

This chapter explains how to use RL to create and mo dify reportand label defini t ions and also provides inform ation on how touse the resul t ing report and label defini t ions in you r CA -Clipp erapplicat ions.

The following general topics are covered in this chapter:

• Loa ding the repo rt and label utili ty

• Creat ing and mo difying reports

• Creat ing and mo difying labels

• Leaving RL

• The RL system archi tecture




Load ing th e Repor t and Label Utility

Loading the Report and Label Utility

If you installed the defaul t configurat ion of the CA-Clipperdevelopment sys tem, RL.EXE is located in \CLIP53\BIN. Toexecute RL f rom DOS, use the fol lowing syntax:

RL

Like all other CA-Clipp er u t i li t ies , you can execute RL from anydrive or directory since the appropriate directory was placed inthe PATH list during installation.

Crea t ing and

M od ifying ReportsThe main menu conta ins a Report i tem that activates the reportedi tor. The report definitions you can design are s tandardcolumnar reports with report and colum n headings. W hentotal ing numeric columns you can have up to two levels ofsubtotals and generate a grand total for each colu mn .

From there, you can create and modify report form ( i rm) filesthat are executable with the R E P O RT F O R M c o m m a n d . Formore informat ion on the REPO RT FOR M com mand r e fe r to the

"Language Reference" chapter of the Reference Guide.

Creating or M odifying a Report

To create or mod i fy a report form, select Report from the m ainm e n u . A File dialog bo x opens as shown below:

•;JU'.M'i .B Label Quit

17-2 CA-Clipper

http://clip53/BIN

http://clip53/BIN



Crea t ing a n d Mo difying Reports

Y ou can either create a file b y enter ing a new f i lename or selectan existing file to mod i fy f rom a scrolling list displayed on theright side of the dialog bo x. To create or open the ( i rm ) f i le you

specif ied or highl ig hted, select OK. To canc el and return to themain RL m enu , select C ancel .

Defining Report Columns

Having selected a report to edi t , you ar e presented with theColumn Defini t ion screen, where you can design a new repor t o rmake changes to an exis t ing one. The Colu m n Defini t ion screencorresponds to the F4 Colum ns menu i tem. It is here that you

define the columns of your report by adding , changing , ordele t ing co lumns . The maximum number of co lumns pe r reportis 24.

Fl F2 F3 F4 F5 F6 F7 FIBHelp Report Groups ... Delete Insert Go To Exit

File MYFILE.FRhColunn 1

— Colunn Definition = Total 3

Contents 3£Q23 ^^^^^^^^^^^HIHIÎHHflillHHHfli^^^HiflflfllH I

Heading

Colum ns appear on the resul t ing report in the order you definethem. A detail l ine is d i sp layed fo r each record in thecorresponding database f i le .

A report column is def ined by enter ing each of i ts attribu tes onthe Column Defini t ion screen. To do this , mo ve the cursor to theset t ing that you want to def ine and type in the co rrespond inginformat ion . To add subsequent co lu mn s , press PgDn tonaviga te to a new C olu m n Defini t ion screen.

Programming a n d Utilities G ui de 17 3



Creating and Modifying Reports

Once you have defined several column definitions in this way,you can use PgUp and PgDn to navigate to the next or previouscolumn definition for editing.

Con tents Each colu m n has a conte nts expres sion. It is here that you enterthe name of a f ield or a mo re comp licated expression— you canspecify most data types, including memo fields. Values of eachdata type display in the default format and alignment settings,unless explicitly forma tted. As a gen eral rule, you can use theTRA NSF OR M^) function to apply picture formatt ing to each datatype . Refer to the "Language Reference" chapter of the ReferenceGuide for the syntax and arguments. Specific formattingconsiderations for each data type are discussed below:

Character St r ings: Display left-justified and can be formattedusing TR AN SF OR M (). Character s trings also wrap within thecolu mn boun dar ies if long er than the specified W idth setting. Toforce a line break and wrap the rest of the column to a new line,embed a semicolon (;) using an expression like <cStringl> + ; +<cString2>.

M e m o f i e l d s : Trea ted in the same wa y as characte r strings, butthere are some special considerations since they can containem bed ded soft or hard carr iage returns which adv ersely affect

wo rd wrapp ing. For a m em o field to display correct ly, you m ustreplace these characters using ei ther HARDCR() orM E M O T R A N ( ) .

Date f ie lds : Display left-justified and are formatted accordingSET D AT E. To format the date different ly, create a user-definedfunction.

Logica l va lues : Dis pla y left-justified as eithe r true (.T.) or false(.F.). To define a ne w form at, yo u can use either a user-definedfunction or the IF() function.

17-4 CA-Clipper



Creat ing and Modifying Repor ts

Log ica l va lues : Display right-justified acco rding to the currentDECIMALS and FIXED set t ings. To format numeric values tobus iness or other comm on n umer ic formats, use TRA NS FO RM () .Note , howe ver, tha t TRA NSFO RM Q conver ts a numer ic va lue toa character value, which prevents totaling of the column.Un fortunately, this is a l imitat ion of the REPO RT FO RMarchitecture.

N o t e : If you specify function s located in libraries other thanCL IPP ER . LIB in a report d efinition and do not explicitlyreference these funct ions elsewhere in your program, you mustdeclare them to the l inker using the REQ UE ST statement . TheRE QU ES T statemen t forces the l inker to bring the code for

specif ied routines into your program even though there are noreferences to the routines in any of the compiled object modules.You can declare these functions external in any source file usingthe REQ UE ST statem ent as long i t is com piled and l inked intothe current executable f i le . Refer to the "Language Reference"chapter of the Reference Guide for more information on declaringexternal routines.

Heading He adin g is a literal string of up to four lines that displays abo vethe curren t colum n. The hea ding display s left-justified

regardless of the data type of the current column.

Formatting Yo u specify ho w a colu mn is form atted using this grou p ofoptions.

Width : Defin es the display width of the curren t colum n. If thecolumn type is numeric and the Decimals setting is greater thanzero , the W idth includes the decimal point and the decim aldigits. Th e default wid th is 10. W he n the report is run, if thecontents exceed the specified Width and the type is character, thecolu mn is wrap ped to the nex t line. If the type is nu m eric, anumeric overflow occurs and the column is filled with a row ofasterisk (*) characters.

For numeric colum ns, you can define these addit ional at t r ibutes:

D e c i m a l s : Define s the nu m be r of decim al digits to display . Th edefault is zero.





Totals: Determ ines wheth er or not a num eric column is totaled.A value of Y cau ses the colum n to be totaled. The defau lt is N,indicating that no totaling takes place. Three levels of totalingare available when the Totals setting is Y.

A grand total prints after all other report lines print and, if thereare Groups or Subgroups defined, a subtotal prints for each levelof grouping as well.

Deleting α Column

After you have add ed one or more colum n defini t ions, you candelete any colum n you do not w ant in the report definition. Todelete the current column definition, delete the Contentsexpression by pressing Ctr l+Y then use F5 Delete.

N o t e : F5 Delete will not delete a colum n definition unless theConten ts area is emp ty. This is implem ented as a precautionarymea sure to prevent you from d elet ing a column by accident .

Inserting α New Column

Since the format of the report directly relates to the order of thecolum n defini t ions, you m ay need to insert colum ns b etweenexisting colum n definitions . To do this, position the cursor at thedesired location and use F6 Insert to insert a new blank columndefini tion. This new colum n becom es the current column. Youcan then enter the column definition attributes.

N o t e : F6 Insert will not insert a colum n before the first colum ndefinition in the report.

Locating a Colum n

To naviga te to an existing colu m n definition, use F7 Goto . Amessage appears prompting you to enter the number of thedesired colum n. Pressin g Enter con firms your entry.

17-6 CA-Clipper




Defining Report Options

Columns are only a part, although a major one, of the entire

report definition you can create. There are also options you canspecify which apply at the report level . For exam ple, hea dingsand margins apply to the entire report rather than an individualcolum n. To change the default report layout , use F2 Report . Thefollowing screen displays:

FlHelp

F2 F3 F4 FB F6Groups Colunns ... ...

F7 F18Exit

File MYFILE.FRM

= Page Header =

^ H C u s t o r^ • F i r s t

i e r ReportQuarter Sales

FornattingPage Uidth gLeft Margin ΚRight Margin ΚLines Per PageDouble Space ^

Printer DirectivesPage Eject Before Print jjPage Eject After Print SPlain Page J

The report options screen allows you to define the followingreport attributes:

Page Header Prints a four line literal string on the top and center of each pag eif the Plain Page option is Ν (the default setting). You canachieve the same effect using the REPORT FORM command withthe HEADING clause .

Page Width Determ ines the num ber of characters al lowed for the com binedwid ths of all report colu m ns. Th e default is 80.

Left Margin Determ ines the num ber of characters the report is indented . Ifthe report is directed to the printer, this value is added to theSET MARGIN value. The default is eight .





Right Margin

Lines Per Page

Performs no useful function and is supplied for dBASEcompatibility purposes only. The default is zero.

Determines the total number of lines to print on each page of the

report. This nu m ber includ es the pag e head ing, colum n titles,deta il line s, and total lines. Th e default is 58.

Double Space Determines whether detai l l ines are double spaced whenprinted. The default is N.

Page Eject Before Print Determ ines wh ether C HR (12), the formfeed character, is sent tothe printer prior to the first report line. Yo u can override thisset t ing by specifying the NOEJECT clause on the REPORTFORM command l ine. The default is Y.

Page Eject After Print De term ines wh ethe r a form feed is sent to the printer after thelast report line is printe d. Yo u cann ot override this setting fromthe REPORT FORM command l ine. The default set t ing is N.

Plain Page Corresp onds to the PLA IN clause of the RE PO RT FO RMcom ma nd. If set to Y, the page heading, page numb er, andreport date are not printed and the REPORT FORM HEADINGis printe d only on the first pag e. In addition, there are no pa gebreaks. The default is N.

17-8 CA-Clipper




Defining Groups

RL allows you to define two levels of grouping in order to

sum marize information from o ne or more related database f i les .

A grou p defines a set of consecutive records having the sam e k eyvalue. Each t ime there is a new key value, a new group b eginsand a group header line prints.

Each t ime the current group ends, a sum ma ry l ine prints . I fgrouping criteria is defined and the Totals attribute on anyColumn Definition screen is set to Y, subtotals print for numericreport colum ns. W ithin a grou p, subgro ups behave in the same

manner.

To create groups for the current report, use F3 Groups and thefol lowing G roup D efini tion screen displays:

FlHelp

F2Report

F4 F5 F6ColuMns

F18Exit

File MYFILE.FRM

Group Specifications :

Group On Expression

Sunfiary Report OnlyPage Eject After Group

Sub-Group On ExpressionSub-Group Heading

DeptNoDepar tHen t .

Sub-Group Specifications

This screen allows you to define both gro up and subgro updefinitions for the current database file. If you do not define

grouping criteria, only a grand total is displayed for numericcolum ns w ith the Totals at tr ibute on the Colu mn Defini t ionscreen set to Y.





The options that you can define on this screen are describedbelow:

Group on Expression

Group Head ing

Summary Report Only

Specif ies the prim ary key expression to group on . This can be a

single field or any valid expression involving at least one field.As an example, the group expression might be DeptNo so youcan generate column totals for each department .

Spec ifies the tit le of the grou p as a li teral string. This h ead ingprints before the first report l ine for each group and just to theleft of the group expression.

Determ ines w hether detai l lines are printed in a group ed report .I f you specify Y, detai l l ines are suppressed an d only group

header and summary l ines print . The defaul t is N. Specifying Yis equivalent to specifying the SUMMARY clause on theREPORT FORM command l i ne .

Page Eject Af ter Gro up Determ ines wh ether there is a pag e eject a t the end of each gro upof recor ds. Th e defau lt valu e is N. Spec ifying Y causes eachgroup to begin on a new p age.

Subgroup on Expression Specif ies a second ary key expression defining a second level ofgroup ing. As an exam ple, if the group expression is DeptNo thesubgroup exp ress ion m ight be SalesGroup to obtain a break dow nof each sales group within a department .

Subgroup Head ing Specifies a li teral string to print at the beginning of eachsubgroup.

For groupin g to work p roperly in a report , the co rrespondingdatabase f i le must be in order according to the group andsubgroup expressions. The most convenient method forord ering a databa se file is w ith an inde x. In keep ing with theexample given above, the index key would be DeptNo +

SalesGroup. See IND EX in the "Lan gua ge Reference7 7 chapter ofthe Reference Guide for more information.

17-10 CA-Clipper




Saving the Report Definition

From any screen, you can save the Report Defini t ion using F10Exit . I f you have not mad e any change s, F10 returns you direct lyto the main menu. Otherwise, you are presented with a dialogbox in which you have three choices:

OK Save s al l change s you have mad e to the report form ( i rm ) f i leand returns you to the main menu.

No Disca rds all cha ng es, leavin g the origina l report form file intact,and return s you to the main m en u. In the case of a new file, thefile is simply not created.

C a n c e l Returns you to the current screen wh ere you can continueediting the report definition.

Printing α Report

To print a report form within an applicat ion, you must have acorresponding database file as well as an open index file ifgrouping was specif ied. Subst i tute the appropriate f i lenames inthe fo l lowing CA-Cl ipper commands and inc lude the commandsin a program to print the report:

USE <xcDatabase> INDEX <xcIndex list> NEWREPORT FORM <xcReport> TO PRINTER

There are other opt ions avai lable for the REPORT FORMcommand. See the REPORT FORM ent ry in the "LanguageReference" chapter of the Reference Guide for more informationon printing reports that you create with RL.

Pro gram m ing a nd Utilit ies G uid e 17-11




Reporting from Re lated Work A reas

Using a report form , you can print f ie ld information from mo rethan one w ork area by relat ing w ork areas using the SETREL AT ION com ma nd. There a re , how ever, severa lrequirements to make this work.

In RL, you m ust specify al l field references using an alias:

<idAlias>-xidField>

This guarantees that a field will always be available when thereport is printed.

Before you execute the REPORT FORM command, you must

have all the required database files in use and relations set in theprop er order. In one-to-one relations, report from the main w orkarea and not from the look up.

For example, suppose you have two databases f i les , Customerand ZipCo de. Custo mer is the ma in and ZipC ode is the looku plinked by a com m on f ield, Zip. The code to execute a reportform that pr ints a Cus tom er l ist w ould look something l ike:

USE ZipCode INDEX ZipCode NEW // Open the lookupUSE Customer NEW // Report from mai nSET RELATION TO Zip INTO ZipCode // Establish linkREPORT FORM CustList TO PRINTER

If the relat ionship betw een the wo rk areas is one-to-m any, theorder is reversed. Repo rt f rom the looku p work area instead ofthe m ain work area. In addit ion, the ma in work area must havean index for the linkin g key. For exam ple, this time you arereport ing Invoice amoun ts for each Custom er. The code toexecute this kind of a report would look something like:

USE Customer INDEX InvNum NEW // Open main firstUSE Invoices INDEX CustNum NEW // Report from lookup

// Establish the linkSET RELATION TO CustNum INTO CustomerREPORT FORM Custlnv TO PRINTER

17-12 CA-Clipper



Creat ing and Modifying Labels


The main menu contains a Label item that activates the labeleditor. Th e label definitio ns you can design are quite versatile ,allowing you to define label attributes such as lines per label andnumber of labels across.

From there, you can create and modify label (.lbl) fi les executablewi th the LAB EL FOR M com ma nd. For more informat ion onLA BEL F OR M refer to the "Languag e Referen ce" chapter of theReference Guide.

Creating or Modifying a Label

To create or modify a label form, select Label from the mainme nu. A f ile dialog box opens as show n below :

Report IE331 Quit

You can either create a file by entering a new filename or selectan existing file to modify from a scrolling list displayed on theright side of the dialog box. To create or ope n the (.lbl) fi le youspecified or high ligh ted, select OK . To cancel and return to themain RL menu, select Cancel .





The Label Editor Screen

After you create a new or select an existing (.lbl) file to edit, theLabe l Editor screen displays . This screen is divid ed into two

sect ions as shown below:F lHelp

FZToggle

F3Fornats

FIBExit

File MVFILE.LBLDifiensions

UidthHeightAcross

R e r i a r k s

IFornatting

Left MarginLines BetweenSpaces Betueen 1

3 1/Z χ 15/16 by 1

Contents

AddresslAddressZTRIM(City) + " + State + " " + Zip

W ithin the top sect ion you define the Dimen sions andForm atting attributes of the label. In the botto m section, youdefine the Contents expressions for each label row. When youfirst access the editor, the Dimensions and Formatting section isact ive. F2 Togg le move s the cursor betw een sect ions.

17-14 CA-Clipper




Defining the Label Dimensions an d Formatting

You can define the following label attributes in the Dimensions

and Formatting section of the Label Editor screen:

Width Determ ines the horizontal width of an individual label . Thisvalue can range from one to 255. The default is 35 characters.

Height Determ ines the vert ical num ber of l ines in an individual label .This value can range from one to 16 lines. The default is fivelines.

Across Determ ines the num ber of labels pr inted across the page. Formultiple across labels, the last label contents printed on a line ist r imm ed autom atical ly. This value can range from one to 255.The default is one label across.

Left Margin Spe cifies the left m argin and dete rm ines the first print position ofthe leftm ost label. W he n the labels are prin ted, this valu e isadded to the SET MARGIN value. This value can range fromzero to 255. The default is zero.

Lines Betw een Determ ines the num ber of blank horizontal l ines pr intedbetw een labels . This value can range from zero to 255. Th e

default is one blank line at the bottom of each label.

Spaces Between Determ ines the am oun t of ver t ical space pr inted betwe en labelsif the number of labels across is greater than one. You can alsouse this setting to set the left margin for labels after the first label.Its value can range from zero to 255, and the default is zero.

C o m m e n t s Is a com m en t field that con tains stand ard label form at sizedefin itions. Selectin g one of the label formats describe d in thenext section fil ls this area with the appropriate format definition.The defau lt l abel def in it ion is 3 1 / 2 x 1 5 / 1 6 by 1 . You can a lsocustomize the Remarks comment f ie ld using your own labelform at s ize defini t ions.




Creating and Modifying Labels

Standard Label Formats

Instead of specifying the dimension and formatting criteriadirectly, you can select a standard label format from the F3

Formats me nu. The table below gives the available s tandardformats and the resulting label dimensions and formatting:

Remarks Width Height Across Marg in Lines Spaces

3 1/ 2 χ 15 /1 6 by 1 35 5 1 0 1 0

3 1 / 2 x 1 5 / 1 6 b y 2 35 5 2 0 1 2

3 1 / 2 x 1 5 / 1 6 b y 3 3 5 5 3 0 1 2

4 χ 1 7/ 1 6 by 1 40 8 1 0 1 0

3 2/10 χ 11/12 by 3 (Cheshire) 32 5 3 0 1 2

To select one of these standard label formats, use F3 Formats.W hen the m enu appears on the screen, mo ve the highl ight to thedesired label format and press Enter. The label dimension andformatt ing information are automatical ly updated using yourselection.

Defining the Label Contents

After you have de fined the label dimension a nd formatt ingattributes, F2 Toggle moves the cursor to the Contents section inthe bot tom h alf of the Label Editor screen. It is here that youdefine the actual contents of each label row.

Dep ending on the Height you have chosen for your labeldefinition, the number of available lines in the Contents area isdefin ed. On ea ch line, you ca n enter the nam e of a field or a

mo re complicated expression. Yo u can specify most data types,including memo fields, and the expression itself can be up to 60characte rs in length. The result of a conten ts expre ssion can beany length, but a result longer than the specified label width ist runcated when pr in ted by LABEL FOR M.

17-16 CA-Clipper




For each label line, enter the expression whose result you want toprint on that l ine. For exam ple , a fam iliar label content migh t be:

TRIM(FirstName) + " " + LastNameAddresslAddress2TRIM(Cit y) + '\ " + State + " " + Zip

To enter the contents for a line, move the highlight to that l ineand begin typing the expression. Pressing Enter mo ves thehighlight to the next line.

N o t e : If yo u specify functio ns located in libraries other tha nCLIP PER .LIB in a label defini t ion a nd do not explici t ly referencethese funct ions elsewhere in your program, you must declare

them to the l inker using the RE QU EST statement . TheRE QU EST statement forces the l inker to bring the code forspecif ied rout ines into your program even though there are noreferences to the routines in any of the compiled object modules.You can declare these functions external in any source file usingthe REQ UE ST statem ent as long i t is com piled and l inked intothe current executable f i le. Refer to the "Lang uag e R efere nce "chapter of the Reference Guide for more information on declar ingexternal routines.

Important The CA-Clipper LABEL FOR M comm and does notsupport a list of expressions for the label content as in dBAS E IIIPLUS. If more than one expression is specified, a runtime error oc

Blank Lines

In CA-Clip per, a blank contents expression prints a blank l inewh en the label is pr inted. For exam ple, if you w ant a blan k l inebetw een the nam e and ad dress , the label contents might look l ikethis:

TRIM(FirstName) + " " + LastName

AddresslAddress2TRIM(City) + ", " + State + " " + Zip




Creating and Modifying Labels

If, however, a label contents expression that returns a null string("") is specified, the resulting blank line is suppressed when thelabel is prin ted. A good ex am ple of this is the second addressline in a ma iling list which is often e m pty.

To disp lay a blank line w he n the conten ts value is a null ("")string, the contents expression must return a nonprintablechara cter. You can generally enforc e this by specifying thefollowing IF() expression on the label contents line:

IF( EMPTY(< cString>) , <cString> , CHR(2 55))

You can also create a user-defined function that performs thesam e action an d use it as the label content (e.g.,NoSkip(Address2) ) :

FUNCTION NoSkip(exp)RETURN IF( EMPTY(exp), exp, CHR(255))

Saving the Label Design

When you have finished specifying the label, you can save thedefinition usin g F10 Exit. If you hav e not m ade any change s tothe current label definition, F10 returns you directly to the mainme nu. Otherw ise, you are presented with a dialog box offeringthe following three choices:

OK Save s all chan ges you hav e m ad e to the label form (.lbl) file andreturns you to the main m enu.

No Disc ards all cha nge s, leaving the original label file intact, andreturns yo u to the m ain m enu . In the case of a new file, the file issimply not created.

Ca nc el Returns you to the current screen wh ere you can continueediting the label definition.

17-18 CA-Clipper



Leaving RL

Printing the Labels

To print the label using the label definition you have designed,

you m ust have a correspon ding database f i le in USE then invokethe LABEL FORM command specifying the appropriate labeldefinition:

USE <xcDatabase> INDEX <xclndex list>LABEL FORM <xcLabel> TO PRINTER

The LAB EL FO RM co mm and has a num ber of op t ions todeterm ine wh ich records to print and whether to print a sam pleset of labels in place of the actual labe ls. Refer to the LA BE LFORM entry in the "Language Reference "chapter of the

Reference Guide for more information on printing labels.

Le avin g RL

When you have f inished designing report and label defini t ions,you can exit RL by selecting Quit or by pressing Esc from themain menu.

Prog ram m ing an d Utilit ies G uid e 17-19



The RL System Architecture

The RL System Architecture

RL is pro vide d in sourc e cod e form . If you installed CA -Clip perin the default configuration, the following source files are locatedin the \CLIP53\SOURCE\RL directory:

• Rlfront.prg

• Rlback.prg

• Rldialg.prg

The system is provided as source code so you can modify it tosui t your specif ic needs. Yo u may wan t to ma ke enhancem entsspecif ic to your development environment or s imply add the RLsystem to your application, thereby giving your users the powerto create their own reports and labels.

The RL system is broke n up into two primary su bsystems: frontand back. The RL front sub system (found in Rlfron t.prg) is theuser interface of the entire RL system . The back su bsystem(found in Rlback.prg) contains all of the routines for reading andwri t ing ( i rm) and (.lbl) fi les. Th e system is organ ized in thisway so that you can create your own user interface and easilyaccess the lower-level routines to read and write the form files.

To facilitate maintenance of the RL program files, the make file,RL .RM K, is also installed w ith the RL source files. Ass um ingyour current DOS directory is \CLIP53\SOURCE\RL, you caneasi ly rebuild RL.EX E after you m ake source code changes w iththe fol lowing command:

RMAKE RL

If your chan ges involve addit ional source m odu les or changes inthe exist ing f ile depen dencies , you w il l need to update RL.RM Kto ref lect those changes. See the "Program Maintenance—

RMAKE.EXE" chapter in this guide for more information aboutmake files.

17-20 CA-Clipper



Chapter 18

Online Documentat ion-NG.EXE


The CA-Clipper DOS-reference documentat ion is provided inthe form of several databases referred to collectively as The Guide

To CA-Clipper. It conta ins the m ost timely referenc e inform ationon CA-Clipper commands, funct ions, and ut i l i t ies .

The Guide To CA-Clipper is accessible via the N orton In stantAccess Engine™ (NG.EXE), a memory-resident program alsoincluded w ith CA-Clipp er. In the defaul t configurat ion, a ll ofthe docum entat ion d atabase f i les and the Instant Access Eng ineare installed in the \NG directory, and the PATH is updated toinclude this directory.

N o t e : The W orkb ench provide s a separate onl ine help systemfor al l menu commands, dialog boxes, and procedural s teps.From the Workbench, press Fl or cl ick on the Help pul l-downmenu to access this online help system.

In this chapter, the following general topics are discussed:

• Load ing the Instant Access Engin e

• H ow the Instant Acc ess Eng ine search es for files

• Using the Access w ind ow

• View ing a docu men tat ion database

• Instant Access Engine navigat ion keys

• Configu ring the Instant Access Engine

• Leaving the Instant Access Engine




Loading the Instant Access Engine

Loa ding the Instant A cce ss Engine

The Instant Access Engine can be loaded in two w ays:

• Mem ory-resident mode where the Instant Access Engine loadsas a TSR (terminate and stay resident) program and remainsin memory unt i l expl ici t ly removed.

• Pass through mode where the Instant Access Engine loads andthen runs a specif ied applicat ion progra m an d remains inmemory unt i l the applicat ion program terminates .

In either mode, the Instant Access Engine occupiesapproximately 65 KB of RAM, no matter how large thedocumentat ion database you access.

To use The Guide To CA-Clipper or any other documen tat iondatabase, you m ust f i rs t load N G .EXE , the Instant Access Eng ine.The general syntax is as follows:

NG [<command line>]

command line> is any val id DOS command, includingarguments . I f comm and line> is specified, NG is loaded in passthrough m ode . Otherw ise, i t is loaded in m emo ry-residentmode .

Like all other CA-Clipper utili t ies, you can execute the InstantAccess Engine from any drive or directory since the appropriatedirectory was placed in the PATH list during installation.

Using Mem ory-Resident M od e

In mem ory-residen t m ode , the Instant Access Engine remains inmemory unt i l you explici t ly remove i t f rom memory usingOption s Uninstal l or unt i l you reboot your compu ter. Thismea ns you have access to the current docum entat ion databasefrom the DOS prompt or from within any program, includingyour editor.

18-2 CA-Clipper



Loading the Instant Access Engine

Using Pass Through M od e

In pass through mode, the Instant Access Engine is loaded intomemory, then the command l ine program is executed.Terminating the command l ine program automatical ly removesthe Instant Access Engine from mem ory. This means that youhave access to a documentation database only as long as thecom ma nd l ine program is running . For exam ple, the fol lowingcom ma nd l ine loads the Instant Access En gine then theCA-Clipper program editor:

NG PE Sample.prg

While operating in the editor, you can activate the Instant AccessEngine at any t ime to view the current docu men tat ion database.When you save the program file you are editing and leave theeditor, the Instant Access Engine is automatically removed frommemory.

Access ing the Instant Acce ss Engine

Once the Instant Access Engine is loaded, you can access thecurrent docum entat ion d atabase by pressing the activat ion hotkey. The default hot key is Sh ift +F l. If this conflicts with a keyused by another program, you can change it to a new valueusing the Options Hot key menu item described later in thischapter.

N o t e : If you are using DO S 5.0 or later, you m ust press Escimm ediately af ter Sh if t+F l to act ivate the Instant Access Eng ine.I f you p lace the s ta tement SWITCHES=/k in your CONFIG.SYSfile, you will not have to press Esc.

Important The Instant Access Engine will not display if your screeis currently in graphics mode. If the screen is in either EG A 43-line VGA 50-line mode, the Instant Access Eng ine will display using 24lines only.




How the Instant Access Engine Searches for Files

How the Instant Access Engine Searches for Files

The Instant Access Eng ine can display documen tat ion databases

from any drive or directory, as long as they are in the currentdirectory or the same directory as NG .EX E. W hen you access theOptions D atabase to select a docum entat ion database to view,the Instant Access Engine shows a scrolling list of documentationdatabases from the NG.EXE directory fol lowed bydocu men tat ion databases foun d in the current directory.

All docum entat ion databases that are part of the C A-Clipperdeve lopme nt system w ere placed in the same directory asNG.EXE during instal lat ion; therefore, The Guide To CA-Clipperis accessible regardless of the drive and directory that is currentwhen you load the Instant Access Engine.

Tip: If you pur cha se a third-pa rty produ ct that include s acompatible documentat ion database, copy the database intothe \NG directory. This makes the database accessible fromthe Options Da tabase l is t indepen dent of your currentdirectory location.

18-4 CA-Clipper



Using the Access Window


When the Instant Access Engine is f i rs t act ivated, a windowappears s imilar to the one shown below:

CR-Clipper 5.3 » The Guide To CA-C Upper » Language » FunctionsSearch... Options Language Tables

A B S OACHOICEOACLONEΟACOPVOADELOA D I R O *AEUALOAFIELDSO*AFILLOAINSOALERTOALIASO

ALL TBI P I C )ALT D OARRAVOA S C OASCANOASIZEOASORTOΑΤ Ο

mmReturn the absolute ualue o f a nuneric expressionExecute a pop-up Menu.Duplicate * nested or nullLdlfiensional arrayCopy elenents FroM one array to anotherDelete an array elenentFill a series of arrays with directory informationExecute a code block For each elenent i n an arrayFill arrays wi th the structure of t hE current database fileFill an array uith a specified valueInsert a NIL elenent into an arrayDisplay a sinple Modal dialog boxReturn a specified uork area alias

Relieve leading and trailing spaces from a character stringInvoke The CA-Clipper DebuggerCreate an uninitialized array o f specified lengthConvert a character to its ASCII ualueScan an array For a ualue or until a block returns true <,T.)Grou or shrink an arraySort an arrayReturn the position o f a substring uithin a character string

At the top of the screen is the nam e of the current docu me ntat iondatabase fol lowed by the major and minor category names . Justbelow this is the men u bar.

The Menu Bar

The m enu bar prov ides you w ith opt ions to select differentdocumentat ion databases to view, search for keywords in thecurrent list of short entries, and change the default configurationof the Instant Access Engine. The f i rs t three menu s d isplayed(that is , Exp and , Search, and O ptions) are Instant Access Engin esys tem menus and are a lways d isp layed . The remain ing m enu sare placed on the men u bar by the current d ocum entat iondatabase.

A menu can execute a funct ion direct ly, prompt you for input , orpul l down a menu. Of the system menus, Expand executes afunct ion direct ly, Search display s an input f ie ld, and Op tionspulls down a menu of configurat ion i tems.





Selecting Menus and Menu Items

W hen the men u bar is act ive, you ca n select a menu ei ther bypressing the first letter of the menu name or by moving the

high light us ing the Right or Left arrow . If yo u use the first lettermeth od to select e i ther the Expan d or the Search m enu , pressingthe key execu tes the m enu . If you use the Direc tion keys tonavigate to a m enu , you must press Enter to execute the men u.

When you access a pul l-down menu, a l is t of menu i temsappea rs . You can then select a me nu i tem the same wa y youselect a menu: either by using the first letter method or bymo ving the highl ight to the desired i tem with Up or Dow n arrowand pressing Enter.

To cancel a pul l-down menu, press Esc and the highl ight movesback to the Expand menu.

Sizing an d Moving the A ccess W indow

By default, the Ac cess win do w takes up the entire screen. If youneed to see the application program screen without exiting theInstant Access En gine, the Op tions Full screen men u i tem, or F9,toggles the s ize of the Access w indo w be tween ful l -screen andhalf-screen mod es. A check mark indicates the current mode isfull-screen.

When the Access window is act ivated in half-screen mode, i tpops up either at the top or the bottom of the screen, whicheveris furthest aw ay from the current cursor position. If the Accesswindow obscures important information on the applicat ionprogram screen, you can move the window up or down on thescreen.

To do this , press Scrol l lock then use Up arrow , Do w n arrow ,PgU p, or PgD n to mo ve the w indo w to a new locat ion. W henyou have finished, press Scroll lock again to freeze the windowposi t ion. No te, how ever, that the Instant Access Engine does notrem em ber the new w indo w locat ion. Each time you exi t andreact ivate in half-screen mode, the Access window always popsup away from the cursor.

18-6 CA-Clipper




Getting Help

While viewing in the Access window, you can pop up a help

window like the one shown below by pressing Fl:Cft-Clipper 5.3 w The Guide To Cft-Clipper » Language » Functions

Search... Options Language Tables

About the No.'t · ιη Go itVs.

<t?u E > Back up one level Ctrl S Continue last dearthF9 Ft 11/ha If screen Grey Shou pro long entryFl Η Exit the Guides Grey + Siiou next long entry

The Norton Guides, Iters ion 1 0BCopyright < C) 1987 by Peter Norton Computing

Fro a ran designed and ur liter by John Soc;J αFrts.F.'l on Lin idea by ~l •*> Uorjrlf ο r*d

Cur r i?nt. database: CP-Clipper Β ή » The Guide To CA-Clipptr

The Guide To Cfi Clipper, Copyright. <C J -enputpp A P S C C I atm .

I.eyend- L drritles cha iget ΜΛΙ ΙΊ'Ϊ ΛΙdi notes neu rateri <1

* denctes obsolete iteris r us*ie

BIH2 TO Comiert a 16-bit signed integer to a numeric ualue

This window gives you information about the Instant AccessEngine and the current documentation database.

Programming an d Utilities Gui de 18-7



Viewing α Documenta t ion Da tabase

Viewing a Docu m enta t ion Da taba se

A docum entat ion database is a hierarchical s tructure consist ingof the following items:

• Menus

• M enu i tems

• Short entries

• Lon g entries

• See also referenc es

In a typical documentation database, a menu lists a series ofcatego ries as its item s. Each m en u item , in turn, refers to a list ofshort entries or a single long entry. Eac h short entry can alsorefer to an oth er list of short entries or a long en try. If yo uconsider a docu men tat ion d atabase as a tree s tructure, longentries are nodes of the tree and contain the actual topicalinform ation. Since long entries are the nod es of the inform ationt ree, they can only refer to other long entries by way of the SeeAlso list.

18-8 CA-Clipper




The Short Entry List

Having selected a subject area of the current documentat ion

database using the menu system, you are general ly presentedwith a list of short entries. Short entries usu ally consist of akeyword, such as a command or funct ion name, fol lowed by ashort descript ion. For examp le, the fol lowing show s the shortentry l is t of CA -Clipp er funct ions:

CA-Cllpper 5.3Search -,.

The Guide To CA-C Uppe r » Language i > FunctionsOptions Language Tables

A B S OACHOICEOACLONEΟACOPVOADELOA D I R O *AEUALOAFIELDSO *AFILLOAINSOALERTOALIASOALL ΤΗ I H OALTDOARRAVOA S C OASCANOASIZEOASORTOΑΤ Ο

[SEEDSReturn t he absolute ualue of a nuneric expressionExecute a pop-up MenuDuplicate a nested or nultidinensional arrayCopy elenents Fron one array to anotherDelete an array elenentFill a se ries of arrays with directory informationExecute a code block Tor each elenent in an arrayFill arrays with the structure nf the current database fileFill an array with a specified ualueInsert a NIL elerent into an arrayDisplay a sinple Modal dialog box

Return a specified uork area aliasReMove leading and trailing spaces fron a character stringIntake The CA-C1 ipper Deb ugger 5j ':Create an uninitialized array of specified lengthConvert a character to its ASCII ualueScan an array For a ualue or until a block returns true <. T, >Grou or shrink an arraySort an arrayReturn the position of a substring within a character string ||

To navigate a short entry list , you can use the typical cursornavigat ion keys (refer to the Instant Access Engine Nav igat ionKeys section later in this chapter) or the Search menu.





Searchin g a Short Entry List

Instead of scrolling or paging through a list of short entries, youcan search for a short entry containing a specified text string

using the Search m enu . W hen yo u select Search, a dialog boxpops up into which you can enter a string to locate.

If you hav e already pe rform ed a search, the previous searchstr ing reappe ars . To enter a new search s tr ing, begin typing andthe prev ious entry is auto ma tically erase d. If you wis h to editthe exist ing text, press Ho me (or any other cursor m ove me ntkey) before typing any new text.

Once you hav e entered the search s tr ing, press Enter to perform

the search operat ion. Searching begins with the next entry andcontin ues to the end of the list . If there is no ma tch, the searchcontinues from the top of the list .

The search operation is not case-sensitive, allowing you to useany combinat ion of uppercase and lowercase let ters . In addit ion,each search scans short entries for a matching substring,allow ing you to specify a partial search string. For exam ple , ifFunctions is the current short entry list , searching for "ST"locates the short entry for STR().

To continue a search for the next occurrence of the search string,re-execute the Search menu or press Ctr l+S.

Expanding an Entry—Moving Down a Level

Once you have located a short entry of interest, you can move toa lower-level in the database hierarchy by executing the Expandm en u. The refere nce d entry can be another short entry list or along entry.

Note that Expand is always the defaul t menu unless youexplici tly access another men u. Even then, after you mak e aselect ion the highl ight automatical ly moves back to Expand.This makes moving down a level very easy s ince pressing Enteralmost invariably executes Expand.

18-10 CA-Clipper



Vi e w in g α D o c u m e n t a t i o n D a t a b a s e

If the referenced entry is a long entry, the Access windowdisplay area is replaced with the long entry text and the menubar with the associa ted See Also list. On ce you are located

within a long entry, you can naviga te using the curso r keys. Forexam ple , Up ar row, Down ar row, PgU p, and PgDn m ove wi th inthe win dow , wh ile Left and Right arrow navigate the See Alsoreferences (if there are any).

See Also References

Within a long entry, the menu bar is replaced with a list of SeeAlso references. A See Also reference al lows you to naviga tedirectly to another long entry without navigating through themenus and short entry lists.

To select a See Also reference, move the highlight using Left orRigh t arrow and press Enter. You can also select a See A lsoreferenc e using the first letter m etho d and pressing Enter. Th efollowing shows a typical long entry and See Also list:= — CA-Clipper 5.3 » The Guide To Cn -Clipper » Language » Functions » .

See also: |&UU| STRTRfiNO SUBSTRO

ΑΤ ΟReturn the position of a substring uithin a character string

Syntax

AT(<cSearch>, <cTa rget » — > nPosition

Arguments

<cSearch> is the character substring to search for.

<cTarget> is the character string to search.

Returns

Α Τ Ο returns the position of the first instance af <cSearch> uithin<cTarget> as an integer nuneric value. If <c.Search> is not found, fl TOreturns zero.

Description





If you navigated to the current long entry by way of a See Alsoreference, the Instant Access En gine provides tw o way s to returnto the referring long entry:

• If the curren t long entry has the referring long entry nam e asa See Also referen ce, that referenc e is high lighted . To returnto the referring long entry, press En ter. As an exam ple, ifyou begin w ith the SU BST R() funct ion long entry andexecute the AT() See Also reference, the SUB STR () See Alsoreferenc e in the AT () long entry is high lighted . By pre ssingEnter you return to the SUB STR () long entry, and the AT ()See Also reference is again highligh ted. In this w ay , you canmo ve quickly betwe en tw o related long entr ies by pressingEnter c onsecutively.

• If there is no See Also reference to the referring long entry inthe current See Also list , the Instant Access Engine puts aspecial See Also reference, Previous, at the end of the currentlist . As befor e, yo u can press En ter to return to the referringlong entry. Note, how ever, the Instant Access Engineremembers only one level of reference with Previous.

Moving Up α Level

From any level in the database hierarchy, you can mo ve up tothe pre viou s level by press ing Esc. If you are currently locatedin a long entry, this moves you up to the referring short entrylist. If you are at the top level of the datab ase hiera rchy , Esccauses you to exit the Instant Access Engine altogether.

N o t e : If you accide ntally exit the Instant Access Engin e wh enyou press Esc, simply reactivate it using the hot key.

18-12 CA-Clipper



Vi e w in g α D o c u m e n t a t io n D a t a b a s e

Selecting a N ew Docum entation Datab ase

To select another do cum entat ion database to view, use the

Options D atabase m enu i tem. This al lows you to select adocumentation database from a scrolling list as shown in thefollowing screen:

= — CA-Clipper 5.3 » The Guide To CA-Clipper » LanguageExpand Search... lluHWSHI Language Tables

Functions

A B S OA C H O I C E OA C L O N E OA C O P Y OA D E L OA D I R O *A E U A L OAFIELDSO*A F I L L OA I N S OALERTC)ALIASC)ALLTRIflOA LT D OA R R AV OA S C OA S C A N OA S I Z E OA S O RT OΑΤΟ

Return the absolute ualue of a miner ic expression

μ CA-Clipper b,3 » The Guide To CH-Clipper|CA Clipper 5.3 'Λ Error MessagesCA Clipper h 1 >· API Refere nceCA-Clipper b i >- Util itie s

It abase file

ΐ|ter stri ng ))

Invoke The CA-Clipper DebuggerCreate an uninitialized array of specified lengthConvert a character to its ASCII value :YScan an array for a ualue or until a block returns true < M \ } '• '··Grou or shrink an array i|

Sort an arrayRetur n the position of a substring uithin a character string ||

Documentat ion databases found in the NG.EXE directory are

listed first, followed by those found in the current directory.Documentat ion databases are arranged in the order the actualdataba se ( .NG) f i les are encou ntered. To change the order, youmust physically sort the .NG files with a disk utility.

To select a new documentat ion database to view, navigate thel is t using Up arrow, Down arrow, Home, or End, and pressEnter to select the current ly highlighted docum entat iondatabase. Esc cancels the selection.




Instant Access Engine Navigation Keys

Instant Access Engine Navigation Keys

The followin g is a list of all the navigatio n k eys available wh ileyou are operating within the Instant Access Engine:

Key Funct ion M o d e

F l Help All

F9 Fu ll /half-scree n toggle All

F10, Shi f t+Fl Exit All

Esc Up a levelExit

Short , LongTop-level Short

Enter Do wn a levelSelect itemSelect See Also

ShortMenu bar, MenuLong

Gray - Previous long i tem Long

Gray + Next long i tem Long

Ctr l+S Con tinue last search Long

Scroll lock Enab le /d isable moving Al l

Up arrow Previous i temPrevious line

Window up a l ine

Menu, ShortLong

MoveDo wn arrow Next i tem

Next lineWindow down a l ine

Menu, ShortLongMove

Left arrow Previous i tem Menu bar, See also

Right arrow Nex t i tem Menu bar, See alsoContinued

18-14 CA-Clipper



Configuring the Instant Access Engine

Continued

Key Funct ion M o d e

PgUp Last item previous screen ShortLast l ine previo us screen Lon gW indow to top Mo ve

PgDn First i tem next screen ShortFirst l ine next screen Lon gW indow to bot tom M ove

H om e Firs t short i tem ShortFirst line LongM ove wind ow top M ove

End Last short i tem ShortLast l ine LongWind ow to bot tom M ove


The Options menu al lows you to change certain parametersaffect ing the display an d operat ion of the instant Access En gine.

The menu contains the fol lowing i tems:• Database

• Color

• Full screen F9

• Au to looku p

• Ho t key

• Uninstall

• Save opt ions

The Database and Full screen i tems have already been discussed.The remaining options are discussed in this section.





Toggling Color

The Options Color menu item toggles color and is useful only ifyou have a color monito r. A check m ark indicates that color is

on.

Toggling Auto Lookup

The Options Auto lookup menu i tem toggles the automaticsearch mode. A check mark indicates the mo de is turned on.

When this option is on, activating the Instant Access Engineautomatically searches the current short entry list for the word at

the application prog ram curso r position. If foun d, the match ingentry is highlighted in the short entry list .

If Auto lookup is off, the entry highlighted when you last left theInstant Access Engine is still highlighted when you reactivate it .

This menu item is very useful if you are accessing the InstantAccess Engine from you r edi tor wh ile wri ting or edi t ing apro gram . For instanc e, if you do not kn ow the correct syntax fora funct ion you can type the funct ion nam e and press S hif t +F l .The function wil l be highlighted automatical ly and pressingEnter zooms into the long entry for that function, allowing you toview the funct ion 's syntax.

18-16 CA-Clipper




Changing the Hot Key

The Options Hot key menu item allows you to change the key

pressed to activate or exit the Instant Access Engine. The defaulthot key is Shift+Fl, but you can change this to any valid keyincluding the Shift, Alt, and Ctrl key combinations. When youselect Options Hot key, the dialog box shown below displays:

— CA-Clipper 5.3Expand Search

The Guide To CA~CU pper » LanguageLanguage Tables

Functions

ABSOACHQICEOACLONEOACOPVOADELOA D I R O *AEUALO

A F I E L D S O *AFILLOAINSOALERTOALIASOALLTRINOALTDOARRAVOASCOASCAHOASIZEOASORTOΑΤΟ

Return the absolute galue of a numeric expressionExej

al arrayher

Du]Co;Del|Fi l ^ U ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ B ^ H r y infornation^ x i b ^ ^ ^ ^ ^ ^ ^ ^ ^ arrayFill arrays uith the structure of tke current database FFill an array uith a specified ualueInsert a MIL elerient into an arrayDisplay a sinple nodal dialog boxReturn a specified uork area aliasRenoue leading and trailing spaces froM a character striInvoke The CA-Clipper DebuggerCreate an uninitialized array of specified lengthConuert a character to its ASCII ualueScan an array for a ualue or until a block returns trueGrou or shrink an arraySort an arrayReturn the position of a substring uithin a character st

To change the hot key, press the new hot key or key combinationthat you want to use. Pressing Enter confirms your choice, andpressing Esc cancels any changes you have made.

Note Since the Instant Access Engine hot key takes precedenceover your application program key definition for the same key,be sure to choose a hot key that does not conflict with othersoftware that you are using.

Saving the New Configuration

While you are using the Instant Access Engine, items that youchange in the Options menu remain in effect until you removethe Instant Access Engine from memory. If you want to saveyour changes as the new default settings, execute the OptionsSave options menu item. Then, the next time you load theInstant Access Engine, these settings will be the default settings.

Prog ramming an d Utilities Gui de 18-17



Leaving the Instant Access Engine

When you execute the Options Save opt ions menu i tem, theInstant Access Engine sav es the current opt ions in NG .INI,located in the same directory as NG.EXE.

Leaving the Instant Access Engine

To leave the Instant Access Engine, you can either return towhere you were in your applicat ion program or remove theInstant Access Engine from memory.

Exiting the Instant Access Engine

W hen y ou hav e f inished viewing in the Instant Access E ngine,you can return to the original position in your applicationprog ram b y pressing the hot key or F10 from an y level or view.You can also press Esc from the top-level short entry list .

Uninstalling the Instant Access Engine

If you loaded the Instant Access Engine in memory-resident

mode, you can remove the Instant Access Engine from memoryusing the Op tions Uninstal l men u i tem. If you loaded the InstantAccess En gine in pass through m od e, the Engin e is automatical lyunloaded from memory when the launched applicat ion istermina ted, and the Options Un instal l is not o perat ional .

N o t e : In som e cases, yo u may not be able to rem ov e the InstantAccess Engine from mem ory. This m ay occur i f you loadanother memory-resident program after the Instant AccessEn gin e, and it is still m em ory -resid ent. If this ha pp ens , uninstallthe memory-resident program loaded af ter the Instant AccessEn gin e, then uninstall the Instan t Acc ess Engine . Failing this,you may have to reboot your computer using Ctr l+Alt+Delete .

18-18 CA-Clipper



Appendix A

CLIPPER.BMLThis appendix provides information about the resource f i les thatare included in the CL IPP ER .BM L bitma p l ibrary fi le . This f i le isinstalled in the \CLIP53\LIB directory . A listing of the files inCLIPPER.BML can be obtained by using theB M L D I R . C O M utility, which is also installed in the\CLIP53\BIN directory.

The fol low ing table describes the avai lable bi tmap f i les:

Fi le Graph ic Descr ip t ion

ARROW_D.BMU • Down arrow used by vert icalscroll bars

ARROW_E.BMU Thumb wheel used in scrol lbars

ARROW_L.BMU Left arrow used by horizontalscroll bars

ARROW_R.BMU Β Right arrow used by horizontalscroll bars

A R R O W J J . B M U • Up arrow used by vert icalscroll bars

CHECK_E.BMU IB3 Unselected check box

CHECK_F.BMU Μ Selected check box

DROPBOX.BMU Μ Drop-down l is t box

RADICLE.BMU Unselected radio but tonRADIO_F.BMU • Selected radio but ton

Prog ram ming a n d Utilit ies G uid e A - l

http://clip53/LIB

http://bmldir.com/

http://clip53/BIN

http://clip53/BIN

http://bmldir.com/

http://clip53/LIB



CLIPPER.BML

The following tables list the available font ( .FNT/.FND) files:

.FNT Files .FNT Files

ARIAL04 .FNT C_NEW14.FNT





ARIAL12 .FNT CJMEW36.FNT

A R I A L 1 4 . F N T C J N E W 4 0 . F N T

ARIAL16 .FNT SMALL06 .FNT

ARIAL20 .FNT TNR04 .FNT






C_NEW04.FNT TNR14 .FNT






A-2 CA-Clipper



CLIPPER.BML

.FND Files .FND Files

ANTIQUE.FND FRESN.FNDBIGSF.FND ITALICFND

BLOCK.FND KIDS.FND

BOLD.FND NORMS.FND

BOXROUND.FND OCR.FND

BWAY.FND ROM8PIX.FND

CNTDOWN.FND ROMAN.FND

COURRIER.FND THIN1.FND

CURFONT.FND THIN2.FND

Programming an d Utilities Guide A-3





Index

(negate), 2-53

= (not equal), 2-52

#

# (not equal), 2-52

#include, 2-8, See also Header files, 10-14

$

$ (substring), 2-52

%

% (modulus), 2-51

%= (modulus and assign), 2-57

&

& (compile and ru n), 2-60, 2-66, 2-80, 2-95

&& (com ment), 2-8

(

() (g rou p), 2-49, 2-60, 2-65

* (comm ent), 2-8

* (multiplication), 2-51

** (exponentiation), 2-51

** - (exponentiation and assign), 2-57

V (comment), 2-8

*= (multiplication and assign), 2-57

+

+ (addition), 2-51

+ (concatenation), 2-50

++ (increment), 2-58

+= (addition and assign), 2-57

+= (concatenate and assign), 2-57

Prog ram min g a n d Utilit ies G uid e Index-1



/

- (concatenation), 2-50

- (subtraction), 2-51

- (decrem ent), 2-58

-= (concatenate and assign), 2-57

-= (subtraction and assign), 2-57

-> (alias), 2-33, 2-60

.AND., 2-53

AND., truth table, 2-53

.dbf files, 2-105 , S ee also Database files

.dbt files, See also Mem o fields, Memo files,2-42, 2-105

.EXEignoring linking errors, 11-20including specified packages, 11-21

loading into m emory, 11-2overriding environmental settings,11-17

specifying default options, 11-18

.ndx files, 2-109, See also Index files

.NOT., 2-53

.NOT., truth table, 2-53

.ntx files, 2-109 , See also Index files

.OR., 2-53

.OR., truth table, 2-53

.ppo files, 10-7,10 -10,10-1 6

.RMK file, See Make file

.RTLink, using, 11-5

.vew file, 1 6-13,16-1 7,16-24

/ (division), 2-51

/* (comment), 2-8/ / (comment), 2-8

/ = (division and assign), 2-57

/B compiler option, See Compiler options,See Compiler options

: (send), 2-97, 2-98, 2-99

:= (inline assign), 2-56, 2-57, 2-77, 2-99

; (continuation), 2-9

<

< (less than), 2-52

<= (less than or equal), 2-52

<> (not equal), 2-52

= (assign), 2-55, 2-57, 2-77

- (equa l), 2-52, 2-55

== (array equivalence), 2-84

== (equal), 2-52

== (exactly equal), 2-52

lndex-2 CA-Cl ipper



> I

> (greater than), 2-52>= (greater than or equal), 2-52

?, 13-5,13-51,13-53,13-55,13-56,13-64,13-82,13-83,13-84,13-85,13-87

@ (pass by reference), 2-17

@ (pass-by-reference), 2-60

©...GET, 4-7

@...SAY, 2-116

(

[] (array elem ent), 2-60

Λ

Λ (exponentiation), 2-51

Λ = (exponentiation and assign), 2-57

{

{} (array delimiter), 2-60, 2-80

{} (code block d elimiter), 2-60, 2-89

I I (code block argument delimiter), 2-60,2-89

A

A20 problems, 11-37

AAD D(), 2-83, 2-85

Accelerator keys, 8-2, 8-7, 8-12

Accessing DOS, 13-62,13-71

ACLONE(), 2-86

ACOPY(), 2-86

Add Rec(), 4-10

ADELQ, 2-86

AEVALQ, 2-90example, 2-82general discussion, 2-57

AFILL(), 2-77

AINS(), 2-86

Aliasexpressions, 2-60field, 2-55operator, 2-60, 2-101

ALTD(), 2-122,13-12

APPEND BLA NK, 4-10

APPEND FRO M, 4-4application

controlling execution of, 13-9viewing screen, 13-10

Application failures, 11-31

ARRAYQ, 2-75, 2-77

Program ming a n d Utilities Gu ide lndex-3



Arraysadding new elem ents, 2-85addressing elements, 2-76and the macro operator, 2-71as return values, 2-20, 2-81assigning values to, 2-77changing the size of, 2-83, 2-85comparison, 2-84constant, 2-60, 2-80copying elements, 2-86creating, 2-75definition, 2-75deleting elements, 2-85, 2-86determining number of elements in,2-84determining size of, 2-84duplicating, 2-86

subarrays, 2-86dynamic, 2-75empty, 2-83, 2-84equivalence, 2-84general discussion, 2-75growing, 2-83, 2-85initializing, 2 -77inserting elements, 2-86lexically scoped, 2-75literal, 2-80

local, 2-75multidimensional, 2-75, 2-79, 2-86passing as parameters, 2-16, 2-18, 2-81private, 2-75public, 2-75scanning for a value, 2-88shrinking, 2-85sorting, 2-87static, 2-75subscript numbering, 2-76syntax for addressing, 2-76

syntax for creating, 2-75traversing, 2-82

used with macro operator, 2-80

ASC AN(), 2-88

ASCII files, See also Outpu t to text file

ASIZEQ, 2-83, 2-85

ASO RT(), 2-87

Assignmentarray,2-77operators, 2-55, 2-57, 2-77

precedence of operators, 2-62, 2-65table of compound operators, 2-57

AT&T 6300 Plus, runningCA-Clipper/Exospace on, 11-35

AUTOEXEC.BAT, 3-2

Automatically overlaying code, 11-2

Bad memory, 11-39

BADCACHE, 3-10, 3-12

Beginning of file, 2-126

BIN directory, 10 -13,11-7 ,15-2,16 -2

Binary fileclosing a, 2-126creating a, 2-124

moving pointer in a, 2-126opening a, 2-124reading a, 2-125, 2-126writing to a, 2-125, 2-126

BIOSincompatibility withCA-Clipper/Exospace, 11-31,11-32Interrupt 15h, function 88h, used byCA-Clipper/Exospace, 11-46

Blinker commands# (comm ent), 12-4/ / (comment), 12-5@ (nested script), 12-5BEGINAREA, 12-6BLINKER CACHE EMS, 12-7BLINKER CACHE XMS, 12-8BLINKER CLIPPER PAGE, 12-9

lndex-4 CA-Clipper



BLINKER ENVIRONM ENT CLIPPER,12-9BLINKER ENVIRONMENT NAME,

12-10BLINKER ENVIRONMENTOVERRIDE, 12-11BLINKER EXECUTABLE CLIPPER,12-12BLINKER EXECUTABLE NODELETE,12-14BLINKER LINK EMS, 12-14BLINKER LINK PAGEFRA ME, 12-15BLINKER LINK XMS, 12-15BLINKER MESSAGE D UPLICATES,12-16BLINKER M ESSAGE NO BLINK, 12-17BLINKER MESSAGE NOWARNING,12-18BLINKER M ESSAGE WINK , 12-18BLINKER OVERLAY O PSIZE, 12-19BLINKER OVERLAY PAGEFRAME,12-20BLINKER OVERLAY THRESHOLD,12-21BLINKER O VERLAY U MB , 12-22BLINKER PROCEDURE DEPTH , 12-23

DEFINE, 12-24DEFL IB, 12-25ECHO, 12-25ENDAREA, 12-26EXTDICTIONARY, 12-26FILE, 12-27LIBRARY, 12-28MAP, 12-29MIXCASE, 12-29MO DULE, 12-30MURPH Y, 12-32

NOBELL, 12-32NODEFLIB, 12-33NOEXTDICTIONARY, 12-33NOTABLEOFCONTENTS, 12-34OUTPUT, 12-34READONLY, 12-35SEARCH, 12-35SECTION INTO, 12-36

STACK, 12-37UPPERC ASE, 12-38VERBO SE, 12-38

WO RKFILE, 12-39Blinker functions, BLIVERNUM, 12-40

Blinker, using, 11-5

BLINKER.TXT, 12-3

BML2RESGOM, 5-12

BMLDIRGOM, 5-12

Boolean algebra, 2-46, 2-53

BP, 13-14,13-22,13-58,13-66 , See also PointBreakpointBranching, conditional, 2-25, 2-26

Breakpoints, 13-4,13-47 ,13-57,13-61 ,13-72,13-73,13-106,13-112

definition, 13-57,13-66 ,13-101deleting, 13-22,13-59,13-66,13-69,13-101listing, 13-59,13-76setting, 13-14,13-2 2,13-51,13-58,13-6 6,13-101

Buffer, management in a networkenvironment, 4-8

c

CA-Clipper5.01 or 5.01a

linking, 11-15

specifying, 11-15bitmap library, 1-1CLIPPER.BML, 5-13,1-1debugger, 11-33,11-34procedure stack, setting m aximumdepth, 11-23UNIVESA.EXE, 5-17

Program ming an d Utilities Gu ide lndex-5



CA-Clipper/Exospaceapplication failures, 11-31BIOS Interrupt 15h, function 88h, 11-46compatibility, 11-41compatibility with

DOS, 11-47DOS 5.0 and 6.0,11-47DOS 5.0 Task Switcher, 11-48OS/2 Virtual DOS Machines, 11-49third-party libraries, 11-41

device drivers, 11-46DOS return code, 11-7,11-10DPMI extended m emory protocol, 11-44error handling, 11-7extended mem ory, 11-43incompatibility with BIOS, 11-31,11-32input files, 11-10invoking, 11-4linking with

.RTLink, 11-5Blinker, 11-5

loading, 11-2memory

requirements, 11-43shortage, 11-32

output files, 11-8overview, 11-2path searching, 11-10problems with applications, 11-31running

an application, 11-41on AT&T 6300 Plus, 11-35

script file, 11-4,11-11searching for memory managers, 11-45software

compatibility with, 11-35incompatibility, 11-32

syntax for, 11-4

temporary file directory, 11-9VCPI extended m emory protocol, 11-44working in

Carousel environment, 11-47DESQview environment, 11-47DoubleDOS environment, 11-47Windows environment, 11-47

XMS extended memory protocol, 11-44

CA-Clipper/Exospace commandsabbreviations, 11-12EXOSPACE CLIPPER 501,11-15EXOSPACE ENVIRONMENT CLIPPER,11-16,11-17,11-19EXOSPACE ENVIRONMENTOVERRIDE, 11-17,11-19EXOSPACE EXECUTABLE CLIPPER,11-17,11-18EXOSPACE EXECUTABLENODE LETE, 11-7,11-20EXOSPACE PACK AGE, 11-21,11-22EXOSPACE PROCEDURE DEPTH,11-23,11-30FILE, 11-8,11-24ignored .RTLink commands, 11-13ignored Blinker commands, 11-14LIBRAR Y, 11-25list of, 11-12MA P, 11-9,11-26MODULE...FROM, 11-13,11-27NODEFLIB, 11-28OUTPUT, 11-8,11-29specifying, 11-5STACK , 11-30supported .RTLink commands, 11-13supported Blinker commands, 11-14

Call Stack, 13-60

Calling conventionscomm and, 2-5, 2-17function, 2-5, 2-17, 2-18

Callstack, 13-39,13-68, See also ViewCallstack, 13-115

Callstack window , See Windows

Carousel environment, 11-47

Cascading menus, 8-2, 8-15, 8-17

CASE, See also DO CASE

CGACURS, 3-10

lndex-6 CA-Clipper



Changing name ofBLINKER environment variable, 12-10CLIPPER environment variable, 11-16,12-9

Changing the DOS E nvironment Size, 3-4

Character stringcomparison, 2-42, 2-43constants, 2-41delimiters, 2-41fixed length, 2-40literals, 2-41maximum length of, 2-40operators, 2-50, 2-57precedence of operators, 2-62table of operators, 2-50variable length, 2-42

CHR(), 2-121

CL.BAT, 10-13,11-7

Class, See also Objectsdefinition, 2-96

CLD.LIB, 13-11,13-12command line syntax, 13-7

CLEAR TYPEAHEAD, 2-123CLIPPER

BADCA CHE setting, 3-10, 3-12CGAC URS setting, 3-10DYNF setting, 3-10F setting, 3-12INFO setting, 3-12NOIDLE setting, 3-13SWAPK setting, 3-14SWA PPATH setting, 3-14TEMPPA TH setting, 3-14X setting, 3-15

CLIPPER.BM L, 5-13

CLIPPER.EXEcommand line syntax, 10-2

CLIPPER.LIB, 10-7,11-25,11-28

CLIPPERCMD, 10-3,10-4

Closing filesdatabase, 2-112

index, 2-112low-level, 2-126

Code blocks, 13-5,13-60and the macro operator, 2-72as return values, 2-20compared to macro expressions, 2-73,2-89compiling with m acro operator, 2-68,2-95creating, 2-60, 2-89evaluating, 2-90evaluating for arrays, 2-82evaluating for database records, 2-109example using, 2-92, 2-93general discussion, 2-89passing as parameters, 2-16syntax for defining, 2-89used to sort arrays, 2-87variable scoping within a, 2-30, 2-90

Code pagingdisabling, 12-9

enabling, 12-9Code window, See Windows

Command window, See W indows

Com mands,user-defined, 2-89, 2-109

Comments, 2-8

COMMIT, 2-112

Compatibility, See also dBASE III PLUScompatibility

notes, 11-35previous releases, 2-123, 3-5

Compilation, conditional, 10-5

Compile and link batch file, 10-13,11-7

Pro gram min g a n d Utilit ies G uid e lndex-7



Compilerchecking syntax with, 10-7configuration, 10-3DOS return code, 10-9,10-13error handling, 10-9,10-13include file directory, 10-5,10-14options, 10-4output files, 10-15script file, 1 0-2,10 -9,10-1 2switches, 10-4syntax for, 10-2temporary file directory, 10-7,10-15

Compiler assumptions, 2-101

Compiler options/ B , 13-6,13-7/P , 13-6

Compiler switches/A , 10-4/ B , 10-4,10-6/D , 10-5/ES, 10-5/1,10-5,10-14/L , 10-3,10-4,10-6,10-7/M , 10-6,10-7,10-9,10-12/N , 2 -4, 2-20, 2-30, 2-35,10-6/ 0 ,10 -3 ,10 -7 ,10 -15/P , 10-7,10-10,10-16/Q , 10-7/R, 10-7/S , 10-7/T , 10-7,10-15/U , 10-3,10-8,10-14/V , 2-32,10-8/W , 2-32,10-8/Z , 10-8

Compiling program code, 13-6

CONFIG.SYS, 11-44

Console commandsdirecting output to a file, 2-119general discussion, 2-115printing, 2-117

Control structuresdecision-making, 2-25DO CASE, 2-26DO W HILE, 2-23FOR , 2-23, 2-82general discussion, 2-22IF , 2-25looping, 2-22, 2-82nesting, 2-22

Controlling Allocation of Overlay Pool—/OPc, 3-17

Controlling Allocation of Overlay Po ol—/O Uc , 3-17

Controlling Am ount of EMS M emory—/CEnnn,nn, 3-16

Controlling Am ount of XMS M emory—/CXnnn,nn, 3-16

Controlling O perating Size of BlinkerOverlay Pool—/OOnnn, 3-16

Conventional m emory available, 11-44

Conversion functionsBIN2I(), 2-125BIN2L (), 2-125BIN2W(), 2-125

I2BIN(), 2-125L2BIN (), 2-125

COPY FILE, 4-4

COPY STRUCT URE, 4-4

COPY STRUCTURE EXTENDED , 4-4

COPY T O, 4-4

COUNT, 4-8

CREATEfull-screen, 16-18

CREATE FROM , 4-4

Creatingan .EXE, 11-20,12-14files, in DBU, 16-18

CTOD(), 2-44

Cursor, controlling use of, 3-10

lndex-8 CA-Clipper



D separators, 2-43validation, 2-44

Data structures, 2-40Data type

array, 2-40, 2-75character, 2-40, 2-50code block, 2-40, 2-89date, 2-43,2-51general discussion, 2-40logical, 2-46, 2-53mem o, 2-42, 2-50NIL, 2-52num eric, 2-45, 2-51object, 2-96

Database commandssyntax for specifying scope, 2-107table, 2-106

Database filesattributes of, 2-106closing, 2-112creating in DBU, 16-18definition, 2-105general discussion, 2-100

maximum number of open in DBU,16-10modifying records, 6-13opening, 2-101opening in DBU , 16-16operations, 2-106processing with DBEVAL(), 2-109saving structure in DBU, 16-24table of attributes, 2-106

Database functions,table, 2-106

Database utility, 2-100, See DBUDates

blank, 2-44comparison, 2-44constants, 2-43, 2-44literal, 2-43, 2-44operators, 2-51, 2-57precedence of operators, 2-62range of, 2-44

DBAPP END (), 4-10

dBASE III PLUSdatabase driver, 2-109

dBASE III PLUS compatibilitycompiling dBA SE source code, 10-12CREATE LABEL, 17-1CREATE REPORT, 17-1database file format, 2-105indexing, 2-109LABEL FOR M, 17-16

DBEVALQ , 2-90, 2-109DBFNTX.LIB, 10-7,11-25,11-28

DBRLOCKQ, 4-9

DBRUNLO CK, 4-11

DBSTRUCT(), 2-75, 2-77

DBUappending to a file in, 16-30Browse menu, 16-2,16-8,16 -11,16-25 ,16-33, 16-36,16-40

Browse window , 16-25,16-33browsing

a database file, 16-25a view, 16-26

color settings, 16-2copying a file in, 16-28Create menu, 16-8,16-18, 16-24creating

database files in, 16-18files, 16-18index files in, 16-23

data types, 16-20decimal restrictions, 16-21dialog

boxes, 16-5controls, 16-5

editing a memo field in, 16-27error messages, 16-5executing DOS commands from, 16-32

Prog ram m ing a n d Utilit ies G uid e lndex-9



fieldnaming conventions, 16-20width restrictions, 16-21

Help

menu, 16-5,16-8,16-15window, 16-15leaving, 16-13main screen

navigation keys, 16-12usages, 16-9

make file, 16-41marking deleted records in, 16-25menu

bar, 16-3,16-13bar, navigation keys, 16-13navigation, 16-3

Move menu, 16-25,16-33Open menu, 16-10,16-13,16-16opening

database files in, 16-10,16-16files, 16-16index files in, 16-10,16-17view files in, 16-17

performing logical searches in, 16-34prom pts, 16-5removing deleted records in, 16-31replacing fields in, 16-30Save menu, 1 6-13,16-22,16-24,16-35saving

a database file structure, 16-22,16-24a view file, 16-13,16-24

searching indexes in, 16-33Set menu, 16-11,16-35Set Relation window , 16-36setting

afield list in, 16-11 ,16-40relations in, 16-36

skipping records in, 16-35Structure window, 16-8,16-18Utility menu, 16-13, 16-28windows, 16-8

DBU.EXE, 2-100,16-1, See also DBU, 16-41comm and line syntax, 16-2source code, 16-41

DBU.HLP, 16-2

DBUNLOCK, 4-11

Debugger

definition, 13-1invoking, 2-12 2,13-7menus

accelerator keys, 13-20accessing, 13-19File menu , 13-18Help menu, 13-18,13-41Locate menu , 13-18menu commands, 13-21Monitor menu, 13-18,13-37,13-51Options menu, 13-18,13-44

Point menu, 13-18,13-34Run menu, 13-18selecting an option, 13-19shortcut keys, 13-20the menu bar, 13-17,13-19 ,13-93View menu, 13-18,13-42,13-43Window menu, 13-18

quitting, 13-16,13-71

Debugging, 10-4,10-6,14-4error, 11-33

Declarationscompile time, 2-6, 2-27general discussion of statements, 2-33runtime, 2-27

Decrement operators, 2-58

Default libraries, ignoring in a search, 11-28

DELET E, 4-7

Delete, 13-2 2,13-54,13-59,13-66,13-69 , Seealso Point Breakpoint, Point Delete

Dependency file, 14-6,14-12searching for, 14-8

Dependency rule, 14-6,14-10syntax for, 14-12

Dependency statement, 14-12,14-15

DESQview environment, 11-47

lndex-10 CA-Clipper



Device drivers, 11-46RAM DRIVE.SYS, 11-47SMARTDRIVE.SYS, 11-47

VDISK.SYS, 11-47DEV ICE^ statement, 11-32

Dialog boxes, 13-45,13-54,13-55

Directing output to a file, 2-119, See alsoOutput to text file

DIRECTO RY(), 2-75, 2-77

Disablingblinking eyes, 12-17menu items, 8-15processing of table of conten ts, 12-34use of EMS pageframe, 3-15VM pack age, 11-22warning m essages, 12-18winking during linking, 12-18

DISPLAY, 4-4

Displayingscript on screen, 12-25status information, 12-38text on screen, 12-25variables and expressions, 13-64

DO CA SE, 2-26

DO WH ILE, 2-23

DO, compiler implications, 10-12

Documentation, online, 18-1

DOSaccess from a make file, 14-19BUFFERS setting, 3-3

command line length limitation, 11-4,14-14COMMAND.COM, 3-5compatibility withCA-Clipper / Exospace

3.x to 4.x, 11-475.0 and 6.0,11-475.0 Task Switcher, 11-48

COMSPEC setting, 3-5

CON FIG.SYS, 3-2, 3-12default directory, 2-124error number, 2-127

ERRORLEVEL, 10-5,10-9,10-13,11-7,11-10,14-5,14-6,14-7executing com mands from D BU, 16-32file

attributes, 2-124pointer, 2-125

file pointer, 2-126FILES setting, 3-3, 3-12flushing buffers, 2-126MEM command, 11-44open mode, 2-124,4-4

PATH, 11-8,15-2,15-5,16-2,18-1,18-2redirection, 10-9SHELL directive, 3-4used with a memory m anager, 11-47,11-48version requirements for networking,4-3

version specific information, 3-3

DOS extender, 12-3

DOS16M environmental variable, 11-36

DoubleDOS environment, 11-47

DPMIextended memory protocol, 11-44host, problems with, 11-40

Duplicatemodules, enabling warnings for, 12-16symbols, enabling warnings for, 12-16

Dynamic overlayscaching of, 12-2

managing of, 12-2specifying file handles at runtime, 3-10specifying start of area, 12-6

DYNF, 3-10

Prog ram ming a n d Utilit ies G uid e lndex-11

http://command.com/

http://command.com/



Ε

ELSE, See also IF

ELSEIF, See also IF

EMM , 3-10, 3-12

EM PTY(), 2-83

EMScontrolling use of pageframe, 12-15enabling use of pageframe, 12-20maximum amount of, 12-7minimum amount of, 12-7specifying memory use, 12-14

Enablingthreshold size, 12-21use of EMS pageframe, 12-20use of extended library dictionaries,12-33use of library extended dictionaries,12-26use of XMS, 12-22

Enabling menu items, 8-15

End-of-file, 2-126

ENDCASE, See also DO CASE

ENDDO, See also DO WHILE

ENDIF, S ee also IF

ENDTEXT, See also TEXT

Environmentsettings

overriding .EXE defaults, 11-17overriding defaults, 12-11

specifying, 12-11specifying default, 12-12

variableschanging the name of, 11-16DOS16M, 11-36

Environment variables, 14-22BLINKER, 3-15changing name of, 12-9,12-10changing settings, 3-15

CLIPPER, 3-3, 3-9, 3-10, 3-12, 3-13, 3-14,3-15,11-16,11-17,11-19CLIPPERCMD, 10-3,10-4defining in make files, 14-15INCLUDE, 10-5,10-14,14-21LIB, 3-4,11-10OBJ, 11-11PATH, 11-8,16-2RMAKE, 14-3,14-4,14-8,14-23TMP, 3-5,10-7,10-15,11-9

Error blockBREAK , 9-11, 9-16, 9-19ERRO RBLO CK(), 9-16, 9-19ERRO RNE W(), 9-11, 9-16, 9-19EVAL(), 9-11,9-16, 9-19RECOV ER, 9-11, 9-16, 9-19SEQUENCE, 9-11

Error classcanDefault, 9-25canRetry, 9-25canSubstitute, 9-25

DefError(), 9-25, 9-28examp le, 9-25

Error handlingALER T(), 9-28compiler, 10-9,10-13default handling, 9-8error block vs SEQUE NCE , 9-19error objects, 9-21error processing, 9-4error scoping, 9-4example, 9-23, 9-30, 9-32, 9-37

exceptionhandling concepts, 9-2mechanisms, 9-10

general, 9-1handling errors, 9-8in a network environment, 4-3, 4-12linker, 11-7localization, 9-4low-level, 2-127

lndex-12 CA-Clipper



modular programming, 9-2NETE RR(), 9-37on a network environment, 9-37

posted error block, 9-16raising errors, 9-4RMAK E, 14-5,14-7runtime, 2-50, 9-1,10-6SEQUENCE contstruct, 9-10strategies, 9-1, 9-28substitution, 9-8VAL(), 9-23, 9-25, 9-28

Error messagesnot a DO S/16 M executable, 11-33not enough memory, 11-38

Error objectDefError(), 9-37Error.ch, 9-24ERRO RNE W0, 9-21, 9-23RECOVER, 9-32

ERRORBLOCK(), 9-28

EVAL(), 2-90

Exclusive m ode, 4-1, 4-3, 4-4commands that require, 4-4

Executable files, See also runtime ,10-12default

extension, 11-8,11-29name, 11-4,11-8,11-29

discussion of runtime environment, 3-1generating, 1 1-4,11-8requesting a segment map of, 12-29searching for, 11-8setting to read-only status, 12-35specifying stack size of, 12-37

Executingcode blocks, 13-5individual functions and procedures,13-53,13-64program code, 13 -47,13-48,13-49,13 -50,13-51, 13-105, 13-106,13-107,13-108

Execution modes, 13-47animate mode, 13-4 7,13-51 , 13-52,13-91,13-99, 13-105, 13-109

run mode, 13-48, 13-50,13 -51, 13-106,13-107,13-111single step mod e, 13-49,1 3-51, 13-89,13-110trace mode, 13-49,13-51,13-112

EXIT, See also DO W HILE, FOR

Exospace commandsEXOSPACE EXECUTABLE C LIPPER,3-8STACK, 11-23

EXOSPACE PACKAGE NOVM command,11-22

EXOSPACE.EXE, 11-43command line syntax, 11-4

EXOS PACE .LIB, 11-41

Expandedmemory manager, 3-10, 3-12,11-38memory usage,. 3-10, 3-12

Expressions

displaying, 13-64evaluation of, 2-48general discussion, 2-39inspecting, 13-51, 13-55passing as parameters, 2-16precedence used to evaluate, 2-63

EXTEND.LIB, 10-7, 11-25,11-28

Extended library dictionariesdisabling processing of, 12-33

Extended memoryavailable, 11-44in CA-Clipper/Exospace, 11-38linking an application, 11-43protocols

DPMI, 11-44VCPI, 11-44XMS, 11-44

Prog ram min g an d Utilities G uid e Inde x-13



running an application, 11-43sharing, 11-35solving lack of, 11-36used in CA-C lipper/Exosp ace, 11-43using the memory m anager, 11-36

EXTERNALand macro expressions, 2-74in LABEL FORMs, 17-5,17-17in REPORT FORMs, 17-5,17-17

External overlaysname of, 12-36specifing files to be in, 12-36

F

F, 3-12

FIELD alias, 2-33

Fieldsdeclaring, 2-38

passing as parameters, 2-16

FILE comm and, 11-24

File DOS, 13-62,13-71

File Exit, 13-16,13-71File handle

accessing a, 2-125obtaining a, 2-124specifying number at runtime, 3-12

File menu, 13-18DOS Access option, 13-71Exit option, 13-71Open option, 13-72Resume option, 13-73

File Open, 13-5,13-61,13-72, See also View,See also View, 13-73

File Resume, 13-60,13-72,13-73,13-112

FilLock(), 4-9

FLO CK(), 4-9

FOR, 2-23

FOR condition, 2-107

Format files, compiling, 10-12

FOU ND (), 2-111

FROM option, 12-30

Full-screen commandsdirecting output to a file, 2-119printing, 2-117

Full-screen operations, general discussion,2-116

FUNCTIONcompiler implications, 10-8

Function keys, 13-22Ctrl+F5 Run Next, 13-48Fl Help, 13-16,13-41F10 Trace, 13-49,13-51F4 Application Screen, 13-52F5 Execute Application, 13-48,13-50,13-51F7 Run to Cursor, 13-48F8 Step, 13-49,13-51F9 Set/Delete Breakpoint, 13-22,13-51,13-58,13-59programming, 2-123

Functions, See also Library functions,User-defined functions

calling conventions, 2-5, 2-17, 2-18defining, 2-7executing, 13-53,13-64

lndex-14 CA-Clipper



G

General Protection Fault interrupt, 11-33Generating

a map file, 11-26an executable file, 11-29

Get Classdata dictionary, 7-5

Get classassign(), 7-6block, 6-13, 7-2, 7-3, 7-4buffer, 7-6cargo, 7-5, 7-27clear, 7-6, 7-32col, 7-2colorDisp(), 7-6colorSpec, 7-6decPos, 7-6display(), 7-6exported instance variables, 7-2extending Read layer, 7-9insert(), 7-6messages, 7-22

name, 7-2original, 7-6overStrikeO, 7-6pos, 7-6row, 7-2setFocus(), 7-6setting and retrieving values, 7-4undo(), 7-6unTransform method, 7-32varGet(), 7-4varPut method, 7-32

varPut(), 7-4Get function layer, 7-31

creating new, 7-32

Get systemcode blocks, 7-14SET KEY, 7-14using code blocks for W HE N/V AL ID,7-14

Get system commands@ GET, [email protected], 7-9, 7-14, 7-18, 7-27

CLEAR GETS, 7-18REA D, 7-7

Get system functionsGETA CTIVE (), 7-8, 7-10GETAPPLYKEY(), 7-7, 7-25, 7-27, 7-31,7-32GETDOSETKEY(), 7-7GetNew (), 7-2GETPOSTVALIDATE(), 7-7GETPREVALIDATEQ, 7-7, 7-25GETREADER(), 7-8, 7-25, 7-27, 7-32

READVAR(), 7-10Graphic mode

bitmap s/icons, 5-9BML2RE SGOM , 5-12BMLDIR.COM, 5-12CLIPPER.BML, 5-13,1-1common problems, 5-14compiling and linking, 5-10hardware compatibility, 5-17input/ou tput system, 2-113, 5-2invoking, 5-5memory allocation, 5-18overview, 5-2pixel coordinates, 5-2programming techniques, 5-4, 5-8, 5-9push buttons, 5-9RES2BML.COM, 5-11row /colum n coordinates, 5-9shadowing restrictions, 5-7software compatibility, 5-16troubleshooting, 5-14UNIVESA.EXE, 5-17using, 5-6utilities, 5-11VESA drivers, 5-17VGA drivers, 5-17x/y coordinates, 5-9

Guide To CA-Clipper, 18-1

Prog ram ming a n d Utilities G uid e lndex-15

http://bmldir.com/

http://res2bml.com/

http://res2bml.com/

http://bmldir.com/



Η

HARDCR(),in REPORT FORMs, 17-4

Hardwarecompatibility, 11-42problems, 11-34requirements, 11-42

Header files, 13-5,13-61 ,13-72changing the standard, 10-8editing, 15-1general discussion, 2-8RMAKE, 14-21searching for, 10-5,10-8,10-14specifying a directory for, 10-14

Help, 2-123,13-16,13-41,13-74in DBU, 16-15online, 1-1,18-1

Help menu , 13-18Comm ands option, 13-74Keys option, 13-74Menus option, 13-74Windows option, 13-74

Help window, See W indows

High Memory Area, 11-38High m emory area, putting DOS code in,11-47

High speed linking, 12-2

I

IF , 2-25

IF()in LABEL FORMs, 17-16in REPORT FORMs, 17-4

INCLUDE directory, 10-5,10-14

Increment operators, 2-58

INDEX , 2-110, 4-4

Index filesclosing, 2-112controlling index, 2-111, 2-112creating, 2-110

in DBU, 16-23general discussion, 2-109maximum number of open, 2-110maximum number of open in DBU, 16-10opening, 2-110opening in DBU , 16-17order of, 2-111relative searching, 2-111searching, 2-111updating, 2-112

Index key

maximum length, 2-110unique values, 2-110

Inference rule, 14-10syntax for, 14-15

INFO, 3-12

Init.cld, 13-7,13-14

Input/output systemgraphic m ode, 2-113, 5-2overview, 2-113

text mode, 2-113Insert mode, 13-33

Inspectingcode blocks, 13-5macros, 13-5variables and expressions, 1 3-51,13-55

Installationdefault

directory structure, 11-11default directory structure, 10-13,10-14,

11-7,11-10,15-2,15-5,16-2,18-1,18-2Instance variables, 2-98

accessing, 2-99assignable, 2-99exported, 2-98syntax for assigning, 2-99syntax for retrieving, 2-99

lndex-16 CA-Clipper



Instancescreating, 2-97definition, 2-97

ISCOLORO, 16-2

JIOIN, 4-4

Κ

KEYBOARD, 2-121, 2-123controlling the, 2-120, 2-122number of programmable keysavailable, 2-123polling the, 2-121programming, 2-123

Keyboard bufferand function keys, 2-121changing the size of, 2-120clearing the, 2-120, 2-121, 2-123

disabling the, 2-120extracting a key from, 2-121general discussion, 2-120maximum number of characters in,2-120minimum size of, 2-120reading pending key, 2-121returning last key extracted, 2-121stuffing the , 2-121

KEYBOARD command, 7-10

Keyboard functionsINKEY0,2-120, 2-121LASTKEY(), 2-121ΝΕΧΤΚΕΥ0,2-121

L

LABEL FORM, 4-4creating, 17-1printing, 17-19

LAN, 4-1requirements for using CA-Clipperwith, 4-3workstation requirements, 4-3

LEN(), 2-42, 2-84

LIB directory, 3-4,11 -10

Librariescompared w ith packages, 11-21disabling processing of table ofcontents, 12-34Disabling use of extended librarydictionaries, 12-33Enabling use of Library extendeddictionaries, 12-26ignoring default library search records,12-33locating and linking, 12-25prioritizing symbols in, 12-35

third-party compatibility, 11-41

Library filesembedded name in object file, 10-7search paths, 11-10searching for, 11-10

Library modulesoverriding linking sequence, 11-27specifying placement of, 12-30

Linker

resolving external references, 10-7

LinkingCA-Clipper 5.01 or 5.01a, with, 11-15object

files, 11-24modules and libraries with scriptfiles, 11-5

required library files, 11-25sequence, overriding, 11-27

Programming and Utilities G ui de lndex -17



LIST, 4-4, 4-8

List, 13-34,13-55,13-59,13-69,13-76,13-101,13-102

Load size, 11-2Loading

.EXE into memory, 11-2CA-Clipper/Exospace, 11-2

Local Area Network, See LAN

Locate Case, 13-77,13-78, 13-80,13-81

Locate Find, 13-77,13-78,13-80,13-81

Locate Goto, 13-79,13 -88,13-92

Locate menu , 13-18Case sensitive option, 1 3-77,1 3-78,13-80,13-81Find option, 13-78,13-8 0,13-81Goto Line option, 13-79Next option, 13-80Previous option, 13-81

Locate Next, 13-77,13-80

Locate Previous, 13-77,13-81

Lockingautomatic, 4-10commands that require, 4-7file locking, 4 -1, 4-7, 4-9, 4-12programming strategies, 4-12record locking, 4-1, 4-7, 4-9, 4-10, 4-12releasing locks, 4-11

Locks.prgAddR ec(), 4-10NetUse(), 4-6

Logical

comparison, 2-47, 2-53constants, 2-46delimiters, 2-46literals, 2-46operators, 2-53precedence of operators, 2-62, 2-64table of operators, 2-53truth tables, 2-53

LOOP, See also DO W HILE, FOR

Looping structuresconditional, 2-23counter, 2-23, 2-82

Low-level file functionserror table, 2-127FCLO SE(), 2-126FCREATE(), 2-124FERROR(), 2-127FOPE N(), 2-124FREAD(), 2-125FREADSTR(), 2-125FSEEK(), 2-126FW RITE(), 2-125general discussion, 2-124

Μ

Macro expressionsand external references, 2-74compared to code blocks, 2-89creating, 2-60general discussion, 2-66

Macro operatorand arrays, 2-71and code blocks, 2-72compared to extended expressions, 2-69general discussion, 2-66limitations, 2-69, 2-71, 2-72, 2-73nesting, 2-74used for compiling on the fly, 2-68used for text substitution, 2-67

Macro variable

definition, 2-66terminating, 2-66

Macros, 13-5

Main procedure, See also Startup procedure

Make, S ee also RMAKE

lndex-18 CA-Clipper



Make file, 14-2,14-6,14-10comments in, 14-12default extension, 14-8

defining environment variables in, 14-12DOS access from, 14-19example, 14-27line continuation in, 14-11searching for, 14-8using quotation marks in, 14-8,14 -11,14-12,14-20,14-23

Makepath,RMAKE macro, 14-8,14-12,14-21

Manifest constants, 13-6defining, 2-8,10-5

MAP command, 11-33MAP file

finding module and routine errors,11-33generating, 11-26

Map filesdefault extension, 11-9generating, 11-9

Mathematical operators, 2-51

MEM DOS command, 11-44Memo fields

and character strings, 2-42comparison, 2-42, 2-43maximum length of, 2-43operators, 2-50relationship to memo file, 2-105

Memo files, See also .dbt filesgeneral information, 2-105

MEM OREAD(), 4-4

Memoryrequirements, 11-43shortage, 11-32,11-38

Memory managerproviding extended memory, 11-36searched in the CA-Clipper/Exospace

environment, 11-45used with DOS, 11-47,11-48

MEMOTRAN()

in REPORT FORMs, 17-4

MEMVAR, 10-4

MEM VAR alias, 2-33Menultem class

caption, 8-7, 8-9, 8-13, 8-16check ed, 8-13, 8-14, 8-17

data, 8-3, 8-4, 8-8, 8-9definingmenu commands, 8-2prope rties, 8-2, 8-9, 8-10separators, 8-13toggles, 8-13, 8-14, 8-17

disabling items, 8-15enabled, 8-4, 8-15enabling items, 8-15id , 8-9, 8-18isPopUpQ, 8-4Menultem() function, 8-3, 8-5, 8-7, 8-8,8-9, 8-18message, 8-9, 8-17overview, 8-1shortcut, 8-8, 8-9, 8-16style, 8-16, 8-17

Menu ltem(), 8-3, 8-5, 8-7, 8-8, 8-9, 8-18

MENUMODAL(), 8-17, 8-18

Menusaccelerator keys, 8-2, 8-7, 8-12

actions for, 8-8activating, 8-17, 8-18cascading, 8-2, 8-15, 8-17colors for, 8-12creating menu objects, 8-1disabling items, 8-15displaying, 8-17, 8-18enabling items, 8-15making selections, 8-2




Menultem class, 8-1parts of a, 8-2PopUpM enu class, 8-1separators, 8-13

shortcut keys, 8-2, 8-8, 8-9, 8-16submenus, 8-2, 8-15, 8-17toggles, 8-13, 8-14, 8-17TopBarMenu class, 8-1visually effective, 8-12, 8-13, 8-15, 8-16

Messagesarguments, 2-98sending, 2-97, 2-98syntax for sending, 2-98use of parentheses, 2-98

Methods,definition, 2-98

Modes, See also Execution modesInsert, 13-33Overwrite, 13-33

MODIFY STRUCTUREfull-screen, 16-18

Moduleerrors,finding with MAP file, 11-33names,referring to, 12-30

MODU LE...FROM command, 11-14

Monitor Local, 13-82,13-83

Monitor menu, 13-18,13-51Local option, 13-82,13-83Private option, 13-84Public option, 13-85Sort option, 13-37,13-86Static option, 13-87

Monitor Private, 13-84

Monitor Public, 13-85

Monitor Sort, 13-37,13-86

Monitor Static, 13-87

Monitor window, See W indows

Multistatement com mand lines, 13-4

Ν

Nested REA Ds, 7-9

NETERR(), 4-3

NetUse(), 4 -3,4-6

Network [email protected], 4-7APPEND BLANK, 4-10APPEND FRO M, 4-4COPY STRUC TURE, 4-4COPY STRUCTURE EXTENDED, 4-4COPY TO, 4-4COUN T, 4-8CREAT E, 4-4CREATE FROM, 4-4DBAPPEND(), 4-10DELETE , 4-7DISPLAY, 4-4FOPE N(), 4-4INDEX , 4-4JOIN, 4-4LABEL FO RM, 4-4LIST, 4-4,4-8MEM OREAD (), 4-4

PACK, 4-4RECALL , 4-7REINDEX, 4-4REPLACE, 4-7REPORT FORM, 4-4,4-8RESTORE, 4-4SAVE , 4-4SET ALTERNA TE, 4-4SET INDEX , 4-3SET PRINTER , 4-4SORT , 4-4

TEXT, 4-4TO F ILE, 4-4TOTAL , 4-4TYPE, 4-4UPDATE, 4-4,4-7USE, 4-3, 4-4ZAP, 4-4

Network programming, 4-3

lndex-20 CA-Clipper



Networking, 4-1assigning rights, 3-18hardware requiremen ts, 3-17

runtime considerations, 3-17NEXT, See also FOR

NG directory, 18-1,18-2

NG.EXE, See also Norton Gu ides, 18-1command line syntax, 18-2

NG .INI, 18-17

NILas a return value, 2-5, 2-7, 2-20as an initializer, 2-6, 2-47, 2-77

assignment, 2-47assignment to omitted p arameters, 2-14,2-19comparison, 2-47, 2-52, 2-83operations, 2-52

NOIDLE, 3-13

Norton Guides, See also Guide ToCA-Clipper

Access window, 18-5,18-6accessing, 18-3

configuration, 18-15Expand menu, 18-5,18-6getting help, 18-7hot key, 18-3,18-17,18-18Instant Access Engine, 18-1leaving, 18-18loading, 18-2memory used by, 18-2mem ory-resident mod e, 18-2menu bar, 18-5menu bar navigation key s, 18-6menu navigation, 18-6navigation, 18-14NG .INI, 18-17operation, 18-4Options menu, 18-5,18-6pass through mode, 18-2,18-3Search menu, 18-5,18-9syntax, 18-2unins tailing, 18-18

Norton guidesnavigation, 18-10

Not a DO S/16M executable error message,11-33Not enough memory error message, 11-38

Notes on compatibility, 11-35

Nulldate, 2-44string, 2-41terminator, 2-40

Num , 13-88, See also Options Line

Numericcomparison, 2-46constants, 2-45limitations, 2-45literals, 2-45operators, 2-51, 2-57overflow in REPORT FORMs, 17-5precedence of operators, 2-62, 2-64precision, 2-45range of values, 2-45storage format, 2-45table of operators, 2-51

Ο

OBJ directory, 11-11

Object filesdefault name, 10-2,10-7,10-9,10-15embedding library name in, 10-7generating, 10-2,10-12

reducing size of, 10-6search paths, 11-11searching for, 11-11specifying a directory for, 10-7specifying a name for, 10-7,10-15specifying name of, 12-27

Prog ram ming a n d Utilit ies G uide lndex-21



Objectsas return values, 2-20, 2-97creating new objects, 2-97general discussion, 2-96passing as param eters, 2-16, 2-18, 2-97sending messages, 2-97, 2-98

Opening filesdatabase, 2-101in a network environment, 4-4, 4-12in DBU, 16-16in shared m ode, 4-3index, 2-110

Operating systems, 11-47

Operations

array, 2-75code block, 2-89database file, 2-106index, 2-109

Operatorsaddition, 2-51alias, 2-33, 2-60array element, 2-60array equivalence, 2-84assign, 2-55, 2-77binary, 2-49character, 2-50, 2-57code block, 2-60code block arguments, 2-89compile and run, 2-60, 2-66, 2-68, 2-80,2-95compound assign, 2-57concatenation, 2-50constant array, 2-60, 2-80date, 2-51, 2-57, 2-58decrement, 2-58division, 2-51

equal, 2-52exactly equal, 2-52exponentiation, 2-51general discussion, 2-40, 2-48greater than, 2-52greater than or equal, 2-52grouping, 2-60increment, 2-58

infix, 2-49inline addition and assign, 2-57inline assign, 2-56, 2-57, 2-77, 2-99inline concatenation and assign, 2-57inline division and assign, 2-57inline exponentiation and assign, 2-57inline modulus and assign, 2-57inline multiplication and assign, 2-57inline subtraction and assign, 2-57less than, 2-52less than or equal, 2-52logical, 2-53macro, 2-66mathem atical, 2-58mem o, 2-50modulus, 2-51multiple inline assign, 2-56mu ltiplication, 2-51not equa l, 2-52num eric, 2-51, 2-57overloading, 2-48, 2-55pass by reference, 2-17pass-by-reference, 2-60postdecrement, 2-58postfix, 2-49, 2-58postincrement, 2-58precedence of, 2-49, 2-51, 2-61, 2-62

predecrement, 2-58prefix, 2-49, 2-58preincrement, 2-58relational, 2-52, 2-84send, 2-97, 2-98, 2-99special, 2-60substring, 2-52subtraction, 2-51table of decrement, 2-58table of increment, 2-58table of special, 2-60

unary, 2-49Options Codeblock, 13-89

Options Co lor, 13-90

Options C olors, 13-44

Options Exchange, 13-47,13-52,13-89,13-91,13-99

lndex-22 CA-Cl ipper



Options Line, 13-92, S ee also Num

Options Menu, 13-93

Options menu, 13-18Codeblock Trace option, 13-89Color option, 13-90Colors option, 13-44Exchange Screens option, 13-91,13-105Line Numbers option, 13-92Menu Bar option, 13-93Mono Display option, 13-94Path for Files option, 13-95Preprocessed Code option, 13-96Restore Settings option, 13-97Save Settings option, 13-98Swap on Input option, 13-99Tab W idth option, 13-100

Options Mono, 13-94

Options Path, 13-95

Options Preprocessed, 13-6,13-96

Options Restore, 13-14,13 -97

Options Save, 13-14,13-98

Options Swap, 13-99

Options Tab, 13-100Organization,manual, 1-1

O S/ 2 Virtual DOS Machines, compatibilitywith CA-Clipper/Exospace, 11-49

OTHERWISE, S ee also DO CASE

Output execu table filespecifying name of, 12-34

Output to text [email protected], 2-119

console comm ands, 2-119Overlay

area,specifying end of, 12-26manager,forcing display of errors, 12-32pool

adjusting opsize of, 12-19default size of, 12-19request size for, 12-19

Overlay pool,size of, 3-15

Overlaying code,automatically, 11-2

Overriding default linking sequence, 11-27Overview of Blinker, 12-2

Overview of CA-Clipper/Exospace, 11-2

Overwrite mod e, 13-33

Ρ

PACK, 4-4Packages

compared with libraries, 11-21including in .EXE, 11-21protected-mode support, 11-21third-party libraries, 11-22

Pageframefor overlays, 12-20use of, 12-20

Paging system, support for, 12-2

Parameterdeclared, 2-14definition of actual, 2-14definition of formal, 2-14methods of specifying, 2-14number p assed, 2-14, 2-19omitting, 2-14, 2-19optional, 2-14, 2-19passing, 2-14, 2-19passing arrays as, 2-16, 2-18, 2-81passing by reference, 2-17, 2-18passing by value, 2-16, 2-18passing code blocks as, 2-16passing fields as, 2-16passing from DO S comm and line, 2-20passing objects as, 2-16, 2-18, 2-97passing with DO ...WITH, 2-17

PARAM ETERS, 10-4

Parentheses, and precedence, 2-49, 2-65

Program ming an d Utilities Gu ide lndex-23



Pass-by-reference, 2-17, 2-60

PCOL(), 2-117

PCOUNT()

effect of omitting parameters on, 2-19PCO UN T(),effect of omitting parameters on,2-14

PE.EXE, 15-1, See also Program editor

PMINFO command, 11-31,11-32

PMINFO, defined, 11-34

Point Breakpoint, 13-5 1,13-58, 13 -59,13-10 1,See also BP

Point Delete, 13-34 ,13-54,13 -102, See alsoDelete

Point menu, 13-18Breakpoint option, 13-101Delete option, 13-54,13-102Tracepoint option, 13-54,13-103Watchpoint option, 13-54,13-104

Point Tracepoint, 13-14,13-34,13-54,13-103

Point Watchpoint, 13-14,13-34,13-54,13-104

PopUpO, 8-3, 8-6PopUpMenu class

addltem (), 8-4colorSpec, 8-4, 8-10, 8-12creating pull-down menu , 8-2defining properties, 8-10overview, 8-1PopUpO function, 8-3, 8-6

Postdecrementoperators, 2-58precedence of op erators, 2-62, 2-65

Postincrementoperators, 2-58precedence of op erators, 2-62, 2-65

Precedence, 2-49, 2-61and algebraic expression evaluation, 2-63

Predecrementoperators, 2-58precedence of operators, 2-62, 2-63

Preincrementoperators, 2-58precedence of o perators, 2-62, 2-63

Preprocessed output,viewing, 13-6,13-96

Preprocessor, 10-10defining an identifier, 10-5source listing file, 10-7,10-1 6switches, 10-4

Preprocessor directives, 10-8#define, 2-8#include, 2-8,10-14summary of, 10-10

[email protected], 2-117general discussion, 2-117redirecting output to a file, 2-119with console commands, 2-117

PRIVATE, 10-4

Problemsrunning CA-Clipper/Exospaceapplications, 11-31when running under DPMI, 11-40

Procedure stack, setting maximum depth,11-23

PROCEDURE, compiler implications, 10-8

Procedurescalling conventions, 2-5, 2-17

declaring, 2-7defining, 2-7executing, 2-5,13-53,13-64files, compiling, 10-12nesting,specifying maximum depth of,12-23passing parameters to , 2-14startup, 2-4

lndex-24 CA-Clipper



PROC LINE(), 2-123

PROCNAME(), 2-123

Programcomm ents, 2-8multistatement line, 2-9termination, 2-122

Program editor, 15-1architecture, 15-5make file, 15-5navigation, 15-3operation, 15-3source code, 15-5syntax, 15-2

Program filescompiling, 10-2,10-12linking, 11-4

Program librariesspecifying names of, 12-28specifying names to, 12-28

Programminggeneral discussion, 2-2techniques,text vs. graphic mode, 5-2

Protected modeprogramming restrictions

problems in third-party libraries,11-41

running in, 11-2support packages, 11-21switching to real mode, 11-42virtual memory engine, 11-2

Providing extended memory, 11-36

PROW(), 2-117

Pseudof unctions, 13-6

PUBLIC, 10-4

R

RAM, 11-2,11-22RAM DRIVE.SYS device driver, 11-47

Read layer, 7-17, 7-25, 7-27©...GET, 7-8creating, 7-19, 7-27implementation rules, 7-18, 7-27implementation steps, 7-19READM ODAL, 7-8SET MESSAGE TO, 7-22STD.CH, 7-8

READ, exiting from a, 2-122

REA DEX IT(), 2-122

Reading DEFAULTS.LNK, 12-4

Reading OTHER.LNK, 12-4

READVAR(), 2-123

Real modememory availability, 12-2memory optimizing usage, 12-2

memory overcoming limit, 12-2switching to protected mode, 11-42

RecLock(), 4-10

RECNOQ, 16-36

Recordprocessing w ith D BEV AL(), 2-109scoping, 2-107, 2-109

Record pointer,and index updating, 2-112

Recursion, 2-34

REIND EX, 2-112, 4-4

Relationaloperators, 2-52, 2-84precedence of operators, 2-62, 2-64table of operators, 2-52

REPL AC E, 2-55, 4-7and inline assignment, 2-57




Report and label utility, See RL

REPORT FORM , 4-4, 4-8creating, 17-1for related files, 17-12

printing, 17-11Required library files for linking, 11-25

Requirementsavailable mem ory, 11-6hardware, 11-42memory, 11-43

RES2BML.COM, 5-11

Reserved w ords, 2-10, 2-47

RESTOR E, 4-4

Return values, from a user-defined function,2-20

RETU RN , from a user-defined fun ction, 2-20

RLabandoning changes, 17-11,17-18creating a new label, 17-13creating a new report, 17-2inserting line breaks in reports, 17-4Label Exit menu, 17-18

Label Formats menu, 17-16Label Toggle menu, 17-14,17-16leaving, 17-19make file, 14-27,17-20maximum number of report columns,17-3mod ifying an existing label, 17-13mod ifying an existing report, 17-2Report Columns menu, 17-3Report Delete menu , 17-6Report Exit menu, 17-11

Report Goto men u, 17-6Report Groups menu, 17-9Report Insert menu, 17-6Report menu, 17-7saving a label definition, 17-18saving a report definition, 17-11specifying a standard label format,17-16

specifying blank label lines, 17-16specifying fields from multiple files,17-12specifying label contents, 17-16specifying report level options, 17-7

RL.EXE, 17-1, See also RL, 17-20comm and line syntax, 17-2source code, 17-20

RLOCK(),4-9

RM AK E, See also Make file, 14-1commands, 14-10comments in, 14-5,14-12,14-19conditional make, 14-19 ,14-20,14-21configuration, 14-3

DBU make file, 16-41debugging, 14-4dependency rule, 14-6 ,14-10,14-1 2dependency statement, 14-6directives, 14-19display warning m essages, 14-5DOS access from, 14-19DOS return code, 14-5,14- 6,14-7DOS SE Ts, 14-17error handling, 14-5,14-7examples, 14-12,14-15,14-17,14-23,

14-25,14-27header files, 14-21inference rule, 14-10,14-15input files, 14-8internal workspace, 14-5macro definition, 14-23macro expansion, 14-23macros, 14-2,14-3,14-4,14-8,14-10,14-11,14-22make phase, 14-6,14-8,14-15parsing phase, 14-6,14-8,14-19PE m ake file, 15-5predefined macros, 14-15,14-25RL make file, 14-27,17-20special macros, 14-8,14-12,14-21,14-25switches, 14-2,14-4symbol table, 14-5user-defined macros, 14-23

RMAKE directives

lndex-26 CA-Clipper

http://res2bml.com/

http://res2bml.com/



# , 14-19#else, 14-19,14-20,14-21#endif, 14-19,14-20,14-21#ifdef, 14-19#ifeq, 14-20#iffile, 14-20#ifndef, 14-21#include, 14-21#stderr, 14-21#stdout, 14-21#undef, 14-22

RMAKE options, See RMAKE switches

RMAKE switches/B , 14-4/D , 14-3,14-4,14-8,14-23/F , 14-4,14-7,14-12/1,14-5,14-15/N , 14-5/U , 14-5,14-12,14-19/W , 14-5/XS , 14-5/XW, 14-5

RMAKE.EXE, See also RMAKEcommand line syntax, 14-2

Routine errors, finding with MAP file, 11-33Run Animate, 13-47,13-51,13-52,13-105

Run Go, 13-48,13-50,13-51,13-106

Run menu, 13-18Animate option, 13-105Go option, 13-106Next option, 13-107Restart option, 13-108Speed op tion, 13-109Step option, 13-110To Cursor option, 13-111Trace option, 13-112

Run Next, 13-48,13-107

Run Restart, 13-108

Run Speed, 13-47, 13-51, 13-105, 13-109

Run Step, 13-110,13-112Run To, 13-48,13-111

Run Trace, 13-112

RUN, runtime implications, 3-5

Runningan application usingCA-Clipper/Exospace, 11-41in protected mode, 11-2

Runtime

configuration, 3-7, 3-8, 11-16,11-17,11-19configuring number of files at, 3-12controlling extended cursor, 3-10displaying memory configuration at,3-12environment settings, 3-7, 3-8, 11-16,11-17, 11-19excluding available memory at, 3-15general discussion of environment, 3-1list of param eters, 12-12

preventing idle time detection at, 3-13restoring EMM page frame, 3-10specifying dynamic overlay file handles,3-10specifying swap file location at, 3-14specifying swap file size at, 3-14specifying temporary file location at,3-14

Prog ramm ing a n d Utilities Gu ide lndex-27



s

SAVE , 4-4

Scope, syntax for specifying, 2-107Script files, 13-7,13-13,13-14,13-21,13-44,13-97,13-98

comments, 11-4compiling with, 10-2,10-9,10-12default extension, 11-4defaulting to a .LNK extension, 12-4DEFAULTS.LNK, 12-4indicating text as comment, 1 2-4,12 -5linking with, 11-4nesting, 11-4OTHER.LNK, 12-4searching for, 11-11specifying name of, 12-5specifying on the comm and line, 12-4

Search path, 13-13

SEEK, 2-111

SELECT, 2-101

Selectordefinition, 2-98instance variable, 2-99message, 2-98

Separators, 8-13

SET ALTERNATE, 2-115, 2-119, 4-4

SET CENTURY, 2-44

Set Colors window, See Windows

SET CONSOLE, 2-115, 2-117

SET DATE, 2-43

SET DE VICE, 2-116, 2-117

SET EPOCH, 2-43

SET ESCAPE, 2-122

SET EXACT, 2-42

SET EXC LUSIVE, 4-3, 4-4

SET FOR MA T, compiler implications, 10-12

lndex-28 CA-Clipper

SET FUNCTION , 2-123

SET IND EX, 2-110, 2-111, 4-3

SET KEY , 2-122, 2-123, 7-10SET MAR GIN, 2-117

SET ORDER, 2-111

SET PRINTER, 2-115, 2-117, 2-119, 4-4

SET RELATION, 16-36

and REPORT FORMs, 17-12

SET SOFTSEEK, 2-111

SET TYPEAHEA D, 2-120SETCANCEL(), 2-122

SETCOLOR0, 2-117, 8-12

SETPRC(), 2-117Setting

maximum depth of CA-Clipperprocedure stack, 11-23parameters for Virtual DO S M achine,11-49read-only status, 12-35

Shared mod e, 4-1, 4-3 ,4-4 , 4-7, 4-9

Sharing extended mem ory, 11-35

Shortcut keys, 8-2, 8-8, 8-9, 8-16

SMA RTDR IVE.SYS device driver, 11-47

Softwarecompatibility, 11-35,11-42incompatibility, 11-32

Solutions to CA-Clipper/Exospace

application problems, 11-31SORT , 4-4

Sorting arrays, 2-87

SOURC E d irectory, 15-5



Source filescompiling, 10-12editing, 15-1line numbers, 10-6,10-7

Specifying.LIB, 11-2.OBJ, 11-2CA-Clipper, 5.01 or 5.01a, 11-15case sensitivity, 12-29conversion of symbols to uppercase,12-38default

.EXE options, 11-18drive of temporary workfile, 12-39end of overlay area, 12-26executable file to be generated, 11-29file name of temporary workfile, 12-39files to be in external overlays, 12-36name of object files, 12-27name of output executable file, 12-34object files to be linked, 11-24path of temporary workfile, 12-39required library files for linking, 11-25setting to read-only status, 12-35stack size of application, 11-30

stack size of executable files, 12-37suppressing of beep, 12-32symbols to be excluded, 12-24XMS mem ory use, 12-15

Specifying the Location of Executable Files,3-4

Stack sizeof application, 11-30of executable files, 12-37

Standard header file,changing, 10-8

Startup procedure, 10-6

Status informationdisplaying, 12-38during linking, 12-38

STD.CH, 10-8

Storage classes,defined, 2-27

STORE, 2-55, 2-56

Submen us, 8-2, 8-15, 8-17

Substring operator, 2-52

SUM, 4-8

SWAPK, 3-14

SWAPPA TH, 3-14

Symbol table, compression of, 12-2

Symbolsconverting to uppercase, 12-38prioritizing of, 12-35specifying sym bols to be excluded,12-24

Systemhanging, 11-34viruses, 11-33

Target file, 14-6,14-12creating, 14-8searching for, 14-8

TBColumn classblock, 6-13, 6-20cargo, 6-12colorBlock, 6-20, 6-23defColor, 6-19, 6-20, 6-23

TBrowseadding Color, 6-18browsing search results, 6-30

browsing w ith Get, 6-13Controlling highlight, 6-22controlling scope, 6-24Creating TBrowse Objects, 6-3DBEVAL(), 6-30multi-user applications, 6-9obtaining quicker response time, 6-8Optimization, 6-7repositioning record pointer, 6-10

Prog ram ming an d Utilit ies G uide lndex-29



SET COLOR, 6-18SET FILTER, 6-30using TBColumn

cargo, 6-12

using TBrowsecargo, 6-12

using TRANSFORM(), 6-7viewing a key value, 6-26

TBrowse class, 6-3applyKey() method, 6-6autoLite, 6-22cargo, 6-12colorRect, 6-23colorSpec, 6-18deHilite, 6-22

forceStable() method, 6-5goBottomBlock, 6-24, 6-26, 6-30goTopBlock, 6-24, 6-26, 6-30hilite, 6-22refreshAll() method, 6-10refreshCurrent() method, 6-9setKey() method, 6-6skipBlock, 6-24, 6-26, 6-27, 6-30stabilization, 6-5stabilize() method, 6-5, 6-8up() method, 6-10

TBrow seDB(), 6-3TBrowseNEW(), 6-3

Temporary filesspecifying a directory for, 3-5,10-7,10-15,11-9

TEMPPATH, 3-14

TERM INAL.LIB, 11-25, 11-28

TEXT, 4-4

Textmodeprogramming techniques, 5-3

Text filesediting, 15-1

Text modeinput/output system, 2-113

Third-partycompatibility, 11-41library

compatibility, 11-41

packages, 11-22violations and solutions, 11-41

programming restrictions in protectedmo de, 11-41

Threshold size,enabling, 12-21

TMP directory, 3-5,10-7,10-15,11-9

TO FILE clause, 2-115, 2-119

TO PR INTER clause, 2-115, 2-117

Toggles, 8-13, 8-14, 8-17

TopBar(), 8-3, 8-5TopBarMenu class

activating objects, 8-17, 8-18addltem(), 8-4, 8-5, 8-6colorSpec, 8-4, 8-10, 8-12creating menu bar, 8-2defining properties, 8-10display(), 8-4displaying objects, 8-17, 8-18left, 8-3overview, 8-1right, 8-3row, 8-3

TopBar() function, 8-3, 8-5

TOTAL, 4-4Tracepoints, 13-34,13-47,13-51,13-53,13-106

and monitored variables, 13-82,13 -83,13-84,13-85,13-87definition, 13-53,13-103deleting, 13-54,13-69,13-102

listing, 13-55,13-76setting, 13-14,13-54,13-103

TRANSFORM(), 6-7

in REPORT FO RMs, 17-4

TSR programs, 3-10

TYPE, 4-4

TYPE(),and arrays, 2-75

lndex-30 CA-Clipper



υ

UNIVESA.EXE, 5-17UNLOCK, 4-11

UPD ATE, 4-4, 4-7

and inline assignment, 2-57

Upgrade offer, 12-3

USE, 2-101, 2-110, 2-111,4-3, 4-4

User-defined comm ands, 2-89, 2-109User-defined functions

calling conventions, 2-5declaring, 2-7executing, 2-5

passing arguments to, 2-14, 2-81

Using high memory area, 11-38

V

VALTYPE()and arrays, 2-75used to test for omitted parameters, 2-19

Variable nameschanging of, 3-15resolving references, 2-32

Variablesambiguous references to, 2-32changing values of, 13 -34,13-3 7,13-55creating new, 13-56,13-64creation, 2-29declaration, 2-6, 2-27, 2-33, 2-47definition of, 2-27displaying, 13-64dynamically scoped, 2-27field, 2-38initialization, 2-33, 2-47inspecting, 13-51,13-55

lexically scoped, 2-6, 2-27lifetime of, 2-29local, 2-34

monitored, 13-37,13-51,13-82,13-8 3,13-84,13-85,13-86,13-87naming, 2-31passing as parameters, 2-16private, 2-36public, 2-37scoping in code blocks, 2-30, 2-90scoping of, 2-6, 2-27, 2-30static, 2-35undefined, 2-47visibility of, 2-29

VCPI extended memory protocol, 11-44VDISK.SYS device driver, 11-47

Version numberrepresenting, 12-40return as integer, 12-40

View, 13-112, See also File Open, 16-13,16-17,16-24,16-35

definition, 16-3,16-9

View App, 13-52,13-114

View Callstack, 13-39,13 -60,13-11 5, See alsoCallstack

View menu, 13-18App Screen op tion, 13-114Callstack option, 13-115Sets option, 13-42,13-116Workareas option, 13-43,13-117

View Sets, 13-42,13-116

View Sets window, See Windows

View Workareas, 13-43,13-117

View Workareas window, See Windows

Viewingheader files, 13-5,13-61,13-72,13-112preprocessed output, 13-6,13-96program code, 13-61,13-72,13-73,13-105,13-112program output, 13-52,13-91,13-114

Prog ram ming a nd Utilit ies Gu ide lndex-31



VirtualDOS M achine, setting parameters for,11-49memory manager, 3-10, 3-12, 3-14

Virtual Memory M anager, 11-2

Virus, in system, 11-33

VM packagedisabling, 11-22excluding, 11-22

VM M, 3-10, 3-12, 3-14

Wait states, keyboard buffer, 2-120

Watch window, See Windows

Watchpoints, 13-34, 13-51,13-53and monitored variables, 13-82 ,13-83 ,13-84,13-85,13-87definition, 13-53,13-104deleting, 13-54, 13-69, 13-102listing, 13-55,13-76setting, 13-14,13-54,13-104

WH ILE condition, 2-107

Window Iconize, 13-118

Window menu, 13-18Iconize option, 13-118Move option, 13-119Next option, 13-119Prev option, 13-120Size option, 13-120Tile option, 13-121

Z i 13 122

Window Tile, 13-121

Window Zoom, 13-122

Windows

activating, 13-24closing, 13-25environment, 11-47iconizing, 13-26,13-118moving, 13-28,13-119navigating between, 13-24,13-119,13-120opening, 13-25sizing, 13-27,13-120the Callstack window, 13-24,13-3 7,13-39,13-60,13-68,13-115the Code window, 13-6,13 -24,13-29 ,13-37,13-61,13-68,13-82,13-83,13-84,13-85,13-87,13-88,13-91,13-92,13-94,13-96,13-100the Command window, 13-24,13-31,13-53,13-63the Help window, 1 3-16,13-41,13-74the Monitor window, 13-24, 13-37,13-45,13-82,13-83, 13-84,13-85,13-86,13-87the Set Colors window , 1 3-44,13-90the View Sets window , 13-4 2,13-116

the View Workareas window , 13-43,13-117the Watch window, 13-24, 13-34,13-45,13-51,13-54,13-55,13-69,13-76,13-103,13-104tiling, 13-28,13-121zooming, 13-26,13-122

Work areaattributes in DBU, 16-9attributes of, 2-104changing, 2-101d f l li 2 101

Documents

CA-Clipper for DOS Version 5.3 Programming and Utilities Guide