Harbour Reference Guide - Command

Command

Database

COPY STRUCTURE

Create a new database based on current database structure
Syntax
COPY STRUCTURE TO <xcFileName> [FIELDS <field,...>]
Argument(s)
<b>TO <xcFileName></b> is the name of the new database file to create. (.dbf) is the default extension if none is given. It can be specified as a literal file name or as a character expression enclosed in parentheses.
<b>FIELDS <field,...></b> is an optional list of field names to copy from the currently open database in the specified order, the default is all fields. Names could be specified as uppercase or lowercase.
Description
COPY STRUCTURE create a new empty database file with a structure that is based on the currently open database in this work-area.
COPY STRUCTURE 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.
Example(s)
// Create a new file that contains the same structure
USE TEST
COPY STRUCTURE TO MyCopy
// Create a new file that contains part of the original structure
USE TEST
COPY STRUCTURE TO SomePart FIELDS name, address
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
Platform(s)
This is available on all platforms
See also
COPY STRUCTURE EXTENDED,DBCREATE(),DBSTRUCT(),__dbCopyStruct(), __dbCopyXStruct(),__dbCreate(),__dbStructFilter()
Index
Command

COPY STRUCTURE EXTENDED

Copy current database structure into a definition file
Syntax
COPY STRUCTURE EXTENDED TO <xcFileName>
Argument(s)
<xcFileName> The name of the target definition file to create. (.dbf) is the default extension if none is given. It can be specified as a literal file name or as a character expression enclosed in parentheses.
Description
COPY STRUCTURE EXTENDED create a new database named <cFileName> with a pre-defined structure (also called "structure extended file"):

Field name Type Length Decimals
FIELD_NAME C 10 0
FIELD_TYPE C 1 0
FIELD_LEN N 3 0
FIELD_DEC N 3 0

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):
<fixed> FIELD->FIELD_DEC := int( nLength / 256 ) FIELD->FIELD_LEN := ( nLength % 256 ) </fixed>
Later if you want to calculate the length of a field you can use the following formula:
<fixed> nLength := IIF( FIELD->FIELD_TYPE == "C", ;
FIELD->FIELD_DEC * 256 + FIELD->FIELD_LEN, ; FIELD->FIELD_LEN )
</fixed>
COPY STRUCTURE EXTENDED command is preprocessed into __dbCopyXStruct() function during compile time.
Example(s)
// Open a database, then copy its structure to a new file,
// Open the new file and list all its records
USE Test
COPY STRUCTURE EXTENDED TO TestStru
USE TestStru
LIST
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
Platform(s)
This is available on all platforms
See also
COPY STRUCTURE,CREATE,CREATE FROM,DBCREATE(),DBSTRUCT(), __dbCopyStruct(),__dbCopyXStruct(),__dbCreate()
Index
Command

CREATE

Create empty structure extended file
Syntax
CREATE <xcFileName> [VIA <xcRDDName>] [ALIAS <xcAlias>]
Argument(s)
<xcFileName> is the target file name to create and then open. (.dbf) is the default extension if none is given. It can be specified as literal file name or as a character expression enclosed in parentheses.
<b>VIA <xcRDDName></b> is RDD name to create target with. If omitted, the default RDD is used. It can be specified as literal name or as a character expression enclosed in parentheses.
<b>ALIAS <xcAlias></b> is an optional alias to USE the target file with. If not specified, alias is based on the root name of <xcFileName>.
Description
CREATE a new empty structure extended file with the name <cFileName> and then open it in the current work-area. The new file has the following structure:

Field name Type Length Decimals
FIELD_NAME C 10 0
FIELD_TYPE C 1 0
FIELD_LEN N 3 0
FIELD_DEC N 3 0

CREATE command is preprocessed into __dbCopyStruct() function during compile time and use this mode.
Example(s)
// CREATE a new structure extended file, append some records and
// then CREATE FROM this file a new database file
CREATE template
APPEND BLANK
FIELD->FIELD_NAME := "CHANNEL"
FIELD->FIELD_TYPE := "N"
FIELD->FIELD_LEN  := 2
FIELD->FIELD_DEC  := 0
APPEND BLANK
FIELD->FIELD_NAME := "PROGRAM"
FIELD->FIELD_TYPE := "C"
FIELD->FIELD_LEN  := 20
FIELD->FIELD_DEC  := 0
APPEND BLANK
FIELD->FIELD_NAME := "REVIEW"
FIELD->FIELD_TYPE := "C"      // this field is 1000 char long
FIELD->FIELD_LEN  := 232      // 1000 % 256 = 232
FIELD->FIELD_DEC  := 3        // 1000 / 256 = 3
CLOSE
CREATE TV_Guide FROM template
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
Platform(s)
This is available on all platforms
See also
COPY STRUCTURE,COPY STRUCTURE EXTENDED,CREATE FROM,DBCREATE(), DBSTRUCT(),__dbCopyStruct(),__dbCopyXStruct(),__dbCreate()
Index
Command

CREATE FROM

