xHarbour Language Reference Guide

(1)

(2)

Copyright

If this guide is distributed with software that includes an end user agreement, this guide, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. Except as permitted by any such license, no part of this guide may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of xHarbour.com Inc. Please note that the content in this guide is protected under copyright law even if it is not distributed with software that includes an end user license agreement.

The content of this guide is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by xHarbour.com Inc. xHarbour.com Inc. assumes no responsibility or liability for any errors or inaccuracies that may appear in the informational content contained in this guide.

(3)

Read Me First!

Welcome to the First Version of the xHarbour Language Reference Guide. This page informs you about what you can expect from the First Edition and what is not yet included.

First, we'd like to thank you for patience and ongoing support while we were preparing this xHarbour Language Reference Guide. It is a huge documentation project and while not yet finished, we are confident that the large amount of quality information will prove valuable for every xHarbour programmer.

First stage (completed)

We have started this First Edition with collecting most information about xHarbour's roots: the Clipper programming language. The topics covering Clipper are entirely re-written.

Second stage (completed)

At the second stage, we focused on documenting all xHarbour's extensions to the Clipper language. There is a wealth of new features added to xHarbour that do not exist in Clipper (see "Notes for Clipper programmers" below).

For example, a complete OOP model with new classes exists. New data types and operators are added. Additional preprocessor directives are available, plus numerous new functions and statements. As a matter of fact, the core documentation of xHarbour is about twice as much as the original Clipper Norton Guides.

It is structured into the following sections: 1. Operator Reference

2. Statement Reference 3. Command Reference 4. Class Reference (textmode) 5. Function Reference

6. Preprocessor Reference

These sections should aid you in finding information on core features of xHarbour easily. In addition, a comprehensive Index and Full Text Search capabilities, plus a sophisticated Cross Reference Link

System are all included. Please try these features for searching and finding the information you need in

the xHarbour Documentation.

Third stage (ongoing)

We are now entering the third documentation stage right after the release of this book. The result of this third stage will be provided as a free update to Version 1.0 of the xHarbour Language Reference Guide. We are commited to supply you with this free update promptly. However, there is still a bunch of work ahead and we hope you enjoy reading this Version 1.0 in the meantime.

(4)

Read Me First!

Notes for Clipper programmers

The xHarbour programming language has its roots in CA-Clipper, a powerful xBase dialect, and is modelled around Clipper. xHarbour extends Clipper and has received many new features, which can be detected very easily:

Extended function arguments are highlighted in yellow. Refer to functionAIns()for an example.

All topics that do not exist in Clipper, but are added by xHarbour, are listed in the categoryxHarbour extensions.

Copyright

Please read theCopyright notecarefully before using this guide.

Your contributions

This Version 1.0 of the xHarbour Language Reference Guide can only reflect the current stage of xHarbour and its documentation, as of Dec 2006. We are constantly adding new features to xHarbour and new information to the documentation. If you miss something particular, please let us know. This file should give you a clear idea of xHarbour.com commitment to the xHarbour programming language. We are grateful for any suggestion you may have to improve xHarbour.

(5)

Table of Contents

( )... 19 *... 21 **... 22 +... 23 ++... 25 -... 26 -- ... 28 ->... 29 .AND... 31 .NOT... 32 .OR... 33 :... 35 :=... 37 <... 38 <<... 40 <=... 41 <> != #... 43 <|| > ... 45 = (assignment)... 47 = (comparison)... 48 = (compound assignment) ... 50 ==... 52 >... 54 >=... 56 >>... 58 @ ... 59 @()... 60 HAS ... 62 IN ... 64 LIKE ... 66 [ ] (array)... 68 [ ] (string)... 69 ^^... 71 { } ... 73 {=>} ... 74 {|| }... 76 | (bitwise OR)... 78 STATEMENT REFERENCE... 80 (struct) ... 81 ACCESS... 82 ANNOUNCE... 84 ASSIGN... 85 BEGIN SEQUENCE ...92 CLASS ...94 CLASSDATA ...99 CLASSMETHOD ...102 DATA...103 DELEGATE...106 DESTRUCTOR ...108 DO CASE...110 DO WHILE ...112

ENABLE TYPE CLASS...114

ERROR HANDLER ...116

EXIT PROCEDURE ...118

EXPORTED: ...120

EXTEND CLASS...WITH DATA ...121

EXTEND CLASS...WITH METHOD...123

EXTERNAL ...125 FIELD...126 FOR ...128 FOR EACH ...130 FUNCTION ...132 GLOBAL...135 HIDDEN:...137 IF...139 INIT PROCEDURE ...141 INLINE METHOD ...143 LOCAL ...145 MEMVAR ...147 MESSAGE ...148 METHOD (declaration) ...150 METHOD (implementation)...153 METHOD...OPERATOR ...156 METHOD...VIRTUAL ...158 OPERATOR...159 OVERRIDE METHOD ...161 PARAMETERS...163 pragma pack() ...164 PRIVATE ...165 PROCEDURE...167 PROTECTED: ...169 PUBLIC ...170 REQUEST...172 RETURN ...173 STATIC...174 SWITCH...176 TRY...CATCH...178 typedef struct ...180 WITH OBJECT...183 COMMAND REFERENCE... 185 ? | ?? ...186 @...BOX ...188 @...CLEAR...190 @...GET...192 @...PROMPT...196 @...SAY ...197

(6)

Table of Contents ACCEPT...202 APPEND BLANK...203 APPEND FROM ...205 AVERAGE ...208 CANCEL...210 CLEAR ALL...211 CLEAR MEMORY ...212 CLEAR SCREEN...213 CLEAR TYPEAHEAD ... 214 CLOSE ...215 COMMIT...217 CONTINUE ...218 COPY FILE ...219 COPY STRUCTURE ... 220

COPY STRUCTURE EXTENDED...221

COPY TO ...223 COUNT...227 CREATE...229 CREATE FROM ...231 DO ...233 DEFAULT TO ...234 DELETE...235 DELETE FILE ...237 DELETE TAG...238 EJECT ... 240 ERASE ...241 FIND...242 GO ...243 INDEX ...245 INPUT ...249 JOIN ...250 KEYBOARD...252 LOCATE...254 MENU TO...256 PACK...258 QUIT ...259 READ...260 RECALL...262 REINDEX ...264 RELEASE...265 RENAME...267 REPLACE ...269 RESTORE...271 RUN ...273 SAVE...274 SEEK...275 SELECT ...277 SET ALTERNATE ...279 SET AUTOPEN ...281 SET AUTORDER...283 SET AUTOSHARE...284

SET BACKGROUND TASKS...285

SET BACKGROUNDTICK ...286 SET BELL ...287 SET CENTURY...288 SET COLOR...289 SET CONFIRM ...290 SET CONSOLE ...291 SET CURSOR ...292 SET DATE ... 293 SET DBFLOCKSCHEME ...295 SET DECIMALS ... 297 SET DEFAULT ... 298 SET DELETED ... 299 SET DELIMITERS ...301 SET DESCENDING ... 302 SET DEVICE ...303 SET DIRCASE...305 SET DIRSEPARATOR... 306 SET EOL ... 307 SET EPOCH ...308 SET ERRORLOG...309 SET ERRORLOOP...310 SET ESCAPE...311 SET EVENTMASK ... 312 SET EXACT ... 314 SET EXCLUSIVE ...316 SET FILECASE ... 317 SET FILTER ... 318 SET FIXED ...320 SET FUNCTION... 321 SET INDEX...323 SET INTENSITY ... 325 SET KEY...326 SET MARGIN...327 SET MEMOBLOCK... 328 SET MESSAGE...330 SET OPTIMIZE...331 SET ORDER ...332 SET PATH ... 334 SET PRINTER...335 SET RELATION ... 337 SET SCOPE ... 339 SET SCOPEBOTTOM... 341 SET SCOPETOP... 342 SET SCOREBOARD ... 343 SET SOFTSEEK...344 SET STRICTREAD...346 SET TRACE ... 347 SET TYPEAHEAD ...348 SET UNIQUE ...349 SET VIDEOMODE... 350 SET WRAP...351 SKIP ...352 SORT... 354 STORE...356 SUM ... 357 TEXT ... 359 TOTAL...360 UNLOCK... 362 UPDATE... 363 USE ... 365

