Clipper is a trademark of Computer Associates and will often be referred to as CA-Cl*pper within Harbour documents. Regardless of this variant, Clipper is recognized as Computer Associates' trademark.

Harbour is a free software compiler for the xBase superset language often referred to as Clipper (the language that is implemented by the compiler Clipper). The goal of Harbour is to produce a cross platform CA-Cl*pper compatible compiler.

The Harbour website is at https://vszakats.github.io/harbour-core/. If you have any problem with this copy of Harbour please visit our web site and ensure that you are using the latest release.

If you are reading this file as part of a source distribution of Harbour you probably want to start by reading doc/dirstruc.txt because this is your map to the Harbour source directories.

Harbour is a superset of Clipper and is backwards compatible with nearly 100% of all Clipper 5.2x or 5.3 code. Most Clipper S'87 code will also compile and run fine, but may require some modifications to run well.

Invoking the Harbour compiler:

or

or

The command-line options have to be separated by at least one space. The option can start with either - character or / character.

The Harbour command-line options:

-a automatic memvar declaration

This causes all variables declared by PARAMETER, PRIVATE or PUBLIC statements to be automatically declared as MEMVAR variables.

The compiler generates all information required for debugging

-es or -es0 - all warnings are ignored and exit status returned

by the compiler is equal to 0 if there are no errors in compiled source file.

-es1 - any warnings generate a non-zero exit status, but

output is still created.

-es2 - all warnings are treated as errors and no output

file is created. The exit status is set to a non-zero value.

-gc[<type>] output type: C source .c (default)

type: 0=compact (default) 1=normal 2=verbose

3=generate real C code

-gh output type: Harbour Portable Object .hrb

-gd[.<destext>] generate dependencies list into .d file

-ge[<mode>] error output mode: 0=Clipper (default)

1=IDE friendly

-kc clear all flags (strict Clipper mode)

-kh Harbour mode (default)

-ko allow operator optimizations

-ki enable support for HB_INLINE (default)

-kr runtime settings enabled

-ks allow indexed assignment on all types

-kx extended Xbase++ mode (default)

-ku strings in user encoding

-kd accept macros with declared symbols

-km turn off macro-text substitution

-kj turn off jump optimization in pcode

-k? this info

The compiler does not generate the source code line numbers in the output file. The ProcLine() function will return 0 for modules compiled using this option.

type: 0=no implicit starting procedure

1=no starting procedure at all 2=add starting procedure if necessary

The compiler does not create a procedure with the same name as the compiled file. This means that any declarations placed before the first PROCEDURE or FUNCTION statement have file- wide scope and can be accessed/used in all functions/procedures defined in the compiled source file. All executable statements placed at the beginning of the file and before the first PROCEDURE/FUNCTION statement are ignored.

The compiler only creates the file that contains the result of pre-processing the source file.

The compiler does not print any messages during compiling (except the copyright info).

-q0 quiet and don't display program header

-q2 disable all output messages

-ql suppress line number information

Currently not supported in Harbour.

This set the maximum number of preprocessor iterations during processing the source code. If this switch is not used then the preprocessor stops after 1024 iterations. This value is used to stop processing of infinite loops, for example: #command ( => (,7

The compiler checks the syntax only. No output file is generated.

Currently not used in Harbour (the Harbour compiler does not create any temporary files).

All undeclared or unaliased variables are assumed MEMVAR variables (private or public variables). If this switch is not used then the scope of such variables is checked at runtime.

-w0 - no warnings

-w or -w1 - CA-Cl*pper compatible warnings

-w2 - some useful warnings missed in CA-Cl*pper

-w3 - warnings generated for Harbour language extensions

and also enables strong type checking but only warns against declared types, or types which may be calculated at compile time

Sets the prefix added to the generated symbol init function name (in C output currently). This function is generated automatically for every PRG module compiled. This additional prefix can be used to suppress problems with duplicated symbols during linking an application with some third party libraries.

Compilation in batch mode.

@file compile list of modules in file

Not supported yet.

Known incompatibilities between Harbour and CA-Cl*pper compilers

Note:

If you want a 100% compatible runtime libraries then you have to define HB_CLP_STRICT, using HB_USER_CFLAGS=-DHB_CLP_STRICT, then rebuild.

Passing an undeclared variable by the reference

The CA-Cl*pper compiler uses the special opcode PUSHP to pass a reference to an undeclared variable (@ operator). The type of passed variable is checked at runtime (field or memvar). However, field variables cannot be passed by reference. This means that CA-Cl*pper checks the memvar variable only and doesn't look for a field. This is the reason why the Harbour compiler uses the usual PUSHMEMVARREF opcode in such cases. Notice that the runtime behavior is the same in CA-Cl*pper and in Harbour - only the generated opcodes are different.

Handling of object messages

The HB_CLP_STRICT setting determines the way chained send messages are handled.

For example, the following code:

a:b( COUNT() ):c += 1

will be handled as:

a:b( COUNT() ):c := a:b( COUNT() ):c + 1

in strict CA-Cl*pper compatibility mode and

temp := a:b( COUNT() ), temp:c += 1

in non-strict mode.

In practice, CA-Cl*pper will call the COUNT() function two times: the first time before addition and the second one after addition. In Harbour, COUNT() will be called only once, before addition.

The Harbour (non-strict) method is:

1) faster

2) it guarantees that the same instance variable of the same object will be changed

(See also: include/hbexpra.c, include/hbexprb.c)

Initialization of static variables

There is a difference in the initialization of static variables that are initialized with a codeblock that refers to a local variable. For example:

The above code compiles fine in CA-Cl*pper, but it generates a runtime error Error/BASE 1132 Bound error: array access Called form (b)STATICS$(0)

In Harbour this code generates a compile time error: Error E0009 Illegal variable (b) initializer: 'MyLocalVar'

Both CA-Cl*pper and Harbour are handling all local variables used in a codeblock in a special way: they are detached from the local stack of function/procedure where they are declared. This allows access to these variables after the exit from a function/procedure. However, all static variables are initialized in a separate procedure (STATICS$ in CA-Cl*pper and (_INITSTATICS) in Harbour) before the main procedure and before all INIT procedures. The local variables don't exist on the eval stack when static variables are initialized, so they cannot be detached.

Invoking the macro compiler:

or

or

Language extensions:

* Class generation and management.

CA-Cl*pper only allowed creation of objects from a few standard classes.

In Harbour, you can create your own classes—complete with Methods, Instance Variables, Class Variables and Inheritance. Entire applications can be designed and coded in Object Oriented style.

* @<FunctionName>()

Returns the pointer (address) to a function.

The returned value is not useful to application-level programming, but is used at a low-level to implement object oriented coding. (Internally, a class method is a static function and there is no symbol for it, so it is accessed via its address).

* Class HBGetList()

Object oriented support for GetLists management.

* ProcName() support for class Method names.

Class Methods can be retrieved from the call stack.

* Memory() has new return values.

See hbmemory.ch

* Transform() → new function in format string

@0 Make a zero padded string out of the number.

* SToD() → dDate

New function that converts a yyyymmdd string to a Date value.

* Optional Compile Time strong type declaration (and compile time

type mismatch warnings)

Example: LOCAL/STATIC Var AS ...

* The Harbour debugger provides new interesting classes:

- Class HBDbWindow() could be the foundation for a generic multi-platform

- Class HBDbInput()

- Class HBDbMenu() implement both pull-down and popup menus.

RTL enhanced functionality:

- hb_vfDirSpace( <nDir>, <nType> )

The second parameter is a Harbour (optional) parameter and indicates the type of disk info being requested. See doc/en/diskspac.txt for info.

The garbage collector uses the following logic: - first collect all memory allocations that can cause garbage; - next scan all variables if these memory blocks are still referenced.

Notice that only arrays, objects and codeblocks are collected because these are the only datatypes that can cause self-references a[ 1 ] := a or circular references a[ 1 ] := b; b[ 1 ] := c; c[ 1 ] := a that cannot be properly deallocated by simple reference counting.

Since all variables in Harbour are stored inside some available tables (the eval stack, memvars table and array of static variables) then checking if the reference is still alive is quite easy and doesn't require any special treatment during memory allocation. Additionally the garbage collector is scanning some internal data used by Harbour objects implementation that also stores some values that can contain memory references. These data are used to initialize class instance variables and are stored in class shared variables.