Create new database file from a structure extended file
Syntax
CREATE <xcFileName> FROM <xcFileFrom> [VIA <xcRDDName>] [NEW] [ALIAS <xcAlias>]
Argument(s)
<xcFileName> is the target file name to create and then open. (.dbf) is the default extension if none is given. It can be specified as literal file name or as a character expression enclosed in parentheses.
<b>FROM <xcFileFrom></b> is a structure extended file name from which the target file <xcFileName> is going to be built. It can be specified as literal file name or as a character expression enclosed in parentheses.
<b>VIA <xcRDDName></b> is RDD name to create target with. If omitted, the default RDD is used. It can be specified as literal name or as a character expression enclosed in parentheses.
<b>NEW</b> open the target file name <xcFileName> in the next available unused work-area and making it the current work-area. If omitted open the target file in current work-area.
<b>ALIAS <xcAlias></b> is an optional alias to USE the target file with. If not specified, alias is based on the root name of <xcFileName>.
Description
CREATE FROM open a structure extended file <xcFileFrom> where each record contain 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 <xcFileName> is then created and opened in the current or new work-area (according to the NEW clause), 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:
<fixed> FIELD->FIELD_DEC := int( nLength / 256 ) FIELD->FIELD_LEN := ( nLength % 256 ) </fixed>
CREATE FROM command is preprocessed into __dbCopyStruct() function during compile time and uses this mode.
Example(s)
See example in the CREATE command
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
Platform(s)
This is available on all platforms
See also
COPY STRUCTURE,COPY STRUCTURE EXTENDED,CREATE,DBCREATE(),DBSTRUCT(), __dbCopyStruct(),__dbCopyXStruct(),__dbCreate()
Index
Command

PACK

Remove records marked for deletion from a database
Syntax
PACK
Argument(s)
(This command has no arguments)
Description
This command removes records that were marked for deletion from the currently selected database. This command does not pack the contents of a memo field; those files must be packed via low-level fuctions.
All open index files will be automatically reindexed once PACK command has completed its operation. On completion, the record pointer is placed on the first record in the database.
Example(s)
USE Tests NEW index Tests
DBGOTO(10)
DELETE NEXT 10
PACK
USE
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
See also
DBEVAL(), DELETE, DELETED(), ZAP, RECALL
Index
Command

ZAP

Remove all records from the current database file
Syntax
ZAP
Argument(s)
(This command has no arguments)
Description
This command removes all of the records from the database in the current work area. This operation also updates any index file in use at the time of this operation. In addition, this command removes all items within an associated memo file. In a network enviroment, any file that is about to be ZAPped must be used exclusively.
Example(s)
USE Tests NEW index Tests
ZAP
USE
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
See also
DELETE,PACK,USE
Index
Command

Environment

SET ALTERNATE

Toggle and echos output to an alternate file
Syntax
SET ALTERNATE to <cFile> [ADDITIVE] SET ALTERNATE on | OFF | (<lAlter>)
Argument(s)
<cFile> Name of alternate file.
<lAlter> Logical expression for toggle
Description
This command toggles and output console information to the alternate file <cFile>, provided that the command is toggled on or the condition <lAlter> is set to a logical true (.T.). If <cFile> does not has a file extension, .txt will be assumed. The file name may optionally have a drive letter and/or directory path. If none is speficied, the current drive and directory will be used. If the ALTERNATE file is created but no ALTERNATE ON command is issued, nothing will be echoed to the file. If ADDITIVE clause is used, then the information will be appended to the existing alternate file. Otherwise, a new file will be created with the specified name (or an existing one will be overwritten) and the information will be appended to the file. The default is to create a new file. A SET ALTERNATE TO command will close the alternate file
Example(s)
SET ALTERNATE TO test.txt
SET ALTERNATE ON
? 'Harbour'
? "is"
? "Power"
SET ALTERNATE TO
SET ALTERNATE OFF
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
See also
CLOSE,SET PRINTER,SET CONSOLE,SET()
Index
Command

SET BELL

Toggle the bell to sound once a GET has been completed.
Syntax
SET BELL on | OFF | (<lBell>)
Argument(s)
<lBell> Logical expression for toggle command
Description
This command toggles the bell to sound whenever a character is entered into the last character positionof a GET, or if an invalid data type is entered into a GET.
If <lBell> is a logical true (.T.), the bell will be turned ON; otherwise, the bell will be turned off.
Example(s)
SET BELL ON
cDummy:=space(20)
@ 3,2 get cDummy
Read
SET bell off
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
See also
SET()
Index
Command

SET CENTURY

Toggle the century digits in all dates display
Syntax
SET CENTURY on | OFF | (<lCent>)
Argument(s)
<lCent> Logical expression for toggle
Description
This command allows the input and display of dates with the century prefix. It will be in the standart MM/DD/YYYY format unless specified by the SET DATE command or SET() function. If <lCent> is a logical true (.T.), the command will be set on; otherwise, the command will be set off
Example(s)
SET CENTURY ON
? DATE()
SET CENTURY OFF
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
See also
SET DATE,SET EPOCH,CTOD(),DATE(),DTOC(),SET()
Index
Command

SET CONSOLE

Toggle the console display
Syntax
SET CONSOLE ON | off | (<lConsole>)
Argument(s)
<lConsole> Logical expression for toggle command
Description
This command turns the screen display either off or on for all screens display other then direct output via the @...SAY commands or the <-> DEVOUT() function.
If <lConsole> is a logical true (.T.),the console will be turned ON; otherwise, the console will be turned off.
Example(s)
SET console on
? DATE()
SET console off
? date()
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
See also
SET DEVICE,SET()
Index
Command

SET DATE

Assigns a date format or chooses a predefined date data set.
Syntax
SET DATE FORMAT [TO] <cFormat>
SET DATE [TO] [ANSI / BRITISH / FRENCH / GERMAN / ITALIAN / JAPAN / USA / AMERICAN]
Argument(s)
<cFormat> Keyword for date format
Description
This command sets the date format for function display purposes. If specified, <cFormat> may be a customized date format in which the letters d, m and y may be used to desing a date format. The default is an AMERICAN date format; specifying no parameters will set the date format to AMERICAN. Below is a table of the varius predefined dates formats.