(7)

Table of Contents WAIT... 367 ZAP... 368 FUNCTION REFERENCE ... 369 AAdd()... 370 Abs()... 371 AChoice()... 372 AClone() ... 377 ACopy() ... 379 ADel()... 381 ADir() ... 383 AEval() ... 385 AFields() ... 387 AFill()... 389 AIns()... 391 ALenAlloc()... 393 Alert()... 394 Alias()... 396 AllTrim()... 397 AltD() ... 398 AmPm() ... 400 Array()... 401 Asc()... 402 AScan()... 403 ASize()... 405 ASizeAlloc() ... 406 ASort()... 407 At()... 409 ATail() ... 411 Bin2I() ... 412 Bin2L()... 413 Bin2U()... 414 Bin2W() ... 415 BlobDirectExport() ... 416 BlobDirectGet() ... 419 BlobDirectImport()... 421 BlobDirectPut() ... 423 BlobExport()... 425 BlobGet()... 427 BlobImport() ... 428 BlobRootDelete() ... 430 BlobRootGet() ... 431 BlobRootLock()... 432 BlobRootPut() ... 433 BlobRootUnlock()... 435 BoF() ... 436 Break() ... 438 Browse()... 440 CDoW() ... 442 Chr() ... 443 CMonth()... 445 Col() ... 447 ColorSelect()... 448 ConvToAnsiCP()... 450 ConvToOemCP()... 451 CtoD() ...454 CurDir() ...455 CurDrive() ...456 Date() ...457 Day() ...458 Days() ...459 DbAppend() ...460 DbClearFilter() ...462 DbClearIndex()...463 DbClearRelation() ...464 DbCloseAll() ...465 DbCloseArea()...466 DbCommit() ...467 DbCommitAll()...468 DbCopyExtStruct() ...469 DbCopyStruct() ...470 DbCreate() ...472 DbCreateIndex() ...475 DbDelete() ...477 DbEdit() ...478 DbEval() ...483 Dbf() ...485 DbFieldInfo()...486 DbFileGet() ...488 DbFilePut()...489 DbFilter() ...490 DbGoBottom() ...492 DbGoto()...493 DbGoTop() ...495 DbInfo() ...496 DbOrderInfo() ...503 DbRecall() ...510 DbRecordInfo() ...511 DbReindex() ...513 DbRelation() ...514 DbRLock() ...516 DbRLockList() ...518 DbRSelect() ...519 DbRUnlock()...521 DbSeek() ...522 DbSelectArea()...524 DbSetDriver() ...526 DbSetFilter() ...527 DbSetIndex()...529 DbSetOrder() ...530 DbSetRelation() ...531 DbSkip() ...533 DbSkipper()...535 DbStruct() ...537 DbTableExt()...539 DbUnlock()...540 DbUnlockAll()...541 DbUseArea() ...542 DefPath() ...544 Deleted()...545

(8)

Table of Contents DevOut()...549 DevOutPict() ...550 DevPos() ...551 DirChange() ...552 Directory() ...553 DirectoryRecurse()...555 DirRemove() ...557 DiskChange() ...558 DiskName()...560 DiskSpace() ...561 DispBegin() ...563 DispBox() ...565 DispCount()...567 DispEnd() ...568 DispOut() ...569 DispOutAt()...570 DispOutAtSetPos()...572 DllCall()...573 DllExecuteCall() ...576 DllLoad()...578 DllPrepareCall() ...579 DllUnload() ...581 DosError()...582 DoW()...585 DtoC()...586 DtoS() ...587 ElapTime() ...589 Empty()...590 Eof()...592 ErrorBlock() ...594 ErrorLevel()...597 ErrorNew()...599 ErrorSys()...601 Eval() ... 602 Exp() ...604 FCharCount() ...605 FClose()...606 FCount()...608 FCreate()...609 FErase() ...611 FError()...612 FieldBlock() ...613 FieldDec()...615 FieldGet()...616 FieldLen()...617 FieldName()...618 FieldPos()...619 FieldPut() ...620 FieldType()...622 FieldWBlock() ...623 File()...625 FileStats() ...627 FkLabel()...629 FkMax() ...630 FLineCount() ...631 FLock() ...632 FOpen() ... 634 Found()...636 FParse()... 638 FParseEx() ... 640 FParseLine()... 641 FRead()...643 FReadStr() ... 645 FreeLibrary()...647 FRename()... 648 FSeek()... 650 FWordCount() ... 652 FWrite()... 653 GetCurrentThread()... 655 GetDefaultPrinter() ... 656 GetEnv() ...657 GetLastError() ... 658 GetNew() ... 659 GetPrinters()...661 GetProcAddress() ... 663 GetRegistry() ... 665 GetSystemThreadID()... 667 GetThreadID() ... 668 HaaDelAt() ...670 HaaGetKeyAt() ...672 HaaGetPos()...674 HaaGetRealPos() ... 676 HaaGetValueAt()... 678 HaaSetValueAt() ... 680 HAllocate() ...682 HardCR()...683 Hash()...684 HB_AExpressions() ... 686 HB_AnsiToOem()... 688 HB_AParams()... 690 HB_ArgC() ... 691 HB_ArgCheck()...692 HB_ArgString()...693 HB_ArgV() ... 694 HB_ArrayId() ... 696 HB_ArrayToStructure()... 697 HB_ATokens()...699 HB_AtX() ... 701 HB_BackGroundActive()... 703 HB_BackGroundAdd() ...704 HB_BackGroundDel() ... 706 HB_BackGroundReset()...707 HB_BackGroundRun() ...708 HB_BackGroundTime()... 709 HB_BitAnd() ...710 HB_BitIsSet() ... 711 HB_BitNot() ... 713 HB_BitOr() ... 714 HB_BitReset()...715 HB_BitSet()...717 HB_BitShift() ... 719 HB_BitXOr()... 721

(9)