In special cases when the value of a Harbour variable is stored internally in some static area (at C or assembler level), the garbage collector will be not able to scan such values since it doesn't know their location. This could cause some memory blocks to be released prematurely. To prevent the premature deallocation of such memory blocks the static data have to store a pointer to the value created with hb_itemNew() function. Example:

However, scanning of all variables can be a time consuming operation. It requires that all allocated arrays have to be traversed through all their elements to find more arrays. Also all codeblocks are scanned for detached local variables they are referencing. For this reason, looking for unreferenced memory blocks is performed during the idle states.

The idle state is a state when there is no real application code executed. For example, the user code is stopped for 0.1 of a second during Inkey( 0.1 ) - Harbour is checking the keyboard only during this time. It leaves however quite enough time for many other background tasks. One such background task can be looking for unreferenced memory blocks.

Allocating memory

The garbage collector collects memory blocks allocated with hb_gcAlloc() function calls. Memory allocated by hb_gcAlloc() should be released with hb_gcFree() function.

The garbage collecting

During scanning of unreferenced memory the GC is using a mark & sweep algorithm. This is done in three steps:

1) mark all memory blocks allocated by the GC with unused flag;

2) sweep (scan) all known places and clear unused flag for memory blocks that are referenced there;

3) finalize collecting by deallocation of all memory blocks that are still marked as unused and that are not locked.

To speed things up, the mark step is simplified by swapping the meaning of the unused flag. After deallocation of unused blocks all still alive memory blocks are marked with the same 'used' flag so we can reverse the meaning of this flag to 'unused' state in the next collecting. All new or unlocked memory blocks are automatically marked as 'unused' using the current flag, which assures that all memory blocks are marked with the same flag before the sweep step will start. See hb_gcCollectAll() and hb_gcItemRef()

Calling the garbage collector from Harbour code

The garbage collector can be called directly from the Harbour code. This is useful in situations where there is no idle states available or the application is working in the loop with no user interaction and there is many memory allocations. See hb_gcAll() for explanation of how to call this function from your Harbour code.

The idle state is the state of the Harbour virtual machine when it waits for the user input from the keyboard or the mouse. The idle state is entered during Inkey() calls currently. All applications that don't use Inkey() function call can signal the idle states with the call of hb_idleState() function (or hb_idleState() on C level).

During idle states the virtual machine calls the garbage collector and it can call user defined actions (background tasks). It also releases the CPU time slices for some poor platforms that are not smart enough to detect it automatically.

For defining the background tasks see the hb_idleAdd() and hb_idleDel() functions.

For direct call for background actions see hb_idleState() function.

For signaling the idle state from C code see the hb_idleState() API function.

This function can be called either by the Harbour compiler or by user. The compiler always passes the item of HB_IT_SYMBOL type that stores the name of procedure specified in DO <proc> WITH ... statement.

If called procedure/function doesn't exist then a runtime error is generated.

This function can be used as replacement of macro operator. It is also used internally to implement DO <proc> WITH <args...> In this case xFuncProc is of type HB_SYMB.

This function dynamically increases the length of the aArray by adding one new element to the end of the array and optionally stores the value xValue to that newly created element.

xValue may be of an data type, including an array reference pointer, which in turn may be stored to an array's subscript position.

This function copies array elements from aSource to aTarget. nStart is the beginning element to be copied from aSource; the default is 1.

nCount is the number of elements to be copied from aSource; the default is the entire array. nTargetPos is the subscript number in the target array, aTarget, to which array elements are to be copied; the default is 1.

This function will copy all data types in aSource to aTarget. If an array element in aSource is a pointer reference to another array, that array pointer will be copied to aTarget; not all subdimensions will be copied from one array to the next. This must be accomplished via the AClone() function.

Note: If array aSource is larger then aTarget, array elements will start copying at nTargetPos and continue copying until the end of array aTarget is reached. The ACopy() function doesn't append subscript positions to the target array, the size of the target array aTarget remains constant.