Syntax Date Format
ANSI yy.mm.dd
BRITISH dd/mm/yy
FRENCH dd/mm/yy
GERMAN dd.mm.yy
ITALIAN dd-mm-yy
JAPAN yy.mm.dd
USA mm-dd-yy
AMERICAN mm/dd/yy

Example(s)
SET DATE JAPAN
? DATE()
SET DATE GERMAN
? Date()
Test(s)
See tests/dates.prg
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
See also
SET DATE,SET EPOCH,CTOD(),DATE(),DTOC(),SET()
Index
Command

SET DECIMALS

Toggle the console display
Syntax
SET DECIMALS TO [<nDecimal>]
Argument(s)
<nDecimal> Number of decimals places
Description
This command establishes the number of decimal places that Harbour will display in mathematical calculations, functions, memory variables, and fields. Issuing no parameter with this command will the default number of decimals to 0. For decimals to be seen, the SET FIXED ON command must be activated.
Example(s)
SET FIXED ON
? 25141251/362
SET DECIMALS TO 10
? 214514.214/6325
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
See also
SET FIXED,SET()
Index
Command

SET DEFAULT

Establishes the Harbour search drive and directory.
Syntax
SET DEFAULT TO [<cPath>]
Argument(s)
<cPath> Drive and/or path.
Description
This command changes the drive and directory used for reading and writting database,index,memory, and alternate files. Specifying no parameters with this command will default the operation to the current logged drive and directory.
Example(s)
SET DEFAULT to C:\temp
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
See also
SET PATH,CURDIR(),SET()
Index
Command

SET DEVICE

Directs all @...SAY output to a device.
Syntax
SET DEVICE TO [printer | SCREEN ]
Argument(s)
None.
Description
This command determines whether the output from the @...SAY command and the DEVPOS() and DEVOUT() function will be displayed on the printer.
When the device is set to the PRINTER,the SET MARGIN value adjusts the position of the column values accordingly. Also, an automatic page eject will be issued when the current printhead position is less than the last printed row. Finally, if used in conjunction with the @. ..GET commands, the values for the GETs will all be ignored.
Example(s)
SET DEVICE TO SCREEN
? 25141251/362
SET DEVICE TO PRINTER
SET PRINTER TO LPT1
? 214514.214/6325
SET PRINTER OFF
SET DEVICE TO SCREEN
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
See also
@...SAY,SET PRINTER,SETPRC(),SET()
Index
Command

SET EPOCH

Specify a base year for interpreting dates
Syntax
SET EPOCH TO <nEpoch>
Argument(s)
<nEpoch> Base Century.
Description
This command sets the base year value for dates that have only two digits. The default setting is 1900. Dates between 01/01/0100 and 12/31/2999 are fully supported.
Example(s)
SET EPOCH TO 2000
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
See also
SET DATE,SET CENTURY,CTOD(),DATE(),DTOC(),SET()
Index
Command

SET FIXED

Set the number of decimal position to be displayed
Syntax
SET FIXED on | OFF | (<lFixed>)
Argument(s)
<lFixed> Logical expression for toggle
Description
This command activates a system wide fixed placement of decimals places shown for all numeric outputs. If the value of <lFixed> is a logical true (.T.), FIXED will be turned ON; otherwise it will be turned OFF.
When SET DECIMALS OFF is used, the following rules apply to the number of decimal placed displayed.

Addition Same as operand with the greatest number of decimal digits
Subraction Same as operand with the greatest number of decimal digits
Multiplication Sum of operand decimal digits
Division Determined by SET DECIMAL TO
Exponential Determined by SET DECIMAL TO
LOG() Determined by SET DECIMAL TO
EXP() Determined by SET DECIMAL TO
SQRT() Determined by SET DECIMAL TO
VAL() Determined by SET DECIMAL TO

Example(s)
SET FIXED ON
? 25141251/362
SET FIXED OFF
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
See also
SET DECIMALS,EXP(),LOG(),SQRT(),VAL(),SET()
Index
Command

SET FUNCTION

Assign a character string to a function key
Syntax
SET FUNCTION <nFunctionKey> TO [<cString>]
Argument(s)
<nFunctionKey> is a number in the range 1..40 that represent the function key to be assigned.
<cString> is a character string to set. If <cString> is not specified, the function key is going to be set to NIL releasing by that any previous Set Function or SETKEY() for that function.
Description
Set Function assign a character string with a function key, when this function key is pressed, the keyboard is stuffed with this character string. Set Function has the effect of clearing any SETKEY() previously set to the same function number and vice versa.

nFunctionKey Key to be set
1 .. 12 F1 .. F12
13 .. 20 Shift-F3 .. Shift-F10
21 .. 30 Ctrl-F1 .. Ctrl-F10
31 .. 40 Alt-F1 .. Alt-F10

SET FUNCTION command is preprocessed into __SetFunction() function during compile time.
Example(s)
// Set F1 with a string
CLS
Set Function  1 to  "I Am Lazy" + CHR( 13 )
cTest := SPACE( 20 )
@ 10, 0 SAY "type something or F1 for lazy mode " GET cTest
READ
? cTest
Status
Ready
Compliance
Unknown 'COMPLIANCE' code: 'Harbour use 11 and 12 to represent F11 and F12, while CA-Cl*pper use 11 and 12 to represent Shift-F1 and Shift-F2.'
Platform(s)
This is available on all platforms
See also
INKEY(),SETKEY(),__Keyboard()
Index
Command

SET INTENSITY

Toggles the enhaced display of PROMPT's and GETs.
Syntax
SET INTENSITY ON | off | (<lInte>)
Argument(s)
<lInte> Logical expression for toggle command
Description
This command set the field input color and @...PROMPT menu color to either highlighted (inverse video) or normal color. The default condition is ON (highlighted).
Example(s)
SET INTENSITY ON
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
See also
@...GET,@...PROMPT,@...SAY,SET()
Index
Command