Table of Contents HB_BuildDate() ... 722 HB_BuildInfo() ... 723 HB_CheckSum() ... 725 HB_CmdArgArgV()... 726 HB_Compiler() ... 727 Hb_CRC32()... 728 HB_Crypt() ... 729 HB_Decrypt() ... 730 HB_DeSerialize() ... 731 HB_EnumIndex() ... 732 HB_Exec()... 734 HB_ExecFromArray() ... 736 HB_FNameMerge()... 740 HB_FNameSplit() ... 741 HB_FReadLine() ... 743 HB_FSize() ... 745 HB_FTempCreate() ... 746 HB_FuncPtr()... 748 HB_GCAll() ... 749 HB_GCStep() ... 750 HB_IdleAdd()... 751 HB_IdleDel()... 753 HB_IdleReset() ... 754 HB_IdleSleep() ... 755 HB_IdleSleepMSec()... 756 HB_IdleState()... 757 HB_IsArray() ... 758 HB_IsBlock()... 759 HB_IsByRef... 760 HB_IsDate()... 762 HB_IsHash() ... 763 HB_IsLogical() ... 764 HB_IsMemo()... 765 HB_IsNIL() ... 766 HB_IsNull()... 767 HB_IsNumeric()... 768 HB_IsObject()... 769 HB_IsPointer()... 770 HB_IsRegExString() ... 771 HB_IsString()... 772 HB_KeyPut()... 773 HB_LangSelect()... 774 HB_LibDo()... 777 HB_MacroCompile() ... 779 HB_MD5() ... 780 HB_MD5File() ... 781 HB_MultiThread() ... 782 HB_MutexCreate()... 783 HB_MutexLock() ... 786 HB_MutexTimeoutLock() ... 787 HB_MutexTryLock() ... 788 HB_MutexUnlock() ... 789 HB_ObjMsgPtr()... 790 HB_OemToAnsi() ... 792 HB_OsNewLine()... 793 HB_QWith() ...795 HB_Random() ...796 HB_RandomInt()...798 HB_RandomSeed() ...800 HB_ReadIni() ...802 HB_RegEx()...804 HB_RegExAll()...807 HB_RegExComp()...811 HB_RegExMatch() ...812 HB_RegExSplit()...814 HB_ResetWith() ...816 HB_RestoreBlock()...818 HB_SaveBlock() ...819 HB_Serialize() ...820 HB_SetCodePage() ...822 HB_SetIniComment() ...824 HB_SetMacro() ...825 HB_SetWith()...826 HB_SizeofCStructure() ...828 HB_StructureToArray() ...830 HB_ThisArray() ...832 HB_VMExecute() ...833 HB_VMMode()...834 HB_WithObjectCounter()...835 HB_WriteIni()...836 HB_XmlErrorDesc()...838 HClone() ...839 HCopy()...841 HDel() ...844 HDelAt() ...845 Header() ...846 HEval() ...847 HexToNum() ...849 HexToStr()...850 HFill() ...851 HGet() ...852 HGetAACompatibility()...853 HGetAutoAdd()...854 HGetCaseMatch()...855 HGetKeyAt()...857 HGetKeys()...858 HGetPairAt() ...859 HGetPartition()...860 HGetPos() ...861 HGetVaaPos() ...863 HGetValueAt() ...865 HGetValues() ...866 HHasKey()...867 HMerge() ...868 HScan() ...869 HSet()...871 HSetAACompatibility()...873 HSetAutoAdd()...875 HSetCaseMatch()...877 HSetPartition()...879

(10)

Table of Contents I2Bin()...883 If() | IIf()...885 IndexExt() ...887 IndexKey()...888 IndexOrd() ...890 Inkey()...891 Int()...893 IsAlNum()...894 IsAlpha()...895 IsAscii()...896 IsCntrl()...897 IsColor() ...898 IsDigit()...899 IsDirectory()...900 IsDisk()...901 IsGraph()...903 IsLower()...904 IsPrint()...905 IsPrinter()...906 IsPunct() ...908 IsSameThread() ...909 IsSpace()...911 IsUpper()...912 IsValidThread() ...913 IsXDigit()...915 JoinThread()...916 KillAllThreads() ...918 KillThread() ...919 L2bin() ...920 LastKey()...922 LastRec()...924 Left()...925 Len() ...926 LenNum()...928 LibFree() ...929 LibLoad()...930 LoadLibrary() ...931 Log() ...933 Lower() ...934 LTrim() ...935 LUpdate()...936 MakeDir()...937 Max()... 939 MaxCol()...940 MaxRow()...941 MCol()...942 MDblClk() ...943 MemoEdit() ...944 MemoLine()...951 MemoRead() ...954 Memory() ...955 MemoTran() ...957 MemoWrit() ...958 MemVarBlock() ...959 MenuModal() ...960 MHide() ...962 Min() ... 963 MLCount() ... 964 MLCToPos() ... 966 MLeftDown() ... 968 MlPos()...969 Mod() ...971 Month()... 972 MPosToLC() ... 973 MPresent() ...975 MRestState() ... 976 MRightDown()... 977 MRow() ... 978 MSaveState()... 979 MSetBounds()...980 MSetCursor() ... 981 MSetPos()...982 MShow()...983 NetErr() ... 984 NetName() ...986 NextKey()... 987 Notify() ...989 NotifyAll()...990 NumButtons()...992 NumToHex()...993 OrdBagExt()... 994 OrdBagName()...995 OrdCondSet()... 997 OrdCount() ...1000 OrdCreate() ... 1002 OrdCustom()...1004 OrdDescend() ...1005 OrdDestroy() ... 1007 OrdFindRec() ... 1008 OrdFor()... 1010 OrdIsUnique()...1011 OrdKey() ...1012 OrdKeyAdd()...1014 OrdKeyCount()... 1016 OrdKeyDel() ... 1018 OrdKeyGoTo()...1020 OrdKeyNo() ... 1022 OrdKeyRelPos() ... 1024 OrdKeyVal() ... 1026 OrdListAdd()...1027 OrdListClear() ...1029 OrdListRebuild() ... 1030 OrdName() ...1031 OrdNumber()... 1033 OrdScope() ...1035 OrdSetFocus()...1037 OrdSetRelation() ... 1039 OrdSkipRaw() ...1040 OrdSkipUnique()... 1042 OrdWildSeek() ... 1044 Os()... 1046 Os_IsWin2000()... 1047

(11)

Table of Contents Os_IsWin2000_Or_Later() ... 1048 Os_IsWin2003() ... 1049 Os_IsWin95() ... 1050 Os_IsWin98() ... 1051 Os_IsWin9X() ... 1052 Os_IsWinME() ... 1053 Os_IsWinNT()... 1054 Os_IsWinNT351()... 1055 Os_IsWinNT4()... 1056 Os_IsWinVista() ... 1057 Os_IsWinXP() ... 1058 Os_IsWtsClient() ... 1059 Os_VersionInfo() ... 1060 OutErr() ... 1062 OutStd() ... 1063

PadC() | PadL() | PadR() ... 1064

PCol() ... 1066 PCount()... 1068 PrinterExists()... 1069 PrinterPortToName()... 1070 PrintFileRaw() ... 1071 ProcFile()... 1073 ProcLine()... 1074 ProcName()... 1075 PRow() ... 1076 PValue() ... 1078 QOut() | QQOut()... 1079 QueryRegistry()... 1081 RAscan()... 1084 RAt()... 1086 RddInfo() ... 1088 RddList()... 1091 RddName()... 1093 RddSetDefault() ... 1094 ReadModal()... 1096 RecCount() ... 1098 RecNo() ... 1099 RecSize()... 1100 Replicate()... 1101 RestScreen()... 1102 Right()... 1104 RLock() ... 1105 Round() ... 1107 Row() ... 1109 RTrim()... 1110 SaveScreen() ... 1112 Scroll()... 1114 Seconds() ... 1116 SecondsSleep()... 1117 Secs()... 1118 Select()... 1119 Set() ... 1120 SetBlink()... 1127 SetCancel()... 1128 SetColor()... 1130 SetErrorMode()...1134 SetKey() ...1135 SetLastError()...1138 SetMode()...1139 SetMouse() ...1141 SetPos()...1142 SetPrc() ...1143 SetRegistry() ...1145 SoundEx()...1147 Space()...1148 Sqrt()...1149 StartThread() ...1150 StoD()...1153 StopThread()...1154 Str()...1155 StrToHex()...1157 StrTran() ...1158 StrZero()...1160 Stuff()...1162 Subscribe() ...1164 SubscribeNow() ...1166 SubStr()...1167 TBMouse() ...1169 TBrowseDB()...1170 TBrowseNew() ...1172 ThreadSleep() ...1173 Throw() ...1174 Time() ...1175 Tone() ...1176 TraceLog()...1177 Transform() ...1178 Trim() ...1180 TString() ...1182 Type()...1183 U2bin()...1185 Upper() ...1187 Used() ...1188 Val()...1189 ValToPrg()...1191 ValToPrgExp()...1193 Valtype()...1195 Version() ...1197 W2bin()...1198 WaitForThreads() ...1199 WildMatch() ...1200 Word() ...1202 Year() ...1203