This function deletes the element found at nPos subscript position in the array aArray. All elements in the array aArray below the given subscript position nPos will move up one position in the array.

In other words, what was formerly the sixth subscript position will become the fifth subscript position. The length of the array aArray will remain unchanged, as the last element in the array will become a NIL data type.

Note: To completely remove an element and decrease the length of array you can use hb_ADel() that supports auto-sizing.

This function evaluates the elements of aArray, and executes for each of them the processing that's defined with bBlock. By default, all the elements of array are being processed, starting from 1st and up to the last element.

If nStart and/or nCount parameters are given, then the processing starts from nStart element and continues for the next nCount elements (if defined) or up to the last element of the array.

The bBlock code block receives two parameters: the element value and element's index (position) into the array. i.e. {| xValue, nIndex | ... } Worth to note that elements are passed to code block 'by value', thus any change being made to this value doesn't affects the value of element in the array.

This function will fill each element of an array named aArray with the value xValue. If specified, nStart denotes the beginning element to be filled and the array elements will continue to be filled for nCount positions.

If neither nStart/nCount specified, the value of nStart will be 1, and the value of nCount will be the value of Len( <aArray> ); thus, all subscript positions in the array aArray will be filled with the value of xValue.

This function will work on only a single dimension of aArray. If there are array pointer references within a subscript aArray, those values will be lost, since this function will overwrite those values with new values.

This function inserts a NIL value in the array named aArray at the nPosth position.

All array elements starting with the nPosth position will be shifted down one subscript position in the array list and the last item in the array will be removed completely. In other words, if an array element were to be inserted at the fifth subscript position, the element previously in the fifth position would now be located at the sixth position. The length of the array aArray will remain unchanged.

Note: To avoid loosing last element, you can use hb_AIns() which supports auto-sizing of array.

This function returns an uninitialized array with the length of nElements.

Nested arrays are uninitialized within the same array pointer reference if additional parameters are specified.

Establishing a memory variable with the same name as the array may destroy the original array and release the entire contents of the array. This depends, of course, on the data storage type of either the array or the variable with the same name as the array.

CA-Cl*pper v5.x compliant except that arrays in Harbour can have an unlimited number of elements.

This function scan the content of array named aArray for the value of xSearch. The return value is the position in the array aArray in which xSearch was found. If it was not found, the return value will be 0.

nStart is the position from which to start scanning. The default is 1. (1st element) nCount, if specified, is the number of array elements to be scanned. The default is all elements in the array aArray.

If xSearch is a code block, the operation of the function is slightly different. Each array subscript pointer reference is passed to the code block to be evaluated. The scanning routine will continue until the value obtained from the code block is a logical true (.T.) or until the end of the array has been reached.

This function will dynamically increase or decrease the size of aArray by adjusting the length of the array to nLen subscript positions.

If the length of the array aArray is shortened, the redundant elements are removed from the end of array. If the length of the array is lengthened the new elements are added to the end of array and they are assigned a NIL value.

ASort() sort all or part of a given array. If bSort is omitted, the function expect aArray to be one dimensional array containing single data type (one of: Character, Date, Logical, Numeric) and sort this array in ascending order: Character are sorted by their ASCII value, Dates are sorted chronologically, Logical put .F. values before .T., Numeric are sorted by their value. If bSort is specified, it is used to handle the sorting order. With each time the block is evaluate, two array elements are passed to the code block, and bSort must return a logical value that state if those elements are in order (.T.) or not (.F.). Using this block you can sort multidimensional array, descending orders or even (but why would you want to do that) sort array that contain different data type.

Codeblock calling frequency and order differs from CA-Cl*pper, since Harbour uses a different (faster) sorting algorithm (quicksort).

This function deletes the element value (not the element itself!) stored in position nPos and shifts all the following values, one position up.

If lAutoSize is .T., then the last element is removed and the size of the array is decreased by one, otherwise the length of the array remains unchanged and a NIL value will be stored in the last element, just like in ADel().

This function inserts xValue in the nPos position of the array, moving all the items one position down in the array list. If lAutoSize is .T., a new element will be added at the end of array, making room for the previous last element, which means the length of array will be increased by 1.