SET KEY

Assign an action block to a key
Syntax
SET KEY <anKey> to p<bAction>] [when <bCondition> ] )
Argument(s)
<anKey> is either a numeric key value, or an array of such values
<bAction> is an optional code-block to be assigned
<bCondition> is an optional condition code-block
Description
The Set Key Command function is translated to the SetKey() function witch returns the current code-block assigned to a key when called with only the key value. If the action block (and optionally the condition block) are passed, the current block is returned, and the new code block and condition block are stored. A group of keys may be assigned the same code block/condition block by using an array of key values in place on the first parameter.
Example(s)
local bOldF10 := setKey( K_F10, {|| Yahoo() } )
... // some other processing
Set Key  K_F10 to  bOldF10)
... // some other processing
bBlock := SetKey( K_SPACE )
if bBlock != NIL ...
// make F10 exit current get, but only if in a get - ignores other
// wait-states such as menus, achoices, etc...
SetKey( K_F10, {|| GetActive():State := GE_WRITE },;
{|| GetActive() != NIL } )
Test(s)
None definable
Status
Ready
Compliance
Unknown 'COMPLIANCE' code: 'SET KEY is mostly CA-Cl*pper compliant. The only difference is the addition of the condition code-block parameter, allowing set-keys to be conditionally turned off or on. This condition-block cannot be returned once set - see SetKeyGet()'
See also
HB_SETKEYSAVE()
Index
Command

SET MESSAGE

Extablishes a message row for @...PROMPT command
Syntax
SET MESSAGE TO [<nRow> [CENTER]]
Argument(s)
<nRow> Row number to display the message
Description
This command is designed to work in conjuntion with the MENU TO and @. ..PROMPT commands. With this command, a row number between 0 and MAXROW() may be specified in <nRow>. This establishes the row on witch any message associated with an @...PROMPT command will apear.
If the value of <nRow> is 0, all messages will be supressed. All messaged will be left-justifies unless the CENTER clause is used. In this case, the individual messages in each @...PROMPT command will be centered at the designated row (unless <nRow> is 0). All messages are independent; therefore, the screen area is cleared out by the centered message will vary based on the length of each individual message.
Specifying no parameters with this command set the row value to 0, witch suppresses all messages output. The British spelling of CENTRE is also supported.
Example(s)
See Tests/menutest.prg
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
See also
SET(),SET WRAP,@...PROMPT,MENU TO
Index
Command

SET PATH

Specifies a search path for opening files
Syntax
SET PATH TO [<cPath>]
Argument(s)
<cPath> Search path for files
Description
This command specifies the search path for files required by most commands and functions not found in the current drive and directory. This pertains primarily, but not exclusively, to databases, indexes, and memo files, as well as to memory, labels and reports files. The search hirarchy is: 1 Current drive and directory, 2 The SET DEFAULT path; 3 The SET PATH path.
Example(s)
SET PATH TO C:\harbour\test
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
See also
SET DEFAULT,CURDIR(),SET()
Index
Command

SET PRINTER

Toggles the printer and controls the printer device
Syntax
SET PRINTER on | OFF SET PRINTER (<lPrinter>) SET PRINTER TO [<cPrinter>] [ADDITIVE]
Argument(s)
<lPrinter> Logical condition by which to toggle the printer
<cPrinter> A device name or an alternate name
Description
This command can direct all output that is not controled by the @... SAY command and the DEVPOS() and DEVOUT() functions to the printer. If specified,the condition <lPrinter> toggles the printer ON if a logical true (.T.) and OFF if a logical false (.F.). If no argument is specified in the command, the alternate file (if one is open) is closed, or the device is reselected and the PRINTER option is turned OFF.
If a device is specified in <cPrinter>, the outpur will be directed to that device instead of to the PRINTER. A specified device may be a literal string or a variable, as long as the variable is enclosed in parentheses. For a network, do not use a trailing colon when redirecting to a device.
If an alternate file is specified, <cPrinter> becomes the name of a file that will contain the output. If no file extension is specified an extension of .prn will be defaulted to.
If the ADDITIVE clause is specified, the information will be appended to the end of the specified output file. Otherwise, a new file will be created with the specified name (or an existing file will first be cleared) and the information will then be appended to the file. The default is to create a new file.
Example(s)
SET PRINTER ON
SET PRINTER TO LPT1
? 25141251/362
SET PRINTER .F.
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
See also
SET DEVICE, SET CONSOLE, DEVOUT(), SET()
Index
Command

SET WRAP