CLASS REFERENCE (TEXTMODE) ...1204

C Structure class ...1205 Error() ...1211 Get() ...1219 HBObject() ...1237 HBPersistent()...1243 MenuItem() ...1246

(12)

Table of Contents TBColumn()...1260 TBrowse() ...1265 TopBarMenu() ...1288 TXmlDocument() ...1299 TXmlIterator()...1309 TXmlIteratorRegEx()... 1312 TXmlIteratorScan() ... 1315 TXmlNode() ...1318 PREPROCESSOR REFERENCE ... 1330 #command | #translate ...1331 #define...1338 #error ...1341 #if ...1342 #ifdef ... 1344 #ifndef ...1346 #include...1347 #pragma...1349 #stdout...1351 #uncommand | #untranslate ...1352 #undef ...1353 #xcommand | #xtranslate... 1354 #xuncommand | #xuntranslate...1355

NOT INCLUDED IN THIS EDITION... 1356

UNDOCUMENTED FUNCTIONS...1357

UNDOCUMENTEDCGI FUNCTIONS...1358

UNDOCUMENTEDCT FUNCTIONS...1359

UNDOCUMENTEDMISCFUNCTIONS...1361

UNDOCUMENTEDRDD FUNCTIONS...1362

UNDOCUMENTEDRTL FUNCTIONS...1363

UNDOCUMENTEDTIP FUNCTIONS... 1365

UNDOCUMENTEDVM FUNCTIONS...1366 CATEGORIES ... 1367 Array functions...1367 Assignment operators...1367 Associative arrays... 1367 Background processing ...1367 Binary functions ... 1368 Bitwise functions...1368 Bitwise operators ... 1368 Blob functions...1368 C Structure support ...1369 Character functions...1369 Character operators ... 1370 Checksum functions...1370 Class declaration ...1370

Code block functions ...1371

Comparison operators...1371 Console commands ...1371 Control structures... 1371 Conversion functions...1372 Database commands...1373 Database drivers ...1374 Database functions ... 1374

Date and time ... 1376

Debug functions... 1376 Declaration...1377 Directory functions... 1378 DLL functions... 1378 Environment commands ... 1378 Environment functions... 1379 Error functions ...1379 Field functions ... 1380 File commands ...1380 File functions ... 1380 Get system ...1381 Hash functions ...1381 Index commands ... 1382 Index functions...1382 Indirect execution... 1383 Info functions ...1383 Input commands ... 1383 Keyboard functions ... 1384 Language specific... 1384 Logical functions ... 1384 Logical operators ... 1384

Low level file functions... 1384

Mathematical functions... 1385 Mathematical operators... 1385 Memo functions... 1385 Memory commands... 1385 Mouse functions... 1385 Multi-threading functions... 1386 Mutex functions... 1386 Network functions... 1387 Numeric functions... 1387 Object functions... 1387 Operators ...1388 Output commands ... 1388 Output functions ... 1389 Pointer functions... 1389 Preprocessor directives ...1389 Printer commands... 1389 Printer functions... 1390 Random generator... 1390 Registry functions ... 1390 Regular expressions ... 1390 Screen functions... 1390 SET commands...1391 Special operators ... 1392 Statements...1392 UI functions ... 1392 xHarbour extensions ...1393 INDEX ...1399

(13)

(14)

$

Substring operator (binary): search substring in string.

Syntax

Arguments

<cSubString> is a character value that is searched for in <cString>. <cString>

<cString> is a character value where <cSubString> is searched in. <xExp>

<xExp> is the expression of any type to search. <aArray>

<aArray> is the array to scan for a matching <xExp> in.

Description

The substring operator performs a case-sensitive search and returns .T. (true) when <cSubString> is found in <cString>, otherwise the result is .F. (false).

The $ operator can also be used to search for a given value within any Array.

Info

See also: <,<=,<> != #,= (comparison),==,>,>=,IN,HAS,LIKE

Category: Character operators,Comparison operators,Operators

DLL: xhbdll.dll

Example

// The example demonstrates a case-sensitive search. PROCEDURE Main()

LOCAL cString := "xHarbour"

? "X" $ cString // result: .F. ? "arb" $ cString // result: .T. ? 1 $ { 3, 2, 1 } // result: .T. RETURN

(15)

%

Modulus operator (binary): calculates the remainder of a division.

Syntax

Arguments

<nNumber1> is the dividend of the division. <nNumber2>

<nNumber2> is the divisor of the division.

Description

The modulus operator returns the remainder of dividing <nNumber1> by <nNumber2>.

Info

See also: *,**,+,-,/,= (compound assignment),SET FIXED

Category: Mathematical operators,Operators

LIB: xhb.lib

DLL: xhbdll.dll

Example

// The example calculates the remainder of a division // between two numbers.

PROCEDURE Main ? 5 % 0 // result: 0 ? 3 % 2 // result: 1 ? -2 % 3 // result: -2 ? 4 % 2 // result: 0 ? 5.4 % 2.3 // result: 0.8 RETURN

(16)

& (bitwise AND)

Bitwise AND operator (binary): performs a logical AND operation.

Syntax

<cString> & <nMask>|<cMask> --> cCharacter <nNumber> & <nMask>|<cMask> --> nNumeric

Arguments

A character expression of which all bits of each character are processed in a logical AND operation.

A numeric value all bits of which are processed. Numbers are always treated as integer values. If a number has a decimal fraction, it is truncated.

The right operand of the bitwise AND operator can be specified as a character or a numeric value.

Description

The bitwise AND operator performs a logical AND operation with the individual bits of both operands. The left operand is the value to process while the right operand provides the bit mask for the operation. The return value of the &-operator has the same data type as the left operand.

Bits at identical positions in both operands are compared. The bit at the same position is set in the return value, when both operands have the bit set at the same position. If either operand has a bit not set, the corresponding bit in the return value is a lso not set.

The bit mask to apply to the left operand can be specified as a numeric or as a character value. Depending on the left operand, bitwise AND operations are performed according to the following rules:

cString & cMask

When both operands are character values, the bits of individual characters of both operands are

compared. If the right operand has less characters, it is repeatedly applied until all characters of the left operand are processed. The return value has the same number of characters as the left operand.

cString & nMask

When the left operand is a character value and the right operand is numeric, the bits set in the numeric value are compared with the bits of each character in the left operand.

nNumber & cMask

When the left operand is numeric and the right operand is a character value, the bits set in the numeric value are compared consecutively with the bits of each character in the right operand.

(17)

& (bitwise AND)

nNumber & nMask

When both operands are numeric values, the bits of both values are compared.

Note: Numeric operands are always treated as integer values. If a number has a decimal fraction, it is

ignored.

Info

See also: ^^ (bitwise XOR),| (bitwise OR),.AND.,.NOT.,.OR.

Category: Bitwise operators,Operators,xHarbour extensions

LIB: xhb.lib

DLL: xhbdll.dll