If lAutoSize is .F. (or is not passed) the function behaves like AIns(), that is, the size of aArray won't change and the last item of aArray will be lost.

The function scans (left to right) for xSearch into aArray and returns nPosition of aArray in which xSearch was found or 0 (zero) if nothing found.

If lExact is .T., then an exact search will be performed. When xSearch is a code block, the operation of the function is slightly different. See AScan() for details.

HBClass() is a class that ... The class methods are as follows:

:New() Create a new instance of the class

Bin2I() is one of the low-level binary conversion functions, those functions convert between Harbour numeric and a character representation of numeric value. Bin2I() take two bytes of encoded 16-bit signed short integer and convert it into standard Harbour numeric value.

You might ask what is the need for such functions, well, first of all it allow you to read/write information from/to a binary file (like extracting information from DBF header), it is also a useful way to share information from source other than Harbour (C for instance).

Bin2I() is the opposite of I2Bin()

Bin2L() is one of the low-level binary conversion functions, those functions convert between Harbour numeric and a character representation of numeric value. Bin2L() take four bytes of encoded 32-bit signed long integer and convert it into standard Harbour numeric value.

You might ask what is the need for such functions, well, first of all it allow you to read/write information from/to a binary file (like extracting information from DBF header), it is also a useful way to share information from source other than Harbour (C for instance).

Bin2L() is the opposite of L2Bin()

Bin2W() is one of the low-level binary conversion functions, those functions convert between Harbour numeric and a character representation of numeric value. Bin2W() take two bytes of encoded 16-bit unsigned short integer and convert it into standard Harbour numeric value.

You might ask what is the need for such functions, well, first of all it allow you to read/write information from/to a binary file (like extracting information from DBF header), it is also a useful way to share information from source other than Harbour (C for instance).

Bin2W() is the opposite of W2Bin()

I2Bin() is one of the low-level binary conversion functions, those functions convert between Harbour numeric and a character representation of numeric value. I2Bin() take a numeric integer value and convert it into two bytes of encoded 16-bit signed short integer.

You might ask what is the need for such functions, well, first of all it allow you to read/write information from/to a binary file (like extracting information from DBF header), it is also a useful way to share information from source other than Harbour (C for instance).

I2Bin() is the opposite of Bin2I()

L2Bin() is one of the low-level binary conversion functions, those functions convert between Harbour numeric and a character representation of numeric value. L2Bin() take a numeric integer value and convert it into four bytes of encoded 32-bit signed long integer.

You might ask what is the need for such functions, well, first of all it allow you to read/write information from/to a binary file (like extracting information from DBF header), it is also a useful way to share information from source other than Harbour (C for instance).

L2Bin() is the opposite of Bin2L()

__dbCopyStruct() create a new empty database file with a structure that is based on the currently open database in this work-area. If aFieldList is empty, the newly created file would have the same structure as the currently open database. Else, the new file would contain only fields that exactly match aFieldList.

__dbCopyStruct() can be use to create a sub-set of the currently open database, based on a given field list.

COPY STRUCTURE command is preprocessed into __dbCopyStruct() function during compile time.

__dbCopyXStruct() create a new database named cFileName with a pre-defined structure (also called "structure extended file"):

Each record in the new file contains information about one field in the original file. CREATE FROM could be used to create a database from the structure extended file.

For prehistoric compatibility reasons, Character fields which are longer than 255 characters are treated in a special way by writing part of the length in the FIELD_DEC according to the following formula (this is done internally):

Later if you want to calculate the length of a field you can use the following formula:

COPY STRUCTURE EXTENDED command is preprocessed into __dbCopyXStruct() function during compile time.

__dbCreate() works in two modes depending on the value of cFileFrom:

1) If cFileFrom is empty or not specified a new empty structure extended file with the name cFileName is created and then opened in the current work-area (lNew is ignored). The new file has the following structure:

The CREATE command is preprocessed into the __dbCopyStruct() function during compile time and uses this mode.

2) If cFileFrom is specified, it is opened and assumed to be a structure extended file where each record contains at least the following fields (in no particular order): FIELD_NAME, FIELD_TYPE, FIELD_LEN and FIELD_DEC. Any other field is ignored. From this information the file cFileName is then created and opened in the current or new work-area (according to lNew), if this is a new work-area it becomes the current.