Toggle wrapping the PROMPTs in a menu.
Syntax
SET WRAP on | OFF | (<lWrap>
Argument(s)
<lWrap> Logical expression for toggle
Description
This command toggles the highlighted bars in a @...PROMPT command to wrap around in a bottom-to-top and top-to-bottom manner. If the value of the logical expression <lWrap> is a logical false (.F.), the wrapping mode is set OFF; otherwise,it is set ON.
Example(s)
See Tests/menutest.prg
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
See also
@...PROMPT,MENU TO
Index
Command

FileSys

COPY FILE

Copies a file.
Syntax
COPY FILE <cfile> TO <cfile1>
Argument(s)
<cFile> Filename of source file <cFile1> Filename of target file
Description
This command makes an exact copy of <cFile> and names it <cFile1>. Both files must have the file extension included; the drive and the directory names must also be specified if they are different from the default drive and/or director. <cFile1> also can refer to a OS device (e.g. LPT1). This command does not obsert the SET PATH TO or SET DEFAULT TO settings.
Example(s)
COPY FILE C:\harbour\tests\adirtest.prg TO C:\temp\adirtest.prg
COPY FILE C:\harbour\utils\hbdoc\gennf.prg TO LPT1
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
See also
ERASE,RENAME,FRENAME(),FERASE()
Index
Command

DELETE FILE

Remove a file from disk
Syntax
DELETE FILE <xcFile>
Argument(s)
<xcFile> Name of file to remove
Description
This command removes a file from the disk. The use of a drive, directo- ry,and wild-card skeleton operator is allowed for the root of the filename. The file extension is required. The SET DEFAULT and SET PATH commands do not affect this command.
The file must be considered closed by the operating system before it may be deleted.
Example(s)
ERASE C:\autoexec.bat
ERASE C:/temp/read.txt
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
See also
CURDIR(), FILE(), FERASE(), ERASE
Index
Command

DIR

Display listings of files
Syntax
DIR [<cFileMask>]
Argument(s)
<cFileMask> File mask to include in the function return. It could contain path and standard wildcard characters as supported by your OS (like * and ?). If <cFileMask> contains no path, then SET DEFAULT path is used to display files in the mask.
Description
If no <cFileMask> is given, __Dir() display information about all *.dbf in the SET DEFAULT path, this information contain: 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 returns all the information in a multidimensional array.
Example(s)
DIR          // information for all DBF files in current directory
dir   "*.dbf"          // list all DBF file in current directory
// list all PRG files in Harbour Run-Time library
// for DOS compatible operating systems
Dir  "C:\harbour\source\rtl\*.prg"
// list all files in the public section on a Unix like machine
Dir  "/pub"
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
Platform(s)
This is available on all platforms.
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
See also
ADIR(),DIRECTORY(),SET DEFAULT,__DIR()*
Index
Command

ERASE

Remove a file from disk
Syntax
ERASE <xcFile>
Argument(s)
<xcFile> Name of file to remove
Description
This command removes a file from the disk. The use of a drive, directo- ry, and wild-card skeleton operator is allowed for the root of the filename. The file extension is required. The SET DEFAULT and SET PATH commands do not affect this command.
The file must be considered closed by the operating system before it may be deleted.
Example(s)
ERASE C:\autoexec.bat
ERASE C:/temp/read.txt
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
See also
CURDIR(), FILE(), FERASE(), DELETE FILE
Index
Command

RENAME

Changes the name of a specified file
Syntax
RENAME <cOldFile> TO <cNewFile>
Argument(s)
<cOldFile> Old filename
<cNewFile> New Filename
Description
This command changes the name of <cOldFile> to <cNewFile>. Both <cOldFile> and <cNewFile> must include a file extension. This command if not affected by the SET PATH TO or SET DEFAULT TO commands;drive and directoy designaters must be specified if either file is in a directory other then the default drive and directory.
If <cNewFile> id currently open or if it previously exists, this command will not perform the desired operation.
Example(s)
RENAME C:\autoexec.bat TO C:\autoexec.old
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
File(s)
Library is rtl
See also
CURDIR(),ERASE,FILE(),FERASE(),FRENAME()
Index
Command

TYPE

Show the content of a file on the console, printer or file
Syntax
TYPE <xcFile> [TO PRINTER] [TO FILE <xcDestFile>]
Argument(s)
<xcFile> is a name of the file to display. If the file have an extension, it must be specified (there is no default value). It can be specified as literal file name or as a character expression enclosed in parentheses.
TO PRINTER is an optional keyword that specifies that the output should go to both the screen and printer.
TO FILE <xcDestFile> copy the source <xcFile> also to a file. If no extension is given (.txt) is added to the output file name. <xcDestFile> can be specified as literal file name or as a character expression enclosed in parentheses.
Description
TYPE command type the content of a text file on the screen with an option to send this information also to the printer or to an alternate file. The file is displayed as is without any headings or formating.
If <xcFile> contain no path, TYPE try to find the file first in the SET DEFAULT directory and then in search all of the SET PATH directories. If <xcFile> can not be found a run-time error occur.
If <xcDestFile> contain no path it is created in the SET DEFAULT directory.
Use SET CONSOLE OFF to suppress screen output. You can pause the output using Ctrl-S, press any key to resume.
Example(s)
The following examples assume a file name mytext.dat exist in all
specified paths, a run-time error would displayed if it does not
// display mytext.dat file on screen
TYPE mytext.dat
// display mytext.dat file on screen and printer
TYPE mytext.dat TO PRINTER
// display mytext.dat file on printer only
SET CONSOLE OFF
TYPE mytext.dat TO PRINTER
SET CONSOLE ON
// display mytext.dat file on screen and into a file myreport.txt
TYPE mytext.dat TO FILE MyReport
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
See also
COPY FILE,SET DEFAULT,SET PATH,SET PRINTER,__TYPEFILE()
Index
Command

Legacy

LABEL FORM

Displays labels to the screen or an alternate device
Syntax
LABEL FORM <cLabelName> [TO PRINTER] [TO FILE <cFile>] [<cScope>]
[WHILE <bWhile> ] [FOR <bFor> ] [SAMPLE] [NOCONSOLE]
Argument(s)
<cLabelName> Name of label file <cFile> Name of an alternate file <cScope> Expression of a scoping condition <bWhile> WHILE condition <bFor> FOR condition
Description
This command allows labels to be printed based on the format outlined in LBL file specified as <cLabelName>. By default, output will go to the screen however this output may be rerouted with either the TO PRINTER or the TO FILE clause.
If the TO FILE clause is specified, the name of the ASCII text file containing the generated labels will be <cFile>.
If no file extension is specified a .txt extension is added. <cScope> is the scope condition for this command. Valid scopes include NEXT <expN> (number of records to be displayed, where <expN> is the number of records), RECORD <expN> (a specific record to be printed), REST (all records starting from the current record position,and ALL (all records). The default is ALL.
Both logical expression may work ill conjunction with one another where <bFor> is the logical expression for the FOR condition (for records to be displayed whitin a given value range) and <bWhile> for the WHILE condition (for records to be displayed until they fail to meet the condition).
If the SAMPLE clause is specified, test labels will be generated.
If the NOCONSOLE clause is specified,the console will be turned off while this command is being executed.
This command follows the search criteria outlined in the SET PATH TO command. The path may be specified, along, with (the drive letter, in <cLabelName>
Example(s)
FUNCTION MAIN()
USE Test New
LABEL FORM EE
USE
RETURN NIL
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
Platform(s)
This is available on all platforms
File(s)
Library is rtl
See also
REPORT FORM
Index
Command

REPORT FORM

Display a report
Syntax
REPORT FORM <cReportName> [TO PRINTER] [TO FILE <cFile>] [<cScope>]
[WHILE <bWhile> ] [FOR <bFor> ] [PLAIN |HEADING <cHeading>] [NOEJECT] [SUMMARY] [NOCONSOLE]
Argument(s)
<cReportName> Name of report file
<cFile> Name of alternate file
<cScope> Scope.
<bWhile> Logical expression of WHILE condition .
<bFor> Logical expression of FOR condition.
<cHeading> Report heading
Description
This command prints out the report named <cReportName>, which is a standard FRM file. The file extension is not required because .frm will be assumed. The SET PATH TO and SET DEFAULT TO commands affect the search for the file <cReportName>; unless a drive and path are specified in <cReportName>, REPORT will search the path specified in the SET PATH command if it cannot find the report form in the current directory.
The output of the report will be offset based on the setting of the SET MARGIN TO value.
By default, output will go to the console; however, it may be controlled via either the TO PRINTER or TO FILE clause. If the output is to go to the file, the name of the alternate file is specified in <cFile>. Unless specified in <cFile>, the default file extension will be TXT.
<cScope> is the scope for this command. Valid scopes include NEXT <expN> (where <expN> is the number of records), RECORD <expN> (a specific record to be displayed), REST (all records from the current record position), and ALL (all records). The default is ALL.
Both logical expressions may work in conjuntion with one another, where <bFor> is the logical expression for the FOR condition (for records to be displayed within a given range) and <bWhile> for the WHILE condition (for records to be displayed until the condition fails).
If the PLAIN clause is specified, date and page numbers are suppressed. In addition, there is no automatic page breaking, and the report title and column headings appear only once at the top of the form.
If the HEADING clause is used, <cHeading> is displayed on the first title of each report page. The value of <cHeading> is evaluated only once before executing the report; varying the values of <cHeading> is not allowed. The PLAIN clause will take precedence over the HEADING clause if both are included.
If the NOEJECT clause is used, the initial page eject on the report will not be issued when the output clause TO PRINTER is specified. Otherwise, this clause has no effect.
If the SUMMARY Clause is specified, the report will contain only groups, subgroups, and grand total information. The detailed title item information will be ignored.
If the NOCONSOLE clause is specified,output to the console will be turned off while this command is being executed.
Example(s)
FUNCTION() MAIN
USE Test New
Report FORM EE
USE
RETURN NIL
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
Platform(s)
This is available on all platforms
File(s)
Library is rtl
See also
LABEL FORM
Index
Command

Printer

EJECT

Issue an command to advance the printer to the top of the form
Syntax
EJECT
Argument(s)
None
Description
This command issue an form-feed command to the printer. If the printer is not properly hooked up to the computer,an error will not be generated and the command will be ignored.
Once completed,the values of PROW() and PCOL(),the row and column indicators to the printer,will be set to 0. Their values,however,may be manipulated before or after ussuing an EJECT by using the DEVPOS() function.
On compile time this command is translated into __EJECT() function.
Example(s)
Use Clientes New
Set Device to Printer
CurPos:=0
While !Eof()
? Clientes->nome,Clientes->endereco
Curpos++
if Curpos >59
Curpos:=0
Eject
Endif
Enddo
Set Device to Screen
Use
Test(s)
See examples
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
Platform(s)
This is available on all platforms
See also
DEVPOS(),SET PRINTER,PROW(),PCOL()
Index
Command

RDD

FIELD

Declares a list of database field names.
Syntax
FIELD <xField> [,<xFieldn...> [in <cDatabase>]
Argument(s)
<xField> A valid field name
<xFieldn> Additional field name
<cDatabase> An valid alias name
Description
This command declares the names of fields <xField> (and <xFieldn> and following) with an optional alias identifier as <cDatabase> for each. This command allow Harbour to resolve any reference to a field specified in the field list by viewing it as a field when it is not referenced by an alias. If a field is not listed in this list and it is not explicity tagged with an alias indentifier, it may be viewed as a memory variable, which may cause run-time errors. This command has no effect on memory variables or on field reference buried within a macro expression.
Example(s)
Func main
FIELD iD
FIELD Name
USE TESTS NEW
name:="Sales"
Id:=5
USE
Return Nil
Test(s)
See tests/testwarn.prg
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
Platform(s)
This is available on all platforms
File(s)
None.
See also
MEMVAR,PRIVATE,PUBLIC,STATIC
Index
Command

User interface

@...Get

Creates a GET object and displays it to the screen
Syntax
@ <nRow>,<nCol> [SAY <cSay> [PICTURE <cSayPict>] COLOR <cSayColor> ] GET <xVar> [PICTURE <cGetPict>] [WHEN <lWhen>] [COLOR <cGetColor>] [VALID <lValid> / RANGE <xStart>,<xEnd>]
Argument(s)
<nRow> The row coordinate.
<nCol> The column coordinate.
<cSay> Message to display.
<cSayPict> Character expression of PICTURE displayed.
<cSayColor> Color to be Used for the SAY expression.
<xVar> An variable/field name.
<cGetPict> Character expression of PICTURE to get.
<lWhen> Logical expression to allow GET.
<lValid> Logical expression to validate GET input.
<xStart> Lower RANGE value.
<xEnd> Upper RANGE value.
<cGetColor> Color string to be used for the GET expression.
Description
This command adds a GET object to the reserved array variable named GETLIST[] and displays it to the screen. The field or variable to be added to the GET object is specified in <xVar> and is displayed at row, column coordinate <nRow>, <nCol>.
If the SAY clause is used <cSay> will be displayed starting at <nRow>, <nCol>, with the field variable <xVar> displayed at ROW(), COL()+ 1. If <cSayPicr>, the picture template for the SAY expression <cSay>, is used, all formatting rules contained will apply See the TRANSFORM I function for futher information.
If <cGetPict> is specified, the PICTURE clause of <xVar> will be used for the GET object and all formatting rules will apply. See the table below for GET formatting rules.
If the WHEN clause is specified,when <lWhen> evaluates to a logical true (.T.) condition, the GET object will he activated otherwise the GET object will be skipped and no information will be obtained via the screen. The name of a user-defined function returning a logical true (.T.) or false ( F.) or a code block may be ,specified in <lWhen> This clause not activated until a READ command or READMODAL() function call is issued.
If the VALID clause is specified and <lValid> evaluates to it logical true (.T.) condition the current GET will be considered valid and the get operation will continue onto the next active GET object. If not, the cursor will remain on this GET object until aborted or until the condition in <lValid> evaluates to true (.T.). The name of a user-defined function returning a logical true (.T.) or false (.F.) or it code block may be specified in <lValid>. This clause is not activated until a READ command or READMODAL( ) function call is issued.
If the RANGE clause is specified instead of the VALID clause, the two inclusive range values for <xVar> must be specified in <xStart> and <xEnd>. Id <xVar> is a date data type,<xStart> and <xEnd> must also be date data types; if <xVar> is a numeric data type <xStart> and <xEnd> must also be numeric data types. If a value fails the RANGE test ,a message of OUT OF RANGE will appear in the SCOREBOARD area (row = 0, col = 60). The RANGE message may be turned off it the SET SCOREBOARD command or SET() function appropriately toggled.
NOTE GET functions/formatting rules:

@A Allows only alphabetic characters.
@B Numbers will be left justified
@C All positive numbers will be followes by CR.
@D All dates will be in the SET DATE format.
@E Dates will be in British formal: numbers in European format.
@K Allows a suggested value to be seen within the GET
area but clears It if any noncu sor key is pressed when
the cursor is in the first Position in the GET area.
@R Nontemplate characters will be inserted.
@S<nSize> Allows horizontal scrolling of a field or variable that
is <nSize> characters wide.
@X All negative numbers will be followed by DB
@Z Displays zero values as blanks.
@! Forces uppercase lettering
@( Displays negative numbers in parentheses with leading spaces.
@) Displays negative numbers in parentheses without leading spaces.

GET templates/formatting rules:

A Only alphabetic characters allowed.
N Only alphabetic and numeric characters allowed
X Any character allowed.
L Only T or F allowed For logical data.
Y Only Y or N allowed for logical data.
9 Only digits, including signs, will be allowed.
# Only digits, signs. and spaces will he allowed.
! Alphabetic characters are converted to Uppercase.
$ Dollar will be displayed in place of leading
spaces for numeric data types.
* Asterisk,, will Be displayed in place of leading spaces
for numeric data types.
. Position of decimal point.
, Position of comma.

Format PICTURE functions may he grouped together as well as used in Conjunction with a PICTURE templates;however, a blank space must be included in the PICTURE string if there are both functions and templates.
Example(s)
Function Main()
Local cVar:=Space(50)
Local nId:=0
cls
@ 3,1 SAY "Name" GET cVar PICTURE "@!S 30"
@ 4,1 SAY "Id"   GET nId  PICTURE "999.999"
READ
? "The name you entered is",cVar
? "The id you entered is",nId
RETURN NIL
Test(s)
See Examples
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
Platform(s)
This is available on all platforms
See also
@...SAY,READ,TRANSFORM()
Index
Command

@...PROMPT

Display a menu item on screen and define a message
Syntax
@ <nRow>, <nCol> PROMPT <cPrompt> [MESSAGE <xMsg>]
Argument(s)
<nRow> is the row number to display the menu <cPrompt>. Value could range from zero to MAXROW().
<nCol> is the column number to display the menu <cPrompt>. Value could range from zero to MAXCOL().
<cPrompt> is the menu item character string to display.
<xMsg> define a message to display each time this menu item is highlighted. <xMsg> could be a character string or code block that is evaluated to a character string. If <xMsg> is not specified or of the wrong type, an empty string ("") would be used.
Description
With @...Prompt you define and display a menu item, each call to @... Prompt add another item to the menu, to start the menu itself you should call the __MenuTo() function (MENU TO command). You can define any row and column combination and they will be displayed at the order of definition. After each call to @...Prompt, the cursor is placed one column to the right of the last text displayed, and ROW() and COL() are updated.
@...PROMPT command is preprocessed into __AtPrompt() function during compile time.
Example(s)
// display a two line menu with status line at the bottom
// let the user select favorite day
SET MESSAGE TO 24 CENTER
@ 10, 2 PROMPT "Sunday" MESSAGE "This is the 1st item"
@ 11, 2 PROMPT "Monday" MESSAGE "Now we're on the 2nd item"
MENU TO nChoice
DO CASE
CASE nChoice == 0           // user press Esc key
QUIT
CASE nChoice == 1           // user select 1st menu item
? "Guess you don't like Mondays"
CASE nChoice == 2           // user select 2nd menu item
? "Just another day for some"
ENDCASE
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant except that menus (internally arrays) in Harbour can have an unlimited number of elements
See also
ACHOICE(),MENU TO,SET MESSAGE,SET INTENSITY,SET WRAP,__MENUTO()
Index
Command

@...SAY

Displays data at specified coordinates of the current device.
Syntax
@ <nRow>,<nCol> SAY <xValue> [ PICTURE <cPict> ] [COLOR <cColor>]
Argument(s)
<nRow> Row coordinate
<nCol> Column coordinate
<xValue> Value to display
<cPict> PICTURE format
<cColor> Color string
Description
This command displays the contents of <xValue> at row column coordinates <nRow>, <nCol>. A PICTURE clause may be speclfied in <cPict>. If the current device is set to the printer, the output will go to the printer; the default is for all output to go to the screen.
For a complete list of PICTURES templates and functions, see the @... GET command.
Example(s)
Function Main
Cls
@ 2,1 SAY "Harbour"
@ 3,1 SAY "is" COLOR "b/r+"
@ 4,1 SAY "Power" PICTURE "@!"
Return NIL
Test(s)
See Examples
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
Platform(s)
This is available on all platforms
See also
@...GET,SET DEVICE,TRANSFORM()
Index
Command

KEYBOARD

Stuffs the keyboard with a string.
Syntax
KEYBOARD <cString>
Argument(s)
<cString> String to be processed, one character at a time, by the Harbour keyboard processor
Description
This command stuffs the input buffer with <cString>.
The number of characters that can be stuffed into the keyboard buffer is controlled by the SET TYPEAHEAD command and may range from 0 to 32, 622, with each character being in the ASCII range of 0 to 255.
None of the extended keys may be stuffed into the keyboard buffer.
Issuing a KEYBOARD " " will clear the keyboard buffer.
Example(s)
// Stuff an Enter key into the keyboard buffer
KEYBOARD CHR(13)
// Clear the keyboard buffer
CLEAR TYPEAHEAD
Test(s)
KEYBOARD CHR(13); ? INKEY() ==> 13
KEYBOARD "HELLO"; CLEAR TYPEAHEAD; ? INKEY() ==> 0
Status
Ready
Compliance
Unknown 'COMPLIANCE' code: 'KEYBOARD is compliant with CA-Cl*pper 5.3'
See also
CLEAR TYPEAHEAD,__KEYBOARD()
Index
Command

Variable management

LOCAL

Initializes a local memory variable or array
Syntax
LOCAL <xVar> [:= <xInit> ]
Argument(s)
<xVar> Name of a memory variable or array.
<xInit> Value to be assinged to a variable or array
Description
This command created a LOCAL memory variable or array. The name of either is specified in <xVar>. If more then one variable is being initialized with the LOCAL command,separate each entry with a comma. If a variable or an array is to be assingned a start-up value,that expression may be specified in <xInit> and folling. Is Strong type compile mode is used, the Compiler will check if the value recived matchs the type specified in <xType>.
LOCAL varibles are symbols generated at run time and are resolved at compile time. The visibility and life span of a LOCAL variable or array is limited to the function or procedure in which it is defined.
No macro expansions are allowed in the LOCAL declaration statement.
No Harbour command other then FUNCTION, PROCEDURE, PUBLIC, PRIVATE, PARAMETERS, MEMVAR, STATIC and FIELD, may precede the LOCAL command.
LOCAL array reference may not be initialized (i.e., assigned values) on the same command line as the LOCAL command statement. This can be done later in the program.
LOCAL variables and arrays are not affected by the RELEASE command.
Example(s)
Function Main2()
Local n, lVar
n := IIF( lVar, 'A', 3 )
n := 2
n := 'a'
n := seconds() + 2
n := int( seconds() + 2 )
Return NIL
Test(s)
See tests/testwarn.prg for more examples
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
Platform(s)
This is available on all platforms
File(s)
None
See also
FIELD,PRIVATE,PUBLIC,STATIC,MEMVAR
Index
Command

MEMVAR

Declares private and public variables and arrays.
Syntax
MEMVAR <xVar>
Argument(s)
<xVar> Memory variable Name
Description
This command tells the compiler to resolve any reference to a memory variable designated within this list s if it possessed an explicit memory variable alias with either the M-> or MEMVAR-> prefix.Only those memory variables that do not contain any such explicit are affected by this command. Those memory variabls within macro expansions are not affected by this command.
The MEMVAR declaration must apear before any executable commands;it is similat to the LOCAL,STATIC,FIELD,PARAMETERS,FUNCTION, and PROCEDURE commands statements.
Example(s)
MEMVAR y As Numeric
Function Main2()
Local n , lVar
n := IIF( lVar, 'A', 3 )
n := 2
n := 'a'
n := seconds() + 2
n := int( seconds() + 2 )
y := n
? y
Return NIL
Test(s)
See tests/testwarn.prg for more examples
Status
Ready
Compliance
This is CA-Cl*pper v5.2 compliant
Platform(s)
This is available on all platforms
File(s)
None.
See also
LOCAL,STATIC,FIELD,PRIVATE,PUBLIC
Index
Command