Example

// The example demonstrates bitwise AND operations using // operands of different data types.

#define STAT_OFF 0 #define STAT_INIT 1 #define STAT_IDLE 2 #define STAT_ON 4 PROCEDURE Main

LOCAL nStatus := STAT_INIT + STAT_IDLE

? 2 & 3 // result: 2 ? "A" & 64 // result: "@" ? 64 & "A" // result: 64 ? "Z" & "A" // result: "@" ? nStatus & STAT_IDLE // result: 2 ? nStatus & STAT_ON // result: 0 ? "One" & "Two" // result: "Dfe" RETURN

(18)

& (macro operator)

Macro operator (unary): compiles a character string at runtime.

Syntax

a) &<cVarName>

b) "Text &<cVarName>. substitution" c) &<cExpression> d) <objVar>:&<cIVarName> [:= <xValue>] <objVar>:&<cMethodName>([<params,...>]) e) &<cFunctionName>([<params,...>])

Arguments

This is a character string indicating the name of a variable whose symbolic name is known at runtime. This applies to variables of type PRIVATE, PUBLIC or FIELD.

A character string holding a valid xHarbour expression to compile at runtime. <objVar>

This is a variable holding a reference to an object value (Valtype() == "O") to which a message is sent.

A character string indicating the name of an instance variable of the object. If no assignment operator is used in the expression, the value of the instance variable is retrieved by the macro operator. Otherwise, the value <xValue> is assigned to the instance variable.

A character string indicating the name of a method of the object to execute. Calling a method with the macro operator requires the parentheses () be added to the expression. Optionally, a list of parameters can be specified within the parentheses. The list of <params,...> is passed to the method.

A character string indicating the name of a function or procedure to execute. Calling a function with the macro operator requires the parentheses () be added to the expression. Optionally, a list of parameters can be specified within the parentheses. The list of <params,...> is passed to the function or procedure.

Description

One extremely powerful feature of xHarbour is the Macro operator (&). It allows for compiling and executing program code at runtime of an application. The program code is supplied in form of a character string and can be as simple as a variable name or may include very complex expressions.

(19)

& (macro operator) Despite its power, there are some limitations a programmer must be aware of when using the Macro operator.

As a first rule, no white space characters may follow the macro operator. This is required to distinguish the & sign from the bitwise AND operator. The macro expression must follow the & operator

immediately.

All entities that do not have a symbolic name at runtime of an application cannot be accessed by the Macro operator. This applies to memory variables of type GLOBAL, LOCAL and STATIC, to STATIC declared functions and procedures, as well as commands and statements. Also, the Macro operator cannot resolve multiple line expressions, it can only compile expressions programmed within one line of code.

As indicated in the syntax description, there are some typical scenarios where the Macro operator is used. Examples for these scenarios follow:

a) Acessing and creating variables

The values of PRIVATE, PUBLIC and FIELD variables can be retrieved by using a character string indicating the symbolic name of a variable.

LOCAL cPrivate := "myPrivate" LOCAL cPublic := "myPublic" LOCAL cField := "LastName" LOCAL x, y, z

PUBLIC myPublic := "A public variable" PRIVATE myPrivate := 10 USE Customer x := &cPrivate y := &cPublic z := &cField ? x, y, z

// result: 10 A public variable Miller

The macro operator is used in this example as the right-hand-side expression of the assignments. As a result, the values of the variables whose names are stored in LOCAL variables are retrieved and assigned to the LOCAL variables x, y and z.

When the macro operator is used on the left-hand-side of an assignment, a value is assigned to the corresponding variable. If the variable does not exist prior to the assignment, it is created as a PRIVATE variable:

LOCAL cPrivate := "myPrivate" LOCAL cPublic := "myPublic" LOCAL cField := "LastName"

PUBLIC myPublic := "A public variable" USE Customer

&cPrivate := 10 // creates a PRIVATE variable // named myPrivate

&cPublic := "New text" FIELD->&cField := "McBride" ? &cPrivate, &cPublic, &cField

(20)

& (macro operator)

Note that PUBLIC variables cannot be created using this technique while field variables must be aliased to assign a value.

b) Text substitution

Text substitution is a special situation where the macro operator appears within a character string.

LOCAL cText

PRIVATE cMacro := "xHarbour"

cText := "This is a &cMacro. test." ? cText

// result: This is a xHarbour test." cMacro := CDoW(Date())

cText := "Today is &cMacro.!" ? cText

// result: Today is Tuesday!"

When a character string contains a macro variable, the macro is substituted with the contents of the macro variable. Note that the end of the macro variable within the text string is indicated with a period. This period does not appear in the result string but serves as "end-of-macro" marker.

c) Runtime compilation

The most common situation for using the Macro operator is the compilation of expressions at runtime. Expressions must be syntactically correct and may only refer to entities whose symbolic names are known at runtime. If, for example, a function is called only within a Macro expression and nowhere else in the program code, the function symbol must be declared with the REQUEST statement so that it is linked to the executable file.

PROCEDURE Main

REQUEST CDoW, Date

LOCAL cExpr := "CDoW(Date())" ? &cExpr

// result: Tuesday RETURN

The creation of code blocks as complex data types is also a very common usage scenario for the Macro operator.

PROCEDURE Main

LOCAL i, cExpr, cFPos REQUEST FieldGet, FieldPut USE Customer

aBlocks := Array( FCount() ) FOR i:=1 TO FCount()

cFPos := LTrim( Str(i) )

cExpr := "{|x| IIf(x==NIL,FieldGet(" + cFPos + ")," + ; "FieldPut(" + cFPos + ",x)) }" aBlocks[i] := &cExpr

(21)

& (macro operator) Within the FOR..NEXT loop, the syntax for code blocks accessing different field variables is created as character strings. Each string differs by the value of the loop counter variable which identifies individual field variables by theri ordinal position. The character strings are compiled to code blocks and stored in an array.

d) Sending messages to objects

The possibility of sending messages to objects is another field of Macro operator usage that allows for highly dynmic application development. Messages are encoded as character strings:

#include "hbclass.ch" PROCEDURE Main

LOCAL obj := TestClass():new( "Text to display" ) LOCAL cMsg := "display"

obj:&cMsg() // displays: Text to display cMsg := "cValue"

obj:&cMsg := "New text"

obj:display() // displays: New text RETURN

CLASS TestClass EXPORTED: DATA cValue

METHOD new( cString ) CONSTRUCTOR METHOD display

ENDCLASS

METHOD new( cString ) CLASS TestClass ::cValue := cString

RETURN self

METHOD display() CLASS TestClass ? ::cValue

RETURN self

When the send operator (:) is followed by the Macro operator, the contents of the variable following the Macro operator is interpreted as message to send to the object. Note that calling an object's method requires the parentheses be added to the expression.

e) Calling functions

There are two possibilities for calling functions using the macro operator: one is to encode a complete function call as a macro expression, the other is to use only the function name. The difference between both possibilities lies in the type of variables that can be passed to a Macro operator called function.

PROCEDURE Main LOCAL cMacro LOCAL nValue := 2 PRIVATE nNumber := 3

cMacro := "TestFunc( nNumber )" // result: 30 ? &cMacro

(22)

& (macro operator)

? &cMacro( nValue ) // result: 20 RETURN

FUNCTION TestFunc( n ) RETURN 10 * n

When the macro expression includes parentheses for the function call, only PRIVATE, PUBLIC or FIELD variables can be passed as parameters, since the variable names appear in the macro string. LOCAL variables, in contrast, can be passed when the parentheses are "hard coded", i.e. the macro string contains only the name of the function to call.