For prehistoric compatibility reasons, structure extended file Character fields which are longer than 255 characters should be treated in a special way by writing part of the length in the FIELD_DEC according to the following formula:

CREATE FROM command is preprocessed into __dbCopyStruct() function during compile time and use this mode.

__dbStructFilter() can be use to create a sub-set of a database structure, based on a given field list.

Note that field names in aStruct must be specified in uppercase or else no match would be found.

SET EXACT has no effect on the return value.

__FLedit() can be use to create a sub-set of a database structure, based on a given field list.

Note that field names in aStruct must be specified in uppercase or else no match would be found.

SET EXACT has no effect on the return value.

__FLedit() is a compatibility function and it is synonym for __dbStructFilter() which does exactly the same.

This function will fill a series of arrays with field names, field types, field lengths, and number of field decimal positions for the currently selected or designed database. Each array parallels the different descriptors of a file's structure. The first array will consist of the names of the fields in the current work area. All other arrays are optional and will be filled with the corresponding data. This function will return zero if no parameters are specified or if no database is available in the current work area. Otherwise, the number of fields or the length of the shortest array argument, whichever is smaller, will be returned.

AFields() is a compatibility function, it is superseded by dbStruct() which returns one multidimensional array.

NOTE: The destination arrays must be initialized to a given size,

usually FCount(), before calling this function.

This function add a new record to the end of the database in the selected or aliased work area. All fields in that database will be given empty data values - character fields will be filled with blank spaces, date fields with hb_SToD(), numeric fields with 0, logical fields with .F., and memo fields with NULL bytes. The header of the database is not updated until the record is flushed from the buffer and the contents are written to the disk.

Under a networking environment, dbAppend() performs an additional operation: It attempts to lock the newly added record. If the database file is currently locked or if a locking assignment is made to LastRec() + 1, NetErr() will return a logical true (.T.) immediately after the dbAppend() function. This function does not unlock the locked records.

If lLock is passed a logical true (.T.) value, it will release the record locks, which allows the application to maintain multiple record locks during an appending operation. The default for this parameter is a logical false (.F.).

This function creates the database file specified as cDatabase from the multidimensional array aStruct. If no file extension is use with cDatabase the .dbf extension is assumed. The array specified in aStruct must follow a few guidelines when being built prior to a call to dbCreate():

- All subscripts values in the second dimension must be set to proper values

- The fourth subscript value in the second dimension - which contains

the decimal value-must he specified. even 1kw non-numeric fields.

- The second subscript value in the second dimension-which contains

the field data type-must contain a proper value: C, D, L, M or N It is possible to use additional letters for clarity (e.g., 'Numeric' for 'N'): however, the first letter of this array element must be a proper value.

The dbCreate() function does not use the decimal field to calculate the length of a character held longer than 256. Values up to the maximum length of a character field (which is 65519 bytes) are stored directly in the database in the length attribute if that database was created via this function. However, a file containing fields longer than 256 bytes is not compatible with any interpreter.

The cRDD parameter specifies the name of the Replaceable Database Driver to use to create the database. If it is not specified, then the Replaceable Database Driver in the current work area is used.

The lKeepOpen parameter specifies if the already created database is to be opened, and where. If NIL, the file is not opened. If True, it is opened in a New area, and if False it is opened in the current area (closing any file already occupying that area). The cAlias parameter specifies the alias name for the new opened database.

This function marks a record for deletion in the selected or aliased work area. If the DELETED setting is on, the record will still be visible until the record pointer in that work area is moved to another record.

In a networking situation, this function requires that the record be locked prior to issuing the dbDelete() function.

This function places the record pointer, if working with a .dbf file, in selected or aliased work area at the record number specified by xRecordNumber. The position is not affected by an active index or by any environmental SET condition.

The parameter xRecordNumber may be something other than a record number. In some data formats, for example, the value of xRecordNumber is a unique primary key while in other formats, xRecordNumber could be an array offset if the data set was an array.