Info

See also: @(),( ),{|| },HB_MacroCompile(),HB_SetMacro()

Category: Indirect execution,Special operators,Operators

LIB: xhb.lib

(23)

( )

Execution or grouping operator.

Syntax

(<expr,...>) <symbol>([<params,...>]) <objVar>:<symbol>([<params,...>])

Arguments

<expr,...>

One or more expressions to execute, separated with commas. <symbol>

This is the symbolic name of a function, method or procedure to execute. <params,...>

An optional comma separated list of parameters to pass to the called function, method or procedure

This is a variable holding a reference to an object value (Valtype() == "O") that should execute a method.

Description

Parentheses are used to execute functions, procedures or methods, and to group expressions and define their order of execution.

When using the parentheses as a grouping operator, all items appearing inside the parentheses must be valid expressions. The grouping operator can be nested to any depth. The nesting level influences execution order of expressions, i.e. expressions on a deeper nesting level are evaluated first while expressions with the same nesting level are evaluated from left to right.

When the parantheses are used as execution operator, expressions between the parentheses are passed as arguments to the called function, method or procedure. Multiple expressions must be separated with commas. When no expression appears within the parentheses, no argument is passed.

Info

See also: & (macro operator)

Category: Special operators,Operators

LIB: xhb.lib

DLL: xhbdll.dll

Example

// The example demonstrates different scenarios for using // the () operator.

(24)

( )

// changing precedence of operations

? 5 + 2 * 2 // result: 9 ? (5 + 2)* 2 // result: 14 ? 5 + 2 * 2 - 1 // result: 8 ? 5 +(2 *(2 - 1)) // result: 7 x := " xHarbour "

// one function call

? AllTrim( x ) // result: "xHarbour" // list of function calls

? ( x := Date(), CDow(x) ) // result: "Wednesday" RETURN

(25)

*

Multiplication operator (binary): multiplys numeric values.

Syntax

Arguments

<nNumber1> is numeric expression to multiply with <nNumber2>. <nNumber2>

<nNumber2> is numeric expression to multiply with <nNumber1>.

Description

This operator multiplies the value of <nNumber1> with the value of <nValue2> and returns the result.

Info

See also: %,**,+,-,/,= (compound assignment),SET DECIMALS,SET FIXED

LIB: xhb.lib

DLL: xhbdll.dll

Example

// The example shows the behavior of the "*" operand in different // situations. PROCEDURE Main ? 3 * 1 // result: 3 ? 3 * -1 // result: -1 ? -4 * -2 // result: 8 RETURN

(26)

**

Exponentiation (binary): raises a number to the power of an exponent.

Syntax

Arguments

<nNumber> is numeric value to raise to the power defined by <nExponent>. <nExponent>

<nExponent> is the power to raise <nNumber1>.

Description

This operator is a binary operator that raises <nNumber> to the power of <nExponent>.

Info

See also: %,*,+,-,/,= (compound assignment),SET DECIMALS,SET FIXED

LIB: xhb.lib

DLL: xhbdll.dll

Example

// The example shows some results of the "**" operator. PROCEDURE Main ? 5 ** 0 // result: 1.00 ? 5 ** 1 // result: 5.00 ? 5 ** 2 // result: 25.00 ? 5 ** -2 // result: 0.04 ? -5 ** 2 // result: 25.00 ? 5 ^ 0 // result: 1.00 ? 5 ^ 1 // result: 5.00 ? 5 ^ 2 // result: 25.00 ? 5 ^ -2 // result: 0.04 ? -5 ^ 2 // result: 25.00 RETURN

(27)

+

Plus operator: add values, concatenate values and unary positive.

Syntax

Arguments

<nNumber1> is a numeric value to which the value of <nNumber2> is added. <dDate>

<dDate> is a date value to which <nNumber> days are added. <cString2>

<cString2> is a character string to concatenate with <cString1>.

Description

Depending on the data types of the operands, the Plus operator performs different operations.

Unary positive sign

A numeric expression preceeded by the "+" operator performs no operation on the operand.

Numeric addition

When both operands are numeric values, the right operand <nNumber2> is added to the left operand <nNumber1> and the result is a numeric value.

Date addition

When eigher operand is a date value and the other is a numeric, the value of <nNumber> is added as days to <dDate>. The returned value is a date.

String concatenation

If both operands are character strings, the value of <cString2> is joined to the end of <cString1>. The result is a character string containing both operands.

Hash operation

If both operands are hashes, a set-oriented operation is performed so that the resulting hash value contains unique keys of both operands (refer to thehash operator).

(28)

+

Info

See also: %,*,**,++,-,/,= (compound assignment),{=>}

Category: Character operators,Mathematical operators,Operators

LIB: xhb.lib

DLL: xhbdll.dll

Example

// The example demonstrates variations with the + operator: PROCEDURE Main

// Unary positive sign (also included is the negative sign) ? 1 + + 1 // result: 2 ? 1 + - 1 // result: 0 ? 1 - - 1 // result: 2 // Addition ? 10 + 2 // result: 12 ? CtoD("01/01/2005") + 5 // result: 01/06/2005 ? 31 + CtoD("01/01/2005") // result: 02/01/2005 // String concatenation

? "Visit" + " " + "xHarbour.com" // result: "Visit xHarbour.com" RETURN

(29)

++

Increment operator (unary): prefix / postfix increment.

Syntax

++ <Variable> <Variable> ++

Arguments

<Variable> is the name of a memory or field variable of Numeric or Date data type. When <Variable> is a field variable, it must be specified with an alias name or must be declared as field variable using theFIELDstatement.

Description

The increment operator increases the value of its operand by one. When used in an expression, the position of the operator is important for the result of the expression.

When the operator appears to the left of the operand (prefix notation), the operand's value is first incremented and then used in the expression.

When the operator appears to the right of the operand (postfix notation), the operand's value is first used in the expression and then incremented.

Info

See also: +,--,:=,= (compound assignment)

LIB: xhb.lib

DLL: xhbdll.dll

Example

// The example demonstrates the use of the ++ operator and // outlines the importance of prefix and postfix notation. PROCEDURE Main LOCAL nValue1 := 0 LOCAL nValue2 ? nValue1 ++ // result: 0 ? nValue1 // result: 1 ? ++ nValue1 // result: 2 ? nValue1 // result: 2 nValue2 := ++ nValue1 ? nValue1 // result: 3 ? nvalue2 // result: 3 nValue2 := nValue1 ++ ? nValue1 // result: 4 ? nvalue2 // result: 3

(30)

-Minus operator: add values, concatenate values and unary negative.

Syntax

Arguments

<nNumber1> is a numeric value from which the value of <nNumber2> is subtracted. <dDate1>

<dDate1> is a date value from which the date value <dDate2> is subtracted. <dDate>

<dDate> is a date value from which <nNumber> days are subtracted. <cString2>

<cString2> is a character string to add to the end of <cString1> after all trailing blanks from <cString1> are removed.

Description

Depending on the data types of the operands, the Minus operator performs the following operations:

Unary negative sign

when the Minus operator precedes a numeric operand, it performs the equivalent of multiplying the operand by -1. This changes the operand's sign from plus to minus and vice versa.

Numeric subtraction

When both operands are numeric values, the right operand <nNumber2> is subtracted from the left operand <nNumber1> and the result is a numeric value.

Date subtraction

When the left operand is a date value and the right operand is a numeric, the value of <nNumber> is subtracted as number of days from <dDate>. The returned value is a date.

When both operands are of Date data type, the operator calculates the difference in days between left and right operand and returns a numeric value.

When the left operand is a Numeric value and the right operand is a Date, a runtime error is raised sine this is not allowed.

(31)

-String concatenation

If both operands are character data types, the value of <cString2> is joined to <cString1>, returning a character string. Trailing blanks in <cString1> are removed and appended to the end of the result string.

Hash operation

If both operands are hashes, a set-oriented operation is performed so that the resulting hash value contains unique keys of the left operand which are not contained in the right operand (refer to thehash operator).

Info

See also: %,*,**,+,--,/,= (compound assignment)

Category: Character operators,Mathematical operators,Operators

LIB: xhb.lib

DLL: xhbdll.dll

Example

// The example demonstrates variations with the - operator: PROCEDURE Main

// Unary negative sign (also included is the positive sign) ? 1 - - 1 // result: 2 ? 1 + - 1 // result: 0 ? 1 + + 1 // result: 2 // Subtraction ? CtoD("01/20/2005") - 5 // result: 01/15/2005 ? 10 - 2 // result: 8 // String concatenation

? "A " + "B " + "C " // result: "A B C " ? "A " - "B " - "C " // result: "ABC " RETURN

(32)

--Decrement operator (unary): Prefix / postfix decrement

Syntax

-- <Variable> <Variable>

--Arguments

<Variable> is the name of a memory or field variable of Numeric or Date data type. When <Variable> is a field variable, it must be specified with an alias name or must be declared as field variable using theFIELDstatement.

Description

The decrement operator decreases the value of its operand by one. When used in an expression, the position of the operator is important for the result of the expression.

When the operator appears to the left of the operand (prefix notation), the operand's value is first decremented and then used in the expression.

When the operator appears to the right of the operand (postfix notation), the operand's value is first used in the expression and then decremented.

Info

See also: ++,-,:=,= (compound assignment)

LIB: xhb.lib

DLL: xhbdll.dll

Example

// The example demonstrates the use of the -- operator and // outlines the importance of prefix and postfix notation. PROCEDURE Main LOCAL nValue1 := 0 LOCAL nValue2 ? nValue1 -- // result: 0 ? nValue1 // result: -1 ? -- nValue1 // result: -2 ? nValue1 // result: -2 nValue2 := -- nValue1 ? nValue1 // result: -3 ? nvalue2 // result: -3 nValue2 := nValue1 --? nValue1 // result: -4 ? nvalue2 // result: -3 RETURN

(33)

->

Alias operator (binary): identifies a work area.

Syntax

<aliasName> -> <fieldName> (<nWorkArea>) -> <fieldName> <aliasName> -> ( <expr,...> ) (<nWorkArea>) -> ( <expr,...> ) FIELD -> <fieldName> MEMVAR -> <varName>

Arguments

This is the symbolic alias name of a work area as specified with the ALIAS option of theUSE

command. <fieldName>

The field name whose value is retrieved from the work area specified with <aliasName>. <nWorkArea>

Instead of using a symbolic name, a work area can be identified by its numeric ordinal position <nWorkArea>. This value can be obtained by calling theSelect()function. The numeric work area must be enclosed in parentheses () when using it with the alias operator.

<expr,...>

One or more comma separated expressions to execute in the work area identified with <aliasName> or <nWorkArea>.

FIELD

The FIELD keyword is a reserved alias name that identifies a field variable in the current work area.

MEMVAR

The MEMVAR keyword is a reserved alias name that identifies a memory variable of type PRIVATE or PUBLIC. An abbreviation of this alias is M->.

Description

The alias operator "points" to an unselected work area identified with its symbolic name <aliasName> or its ordinal number <nWorkArea>. This allows for retrieving values of field variables from

unselected work areas or executing expressions in the specified work area. The alias operator implicitly selects the work area specified with the left operand and then executes the instructions of the right operand. When the operation is complete, the original work area becomes current again.

FIELD and MEMVAR are reserved alias names that allow for resolving name conflicts between memory and field variables. If memory and field variables with the same symbolic name exist,

(34)

->

/v. It is, however, strongly recommended to avoid identical variable names for memory and field vraiables, and to use the alias operator to identify a variable unambiguously.

Info

See also: DbSelectArea(),FIELD,FieldName(),FieldPos(),FieldGet(),MEMVAR,Select(),USE

LIB: xhb.lib

DLL: xhbdll.dll

Example

// The example demonstrates usage of the alias operator. // The last aliased expression generates a runtime error.

PROCEDURE Main LOCAL nArea

USE Customer ALIAS Cust // current work area ? FIELD->Lastname // result: Miller nArea := Select() // work area number SELECT 100 // select free work area ? Used() // result: .F.

? Cust->Lastname // result: Miller ? Cust->(Recno()) // result: 1 ? (nArea)->Lastname // result: Miller ? (nArea)->(LastRec()) // result: 1576 ? FIELD->Lastname // runtime error USE

(35)

.AND.

Logical AND operator (binary).

Syntax

Arguments

<lCondition1> and <lCondition2> are logical expressions to AND.

Description

The logical .AND. operator yields the result of a logical AND operation with left and right operand. The result is only .T. (true) when the value of both operands is also .T. (true), in all other cases the result is .F. (false).

When multiple .AND. operators appear in an expression, the result is already determined when one operand has the value .F. (false). In this case, remaining .AND. operators are not evaluated for optimization reasons. This so called shortcut optimization can be switched off using the compiler switch /z.

Info

See also: & (bitwise AND),.OR.,.NOT.

Category: Logical operators,Operators

LIB: xhb.lib

DLL: xhbdll.dll

Example

// This example shows results of .AND. operations // using different operands:

PROCEDURE Main ? .T. .AND. .T. // result: .T. ? .T. .AND. .F. // result: .F. ? .F. .AND. .T. // result: .F. ? .F. .AND. .F. // result: .F. RETURN

(36)

.NOT.

Logical NOT operator (unary).

Syntax

! <lCondition> .NOT. <lCondition>

Arguments

<lCondition> is a logical expression to logically negate.

Description

The .NOT. operator (alternatively "!" as an abbreviation) is a unary logical operator that negates the value of its operand. This yields the logical inverse of <lCondition>.

Info

See also: .AND.,.OR.

LIB: xhb.lib

DLL: xhbdll.dll

Example

// The example shows the logical inverse of the operands: PROCEDURE Main

? .NOT. (.T.) // result: .F. ? .NOT. (.F.) // result: .T. ? ! 1 > 2 // result: .T. RETURN

(37)

.OR.

Logical OR operator (binary).

Syntax

Arguments

<lCondition1> and <lCondition2> are logical expressions.

Description

The logical .OR. operator yields the result of a logical OR operation with left and right operand. The result is only .T. (true) when the value of one operand is also .T. (true), in all other cases the result is .F. (false).

When multiple .OR. operators appear in an expression, the result is already determined when one operand has the value .T. (true). In this case, remaining .OR. operators are not evaluated for optimization reasons. This so called shortcut optimization can be switched off using the compiler switch /z.

Info

See also: .AND.,.NOT.,| (bitwise OR)

LIB: xhb.lib

DLL: xhbdll.dll

Example

// This example shows results of .OR. operations // using different operands:

PROCEDURE Main ? .T. .OR. .T. // result: .T. ? .T. .OR. .F. // result: .T. ? .F. .OR. .T. // result: .T. ? .F. .OR. .F. // result: .F. RETURN

(38)

/

Division operator (binary): divides numeric values.

Syntax

Arguments

<nNumber1> is the dividend. <nNumber2>

<nNumber2> is the divisor.

Description