Issuing a dbGoto( RecNo() ) call in a network environment will refresh the database and index buffers. This is the same as a dbSkip( 0 ) call.

This function searches for the first record in a database file whose index key matches expKey. If the item is found, the function will return a logical true (.T.), the value of Found() will be a logical true (.T.), and the value of Eof() will be a logical false (.F.). If no item is found. then the function will return a logical false, the value of Found() will be a logical false (.F.), and the value of Eof() will be a logical true (.T.).

This function always "rewinds" the database pointer and starts the search from the top of the file.

If the SOFTSEEK flag is on or if lSoftSeek is set to a logical true (.T.) the value of Found() will be a logical false and Eof() will be false if there is an item in the index key with a greater value than the key expression expKey; at this point the record pointer will position itself on that record. However, if there is no greater key in the index, Eof() will return a logical true (.T.) value. If lSoftSeek is not passed, the function will look to the internal status of SOFTSEEK before performing the operation. The default of lSoftSeek is a logical false (.F.)

This function moves the Harbour internal primary focus to the work area designated by xArea. If xArea is numeric, then it will select the numeric work area; if xArea is character, then it will select the work area with the alias name.

dbSelectArea( 0 ) will select the next available and unused work area. Up to 65534 work areas are supported. Each work area has its own alias and record pointer, as well as its own Found(), dbFilter(), dbRSelect() and dbRelation() function values.

This function opens an existing database named cName in the current work area. If lNewArea is set to a logical true (.T.) value, then the database cName will be opened in the next available and unused work area. The default value of lNewArea is a logical false (.F.). If used, cDriver is the name of the database driver associated with the file cName that is opened. The default for this will be the value of dbSetDriver().

If used, xcAlias contains the alias name for that work area, If not specified, the root name of the database specified in cName will be used.

If lShared is set to a logical true (.T.) value, the database that is specified in cName will be opened by the user exclusively. Thus locking it from all other nodes or users on the network. If lShared is set to a logical false (.F.) value, then the database will be in SHARED mode. If lShared is not passed, then the function will turn to the internal setting of SET EXCLUSIVE to determine a setting.

If lReadOnly is specified, the file will be set to read only mode. If it is not specified, the file will he opened in normal read-write mode.

This function returns the number of bytes in the header of the selected database of the database in the designated work area.

If used in conjunction with the LastRec(), RecSize() and DiskSpace() functions, this functions is capable of implementing a backup and restore routine.

This function returns a character string stored in the header of the index file

The index key is displayed for an index file that is designated by nOrder, its position in the USE...INDEX or SET INDEX TO command in the currently selected or designated work area. If there is no corresnponding index key at the specified order position, a NULL byte will be returned.

This function return th character name of the RDD extension for the order bag. This is determined by the active RDD for the selected work area.

This function replaces the IndexOrd() function.

This function creates an order for the current work area. It is similar to the dbCreateIndex() except that this function allows different orders based on the RDD in effect. The name of the file cOrderBagName or the name of the order cOrderName are technically both considered to be "optional" except that at least one of two must exist in order to create the order.

The parameter cExpKey is the index key expression; typically in a .dbf driver, the maximum length of the key is 255 characters.

If bExpKey is not specified, then the code block is create by macro expanding the value of cExpKey.

If lUnique is not specified, then the current internal setting of SET UNIQUE ON or OFF will be observed.

The active RDD driver determines the capacity in the order for a specific order bag.

If the name cOrderBagName is found in the order bag can contain a single order, the the name cOrderBagName is erased and a new order is added to the order list in the current or specified work area.On the other hand, if it can contain multiples tags and if cOrderBagName does not already exist in the order list, then it is added. It is does exist, then the cOrderBagName replaces the former name in the order list in the current or specified work area.

This function attempts to remove the order named cOrderName from the file containing the order bag name cOrderBagName. If cOrderBagName is not specified, then the name of the file will be based on the value of the ordName() function. If the extension is not included with the name of the order file, then the extension will be obtained from the default extension of the current and active RDD.

The DBFNTX driver do not support multiple order bags; therefore, there cannot be an order to "destroy" from a bag. This function only works for those drivers with support multiple orders bags (e.q. DBFCDX and RDDADS drivers).