This operator returns the division of <nNumber1> by <nNumber2> as a numeric value.

Info

See also: %

LIB: xhb.lib

DLL: xhbdll.dll

Example

// The example shows the use of the "/" operator: PROCEDURE Main ? 3 / 3 // result: 1 ? 3 /-2 // result: -1.50 ? -3 / 2 // result: -1.50 ? -3 /-2 // result: 1.50 ? 3 / 0 // result: 0 RETURN

(39)

:

Send operator (unary): sends a message to an object.

Syntax

Arguments

<object> is a variable holding an object to which the message is sent. <message>

<message> is the name of an instance variable or method. When a method is called on the object, the message name must be followed with parentheses.

<params,...>

<params,...> is an optional comma separated list of parameters passed to a method.

Description

A class defines instance variables and methods for its objects. Accessing an object's instance variable or executing one of its methods requires the object to receive a corresponding message. This is the task of the Send operator (:).

To access an instance variable, the message is sent without following parentheses. As a result, the object returns the value of the instance variable that corresponds to the message.

Methods, in contrast, are invoked by adding parentheses to the message and passing an optional list of parameters to the method. Parameters are listed inside the parentheses.

The double send operator :: has a special meaning within the context of the program code of methods. It is an abbreviation for self:, i.e. :: sends messages to the object that executes a method.

Note that only messages are understood by an object that are declared in the object's class. In addition, only those instance variables and methods are accessible that are visible in the current program context. If either an instance variable/method is not declared or currently not visible, the message is not

understood by the object and a runtime error is generated.

Info

See also: CLASS,DATA,METHOD (Implementation)

Header: hbclass.ch

LIB: xhb.lib

DLL: xhbdll.dll

Example

// The example demonstrates the use of the single and // double send operator. Note that the double send operator // is only used within the program code of a method.

(40)

:

PROCEDURE Main

LOCAL obj := MyClass():new( "Hello World" )

obj:display() // shows: Hello World obj:value := "Hi there"

obj:display() // shows: Hi there RETURN

CLASS MyClass EXPORTED: DATA value

METHOD new( cString ) CONSTRUCTOR METHOD display

ENDCLASS

METHOD new( cString ) CLASS MyClass ::value := cString

RETURN self

METHOD display CLASS MyClass ? ::value

(41)

:=

Inline assignment to a variable.

Syntax

Arguments

<Variable> is the name of a variable of any type. <Expression>

<Expression> is any valid expression whose result is assigned to <Variable>.

Description

The := operator assigns the value of <Expression> to a variable. It is the preferred assignment operator since it can be used to initialize variables within their declaration statements. This is not permitted with the simple assignment operator "=".

If the variable does not exist when the assignment operation is processed, a PRIVATE variable is automatically created and gets assigned the value of <Expression>.

Info

See also: ++,--,= (assignment),= (compound assignment)

Category: Assignment operators

LIB: xhb.lib

DLL: xhbdll.dll

Example

// The example demonstrates the use of the inline assignment // operator in various situations:

PROCEDURE Main

LOCAL dDate := StoD("20050701") // initializes variables LOCAL nMonth := Month( dDate ) // in declaration statement nDay := 12 // creates

nYear := nPreviousYear := 2000 // PRIVATE variables // assignment within expression

IF (nMonth := Month(dDate)) == 7 ? "July"

ENDIF

? nMonth // result: 7 // note the removed parentheses and

// different return value of the expression IF nMonth := Month(dDate) == 7

? "July" ENDIF

(42)

<

Less than operator (binary): compares the size of two values.

Syntax

Arguments

The values of <Expression1> and <Expression2> must have the same data type and are compared.

Description

The "less than" operator compares two values of the same data type. It returns .T. (true) when the left operand is smaller than the right operand, otherwise the return value is .F. (false).

Only the simple data types Character, Date, Logic, Memo and Numeric can be compared. The complex data types Array, Code block, Hash, Object and the value NIL cannot be used with the "less than" operator.

Comparison rules

Data type Comparison

Character The comparison is based on the ASCII value of the characters. Date The comparison is based on the underlying date value. Logical False (.F.) is smaller than true (.T.).

Memo Same as Character data type.

Numeric Comparison is based on the value of the numerics.

SET EXACT

For character comparisons, the less than operator takes the SET EXACT setting into account. With SET EXACT OFF, characters are compared up to the length of the right operand. With SET EXACT ON, characters are compared up to the length of th e left operand and trailing blank spaces are ignored.

Info

See also: $,>,<=,<> != #,= (comparison),==,>=,SET EXACT

Category: Comparison operators,Operators

LIB: xhb.lib

DLL: xhbdll.dll

Example

// The example demonstrates the result of the "<" operator. PROCEDURE Main ? "A" < "Z" // result: .T. ? "a" < "Z" // result: .F. ? CToD("12/28/2005") < CToD("12/31/2005") // result: .T. ? .T. < .F. // result: .F.

(43)

<

? 2 < 1 // result: .F. SET EXACT OFF

? "a" < "a " // result: .T. SET EXACT ON

? "a" < "a " // result: .F. RETURN

(44)

<<

Left-shift operator (binary): shifts bits to the left.

Syntax

Arguments

<nNumber1> is a numeric value whose bits are shifted to the left. <nNumber2>

<nNumber2> is a number indicating how many places the bits are shifted to the left.

Description

The << operator accesses individual bits in the left operand and shifts them to the left as many times as specified with the right operand. Both operands are always treated as integer values. If an operand has a decimal fraction, it is truncated prior to the operation.

A shift operation involves all bits of the left operand. When the bits are shifted one place to the left, the highest bit is discarded and the lowest bit is set to 0. A numeric value has 32 bits on a 32 bit operating system.

Shifting a value to the left is equivalent with multiplying <nNumber1> by 2 raised to the power of <nNumber2>.

Info

See also: >>,HB_BitShift()

Category: Bitwise operators,Operators,xHarbour extensions

LIB: xhb.lib

DLL: xhbdll.dll

Example

// This example shifts the bits of the value 52 two places to // the left so the value becomes 208.

PROCEDURE Main

nValue := 52 // binary: 00110100

? nValue << 2 // binary: 11010000 (value = 208) ? 52 * 2 ^ 2 // result: 208

(45)

<=

Less than or equal operator (binary): compares the size of two values.

Syntax

Arguments

The values of <Expression1> and <Expression2> must have the same data type and are compared.

Description

The "less than or equal" operator compares two values of the same data type. It returns .T. (true) when the left operand is smaller than or equal to the right operand, otherwise the return value is .F. (false). Only the simple data types Character, Data, Logic, Memo and Numeric can be compared. The complex data types Array, Code block, Hash, Object and the value NIL cannot be used with the "less than or equal" operator.

Comparison rules

Data type Comparison

Character The comparison is based on the ASCII value of the characters. Date The comparison is based on the underlying date value. Logical False (.F.) is smaller than true (.T.).

Memo Same as Character data type.

Numeric Comparison is based on the value of the numerics.

SET EXACT

For character comparisons, the "less than or equal" operator takes the SET EXACT setting into account. With SET EXACT OFF, characters are compared up to the length of the right operand. With SET EXACT ON, characters are compared up to the length of the left operand and trailing blank spaces are ignored.

Info

See also: $,<,<> != #,= (comparison),==,>,>=,SET EXACT

Category: Comparison operators,Operators

LIB: xhb.lib

DLL: xhbdll.dll

Example

// The example demonstrates the result of the "<=" operator. PROCEDURE Main

? "A" <= "Z" // result: .T. ? "a" <= "Z" // result: .F.