This function returns the position of the record pointer in the currently selected of designated work area.

If the database file is empty and if the RDD is the traditional .dbf file, the value of this function will be 1.

This function returns a logical true (.T.) if an attempt to lock a specific record in a selected or designated work area is successful. It will yield a false (.F.) if either the file or the desired record is currently locked. A record that is locked remains locked until another RLock() is issued or until an UNLOCK command is executed. On a Network environment the follow command need that the record is locked:

@...GET

DELETE (single record)

RECALL (single record)

REPLACE (single record)

This function returns the week number of year for the given dDate. The returned value is an ISO 8601 compliant week number. Optionally, can also be obtained the year and/or the day number of the week of the given dDate, if the nYear and/or nDayOfWeek parameters have been passed by reference. If dDate is an empty date expression, the function returns zero(s). Note: new function available after 2017-02-08 19:36 UTC+0100 commit,

not found in earlier versions.

This command runs an external program. Ensure that you have enough free memory to be able to run the external program. Do not use it to run 'Terminate and Stay Resident' programs (in case of MS-DOS) since that causes several problems.

Note: This function is what the RUN command preprocesses into.

It is considered bad form to use this function directly. Use the RUN command instead.

This function yields a string that is the value of the environment variable cEnviroment, which is stored at the system-level.

If no environment variable is found, an empty string is returned.

This function yields a string that is the value of the environment variable cEnviroment, which is stored at the system-level.

If no environment variable is found, an empty string is returned.

Returns a character string containing the character or characters required to move the screen cursor or print head to the start of a new line for the operating system that the program is running on (or thinks it is running on, if an OS emulator is being used).

Under HB_OS_UNIX operating system the return value is the Line-Feed character (0x0a, Chr( 10 ) ); with other operating systems (like DOS) the return value is the Carriage-Return plus Line-Feed characters (0x0d 0x0a, Chr( 13 ) + Chr( 10 )).

This function yields a string that is the value of the environment variable cEnviroment, which is stored at the system-level.

If no environment variable can be found, the value of the function will be cDefaultValue if it is passed, else an empty string.

SetMode() is a function that change the video mode depend on the video card and monitor combination, to match the number of rows and columns specified. Note that there are only a real few combination or rows/cols pairs that produce the video mode change. The followings are available for GTDOS:

The follow modes are available to Windows

Some modes only are available for color and/or VGA monitors. Any change produced on the screen size is updated in the values returned by MaxRow() and MaxCol().

__SetFunction() assign a character string with a function key, when this function key is pressed, the keyboard is stuffed with this character string. __SetFunction() has the effect of clearing any SetKey() previously set to the same function number and vice versa.

SET FUNCTION command is preprocessed into __SetFunction() function during compile time.

This function evaluates the code bloc expressed as bBlock and returns its evaluated value. If their are multiple expressions within the code block, the last expression will be value of this function.

If the code block requires parameters to be passed to it, they are specified in the parameter list xVal and following. Each parameter is separated by a comma within the expression list.

If no cFileMask is given, __Dir() displays information about all *.dbf in the SET DEFAULT path. This information contains: file name, number of records, last update date and the size of each file.

If cFileMask is given, __Dir() list all files that match the mask with the following details: Name, Extension, Size, Date.

DIR command is preprocessed into __Dir() function during compile time.

__Dir() is a compatibility function, it is superseded by Directory() which return all the information in a multidimensional array.

If long file names are available Harbour will use/display the first 15 characters else Harbour will use/display a 8.3 file name consistent with CA-Cl*pper.

ADir() return the number of files and/or directories that match a specified skeleton, it also fill a series of given arrays with the name, size, date, time and attribute of those files. The passed arrays should pre-initialized to the proper size, see example below. In order to include hidden, system or directories aAttr must be specified.

ADir() is a compatibility function, it is superseded by Directory() which returns all the information in a multidimensional array.

This function yields the name of the current OS directory on a specified drive. If cDrive is not specified, the currently logged drive will be used.

This function should not return the leading and trailing (back)slashes.

If an error has been detected by the function, or the current OS directory is the root, the value of the function will be a NULL byte.