The whole FlagShip 7 manual consist of following · PDF fileCMD 8 [item] The entry is...

The whole FlagShip 7 manual consist of following sections:

Section Content Pages

GEN General information: License agreement & warranty,installation and de-installation, registration and support 18

LNGFlagShip language: Specification, database, files,language elements, multiuser, multitasking, FlagShipextensions and differences

176

FSC Compiler & Tools: Compiling, linking, libraries, make,run-time requirements, debugging, tools and utilities 90

CMD Commands and statements: Alphabetical reference ofFlagShip commands, declarators and statements 486

FUN Standard functions: Alphabetical reference of FlagShipfunctions 640

OBJObjects and classes: Standard classes for Get,Tbrowse, Error, Application, GUI, as well as otherstandard classes

368

RDD Replaceable Database Drivers 38

EXTC-API: FlagShip connection to the C language, ExtendC System, Inline C programs, Open C API, Modifyingthe intermediate C code

160

FS2 Alphabetical reference of FS2 Toolbox functions 376

QRF Quick reference: Overview of commands, functions andenvironment 40

PRE Preprocessor, includes, directives 30

SYSSystem info, porting: System differences to DOS, portinghints, data transfer, terminals and mapping, distributablefiles

42

REL Release notes: Operating system dependent informa-tion, predefined terminals 8

APP Appendix: Inkey values, control keys, ASCII-ISO table,error codes, dBase and FoxPro notes, forms 34

IDX Index of all sections 42

fsman The on-line manual contains all above sections, searchfunction, and additionally last changes and extensions variable

multisoft Datentechnik, Munich, Germany

Copyright (c) 1992..2009All rights reserved

Object Oriented Database Development System,Cross-Compatible to UNIX, Linux and MS-Windows

Section CMD

Manual release: 7.1

For the current program release see label on distribution disk andyour Activation Card, or check on-line by issuing FlagShip -version

CopyrightCopyright © 1992..2009 by multisoft Datentechnik, D-81545 Munich, Germany. All rightsreserved worldwide. Manual authors: Jan V. Balek, Ibrahim Tannir, Sven Koester

No part of this publication may be copied or distributed, transmitted, transcripted, stored in aretrieval system, or translated into any human or computer language, in any form or by anymeans, electronic, mechanical, magnetic, manual, or otherwise; or disclosed to third partieswithout the express written permission of multisoft Datentechnik. Please see also "LicenseAgreement", section GEN.2

Made in Germany. Printed in Germany.

TrademarksFlagShip™ is trademark of multisoft Datentechnik. Other trademarks: dBASE is trademarkof Borland/Ashton-Tate, Clipper of CA/Nantucket, FoxBase of Microsoft/Fox, UNIX ofAT&T/USL/SCO, AIX of IBM, MS-DOS and MS-Windows of Microsoft. Other productsnamed herein may be trademarks of their respective manufacturers.

Headquarter AddressHeadquarter:

multisoft DatentechnikHarthauser Str. 8581545 MünchenGermany

Telephone: (+49-89) 6490040Fax: (+49-89) 6412974

E-mail: [email protected]@[email protected]

Web/Ftp: http://www.fship.comftp://mult-soft.de/pub

Call or e-mail multisoft for your local dealer or distributor

CMD 1

FlagShip Commands

Notation Used ...........................................................................................................................7! | RUN ....................................................................................................................................11* && // /*...*/ NOTE..................................................................................................................14? | ?? .......................................................................................................................................16?# | ??# | ??## ........................................................................................................................20@... .........................................................................................................................................22@...BOX..................................................................................................................................23@...CLEAR .............................................................................................................................28@...DRAW ARC......................................................................................................................30@...DRAW CIRCLE ................................................................................................................33@...DRAW ELLIPSE...............................................................................................................35@...DRAW IMAGE..................................................................................................................37@...DRAW LINE .....................................................................................................................39@...DRAW PIE........................................................................................................................41@...DRAW POLYGON ...........................................................................................................44@...DRAW RECTANGLE .......................................................................................................46@...PROMPT..........................................................................................................................48@...SAY ..................................................................................................................................53@...SAY BITMAP @...SAY IMAGE ........................................................................................60@...[SAY..] GET......................................................................................................................64@...[SAY..] GET CHECKBOX ................................................................................................76@...GET COMBOBOX............................................................................................................80@...GET LISTBOX..................................................................................................................82@...GET PUSHBUTTON ........................................................................................................88@...[SAY..] GET RADIOBUTTON ..........................................................................................93@...GET RADIOGROUP ........................................................................................................97@...GET TBROWSE.............................................................................................................102@...TO ..................................................................................................................................104ACCEPT ... TO .....................................................................................................................106ACCESS METHOD ASSIGN METHOD ...............................................................................107ANNOUNCE .........................................................................................................................108APPEND BLANK ..................................................................................................................110APPEND ... FROM................................................................................................................111AVERAGE ... TO...................................................................................................................115BEGIN SEQUENCE...END...................................................................................................116CALL .....................................................................................................................................121CANCEL / QUIT....................................................................................................................123CLASS, INSTANCE..............................................................................................................124CLEAR ..................................................................................................................................131CLEAR ALL...........................................................................................................................132CLEAR GETS .......................................................................................................................133CLEAR MEMORY.................................................................................................................134CLEAR MENU ......................................................................................................................135CLEAR SCREEN / CLS........................................................................................................136

CMD 2

CLEAR TYPEAHEAD ...........................................................................................................138CLOSE..................................................................................................................................139COMMIT ...............................................................................................................................141CONTINUE ...........................................................................................................................144CONSTANT ..........................................................................................................................145COPY FILE ... TO .................................................................................................................146COPY TO..............................................................................................................................147COPY STRUCTURE TO ......................................................................................................151COPY TO...STRUCT EXTENDED .......................................................................................152COUNT ... TO .......................................................................................................................154CREATE ...............................................................................................................................155CREATE ... FROM................................................................................................................156DECLARE.............................................................................................................................159DELETE................................................................................................................................161DELETE FILE .......................................................................................................................162DELETE TAG........................................................................................................................163DIR........................................................................................................................................165DISPLAY...............................................................................................................................167DO.........................................................................................................................................168DO CASE..CASE ... ENDCASE ...........................................................................................170DO WHILE ... ENDDO ..........................................................................................................172EJECT...................................................................................................................................174ERASE..................................................................................................................................175EXPORT INSTANCE............................................................................................................176EXTERNAL...........................................................................................................................177FIELD....................................................................................................................................178FIND......................................................................................................................................180FOR ... NEXT........................................................................................................................182FUNCTION ...........................................................................................................................184GLOBAL ... AS......................................................................................................................189GLOBAL_EXTERN ... AS .....................................................................................................192GO | GOTO...........................................................................................................................194HIDDEN INSTANCE.............................................................................................................196IF ... ENDIF ...........................................................................................................................197INDEX ON...TO.....................................................................................................................199INPUT ... TO .........................................................................................................................206INSTANCE............................................................................................................................208JOIN WITH...TO... ................................................................................................................209KEYBOARD..........................................................................................................................210LABEL EDIT..........................................................................................................................212LABEL FORM .......................................................................................................................215LIST ......................................................................................................................................217LOCAL ..................................................................................................................................219LOCAL ... AS ........................................................................................................................222LOCATE ... FOR...................................................................................................................228MEMVAR ..............................................................................................................................230MENU TO .............................................................................................................................232METHOD ..............................................................................................................................235NOTE....................................................................................................................................239

CMD 3

ON ANY KEY ON KEY .........................................................................................................240ON ERROR...........................................................................................................................241ON ESCAPE .........................................................................................................................243PACK ....................................................................................................................................244PARAMETERS .....................................................................................................................246PRIVATE...............................................................................................................................248PROCEDURE .......................................................................................................................250PROTECT INSTANCE..........................................................................................................255PROTOTYPE........................................................................................................................256PUBLIC .................................................................................................................................261PROTECT PUBLIC...............................................................................................................264PUSH KEY POP KEY...........................................................................................................265QUIT......................................................................................................................................266READ ....................................................................................................................................267RECALL ................................................................................................................................275REFRESH.............................................................................................................................276REINDEX ..............................................................................................................................277RELEASE .............................................................................................................................279RENAME ... TO.....................................................................................................................280REPLACE ... WITH...............................................................................................................282REPORT EDIT......................................................................................................................286REPORT FORM ...................................................................................................................288REQUEST.............................................................................................................................290RESTORE FROM .................................................................................................................291RESTORE SCREEN.............................................................................................................293RETURN ...............................................................................................................................294RUN ......................................................................................................................................295SAVE TO ..............................................................................................................................301SAVE SCREEN ....................................................................................................................303SEEK.....................................................................................................................................305SEEK EVAL ..........................................................................................................................307SELECT ................................................................................................................................309SET ALTERNATE.................................................................................................................312SET ANSI..............................................................................................................................314SET AUTOCOMMIT .............................................................................................................315SET AUTOLOCK ..................................................................................................................316SET BELL .............................................................................................................................319SET CENTURY.....................................................................................................................320SET CHARSET.....................................................................................................................321SET COLOR TO ...................................................................................................................322SET COORD.........................................................................................................................328SET CONFIRM .....................................................................................................................330SET CONSOLE ....................................................................................................................331SET COORDINATE UNIT.....................................................................................................332SET CURSOR ......................................................................................................................333SET DATE ............................................................................................................................334SET DBREAD SET DBWRITE .............................................................................................336SET DECIMALS TO..............................................................................................................338SET DEFAULT TO................................................................................................................339

CMD 4

SET DELETED .....................................................................................................................340SET DELIMITERS ................................................................................................................341SET DEVICE TO...................................................................................................................343SET DIRECTORY TO...........................................................................................................344SET EJECT...........................................................................................................................346SET EOFAPPEND................................................................................................................347SET EPOCH .........................................................................................................................348SET ESCAPE .......................................................................................................................350SET EVENTMASK................................................................................................................351SET EXACT..........................................................................................................................352SET EXCLUSIVE..................................................................................................................354SET EXTRA..........................................................................................................................356SET FILTER TO....................................................................................................................358SET FIXED ...........................................................................................................................360SET FONT ............................................................................................................................362SET FONT ALIGN SET FONT BASELINE...........................................................................365SET FORMAT TO.................................................................................................................367SET FUNCTION ... TO .........................................................................................................369SET GOTOP.........................................................................................................................371SET GUIALIGN.....................................................................................................................372SET GUICOLORS ................................................................................................................373SET GUICURSOR................................................................................................................374SET GUIPRINTER................................................................................................................376SET GUITRANSL .................................................................................................................377SET HTMLTEXT...................................................................................................................381SET INDEX TO.....................................................................................................................384SET INPUT ...........................................................................................................................387SET INTENSITY ...................................................................................................................388SET KEY ... TO.....................................................................................................................389SET KEYTRANSL ................................................................................................................393SET LARGEFILE ..................................................................................................................395SET MARGIN TO..................................................................................................................396SET MESSAGE TO ..............................................................................................................398SET MULTIBYTE..................................................................................................................399SET MULTILOCKS...............................................................................................................401SET NFS...............................................................................................................................403SET OPENERROR...............................................................................................................405SET ORDER TO...................................................................................................................406SET OUTMODE....................................................................................................................408SET PATH TO ......................................................................................................................410SET PIXEL............................................................................................................................412SET PRINTER ......................................................................................................................413SET PROCEDURE TO.........................................................................................................420SET RELATION....................................................................................................................421SET ROWADAPT .................................................................................................................425SET ROWALIGN ..................................................................................................................426SET SCRCOMPRESS..........................................................................................................429SET SCOREBOARD ............................................................................................................430SET SOFTSEEK...................................................................................................................431

CMD 5

SET SOURCE.......................................................................................................................433SET TYPEAHEAD TO ..........................................................................................................436SET UNIT..............................................................................................................................437SET UNIQUE ........................................................................................................................438SET WRAP ...........................................................................................................................439SETSTANDARD SETENHANCED SETUNSELECTED ......................................................440SET ZEROBYTEOUT...........................................................................................................441SKIP......................................................................................................................................442SORT ...ON...TO...................................................................................................................444STATIC .................................................................................................................................446STATIC ... AS .......................................................................................................................448STORE..................................................................................................................................451SUM ......................................................................................................................................453TEXT ... ENDTEXT...............................................................................................................454TOTAL ..................................................................................................................................455TYPE.....................................................................................................................................457UNLOCK ...............................................................................................................................458UPDATE ...............................................................................................................................460USE.......................................................................................................................................462WAIT .....................................................................................................................................470ZAP .......................................................................................................................................473Index CMD ............................................................................................................................475

CMD 7

FlagShip Commands

Notation UsedThe syntax of the FlagShip commands is the same as in other xBase languages, such asdBASE or Clipper. The following notation is used throughout this manual:

COMMAND [arguments] [KEYWORD [arguments]]COMMAND

One or more special keywords (or symbols) at the beginning of a source line(leading spaces and tabs are not significant) define the commands, such as RUN, ?APPEND etc. The command keywords are case insensitive and may be shortenedto 4 characters, so APPEND, APPEN and APPE represent the same commandkeyword, but APPEX will produce a compile-time error.

KEYWORDThe keyword (or clause) modifies the command to perform and satisfy additionalspecial actions and requirements. The keywords are also case insensitive and maybe shortened to 4 characters.

<argument>Some commands and keywords require additional specification (arguments). Thesyntax used for the arguments is always "exp?" where "?" is the type of theexpression e.g. "expC" for character, "expN" for numeric and so on. This means,that the argument may be entered as a constant, variable or any expression of therequired type. If the type is not given, any type is allowed. The usual syntax isKEYWORD constant or KEYWORD "constant" or KEYWORD &macro. orKEYWORD (expression), see details in each command syntax. Note that theparenthesis ( ) does not specify here the priority of the evaluation like amathematical parentheses, but tells the compiler: "use/calculate an expressioninstead of constant". So the arguments "abc.efg" and (xyz + ".efg") are valid(constant vs. expression), but (xyz)+".efg" is an invalid argument syntax, although itis a valid expression in all other context.

<item>The text within the angle brackets informs you which type of information you shouldspecify; not the item itself. Do not enter the brackets.

item1|item2If more than one kind of syntax is allowed, the different syntax keywords or optionsare separated with the | sign. The items are mutually exclusive, you may use onlyone of them. Do not type the | sign.

item [item ...]The item may be entered more than once. Do not type the [ ] brackets.

CMD 8

[item]The entry is optional, you may either specify it or not. Do not type the [ ] brackets.

[item1 [,item2]]The entry of both item1 and item2 is optional, you may give item1 or item1,item2 ornothing at all. Do not type the [ ] brackets themselves.

(item)The parentheses are part of the syntax and must be entered.

expConstant, variable or expression of any type.

expC, expN, expD, expLConstant, variable or expression of type character, numeric, date or logical (seeLNG.2.8).

varSVariable of type screen (see LNG.2.6).

expList, argList, fieldListList of expressions (or arguments, fields etc.) in the syntax exp1 [,exp2 [, exp3 ...]].If two or more expressions (or arguments, fields etc.) are specified, a comma isused as a separator between each of the single expressions <exp>; see alsoLNG.2.8.

on|OFF|(<expL>)The ON or OFF switch (flag) activates or deactivates the command and is specifiedas a literal (meaning the letters "on" or "off"). Alternatively, the parenthesized<expL> (logical expression or constant) can be used, whereby logically TRUE is thesame as ON. The default switch is given in capital letters.

<scope>In some database commands, partial execution can be specified. The valid<scope> arguments are: ALL (all database records), NEXT <expN> (next nrecords), REST (from the current record to the end of the database), RECORD<expN> (the given record number). Additional filters are available using FOR andWHILE clauses.

...FOR <condition> ...WHILE <condition>In some database commands, the FOR clause specifies that the command will berepeatedly executed for all records meeting the logical expression given as<condition>. The WHILE clause stops the repetition of the command when the firstrecord which does not meet the condition is reached. The <scope> option, if given,restricts the FOR and WHILE clause.

...TO PRINTERThis clause echoes the output of the console command (per default ADDITIVE) to aprinter file or to the device set by the SET PRINTER TO command. The ..TOPRINTER clause is equivalent to automatically echoing output to a printer file ordevice, already activated by the SET PRINTER ON command. If the SET PRINTER

CMD 9

TO <file> (or device) was not specified, the output is redirected to the FlagShip'sstandard spooler file, see LNG.3.4 and LNG.5.1.6.

...TO FILE <file>This clause echoes the output of the console command to the specified ASCII file. Ifthe file extension is not specified, .txt is assumed. If the additional ADDITIVE optionis given, an addition in made to the output instead of the <file> being overwritten.The TO FILE.. ..ADDITIVE clause is equivalent to automatically echoing output to aSET EXTRA file or device which has been already opened and activated by ON.Additional redirections of the sequential (console) output are available using theSET PRINTER ON and SET ALTERNATE ON/TO commands.

Syntax:The required syntax, keywords and arguments of the command.

Arguments/Options:Explanation of the required or optional command modifiers or entries.

Multiuser:Where special or additional requirements or actions in the multiuser and/or multi-tasking (or network) environment are necessary, they will be listed in thisparagraph.

Example:Example of one or more command usage possibilities, in a program context.

Classification:Classification of the command, e.g. input, output, database etc..

Compatibility:The commands, keywords and arguments have the same syntax as in other xBASEdialects, like Clipper. If differences exist, they are noted here.

Include:If a special #include file is available or affected (except the default std.fh), it will belisted.

Translation:

Most commands will be translated by the FlagShip preprocessor to equivalentfunctions, according to the file <FlagShip_dir>/include/ std.fh. The actual translationmay differ, and is given for your orientation only. The std.fh file and the internal,undocumented functions (where the name starts with an underscore) may bechanged without prior notice.

Related:Equivalent, related or similar commands and functions.

PROCEDURE exampleTypography used for program examples or command usage.

CMD 10

$ inputTypography used for user input from the UNIX shell.

<FlagShip_dir>The <FlagShip_dir> is usually the directory /usr/local/FlagShip7 in Unix and Linux,or C:\Program Files\FlagShip in MS-Windows, but may differ according to yoursetup choice and MS-Windows defaults. The real path is displayed by "FlagShip -v" or "FlagShip -h".

COMMANDS, KEYWORDS and standard FUNCTIONS will be specified in this manual inuppercase, but their case is disregarded during compilation.

The FlagShip preprocessor translates standard commands to their equivalent functionsaccording to the definitions in the std.fh include file (see translation above). FlagShip alsosupports user-defined-commands (UDC), which are translated via the #command or#xcommand preprocessor directive to other functions or commands. See more in sectionPRE.

The commands that follow are listed in alphabetical order and may be used as the languagereference. For a summary of the commands, see sections QRF and LNG.

CMD 11

! | RUNSyntax:

! [WAIT|NOWAIT][MESSAGE <expC1>]<UNIX command|Windows command>|(<expC2>)

or:RUN [WAIT|NOWAIT]

[MESSAGE <expC1>]<UNIX command|Windows command>|(<expC2>)

Purpose:Executes a UNIX or MS-Windows command, program or script within the actualapplication. This enables harnessing the power of UNIX or Windows commands.

Arguments:<UNIX command> may be any executable program or script within the path. Allcharacter expressions must be enclosed in parentheses. Macro expressions canalso be used and will be expanded before submitting the command to the shell.

Options:WAIT or NOWAIT: optional modifier. With WAIT (default), the application will waituntil the command will finish. NOWAIT will trigger the command to background andcontinue execution of the application. NOWAIT is similar to Unix command"shell_call &". Do not use WAIT/NOWAIT clause together with the "&" postfix.

MESSAGE <expC1> is an optional, user defined message to be printed on thescreen, when the executed UNIX command is finished. Note, no FlagShip outputmapping is active when the MESSAGE is printed; it works as does the "echo<expC1>" from the UNIX shell would. Before <expC1> is printed, a NEW LINE isexecuted (similar to the WAIT command).

Note that both options, if any given, needs to precede the command.

Return code:The return code may be checked via DosError() function. Note: this return code issystem dependant and correspond to the return value of system function system()or of errno if system() returns -1. On some oper. systems, you will get the true exitcode by calculating nRet := int(DosError() / 256). You may display the clean errormsg by Doserror2str()

Description:At RUN command, FlagShip invokes a new shell and passes it the UNIX orWindows command to be executed. The required command must be available inthe current path or else given with an absolute path.

When the <Unix/Windows command> ends (or when the background process isstarted by "&" postfix or by NOWAIT clause), the control returns back to theapplication, executing the next FlagShip statement.

CMD 12

In MS-Windows, the ! or RUN command works by the same way as in Unix. Seefurther details in CMD.RUN description.

To enable the inspection of the output from the called program, print a prompt(using e.g. the MESSAGE clause or the equivalent statement "; echo...") and stopthe further execution using INKEY(0) after the RUN command; see example on theRUN command.

Shell access: You may run a shell by specifying the argument "sh" (or "csh", "ksh"respectively) to the RUN command. To exit the shell, type "exit". In MS-Windows,invoke "CMD" or COMMAND for that reason.

Background processing: the executable or script called may run in background, ifthe RUN command specification ends with an ampersand (&) character or by usingthe NOWAIT clause. The current application will not wait for the called executableto finish, but will carry on with its own execution immediately. The program calledbecomes a child of the calling executable and will terminate latest when the currentapplication terminates. Applicable in Unix/Linux only. Note that any input to, oroutput from the background program may cause the called application to hang.

User break: when the called program is a FlagShip application, both programs willreceive the break and debug signals (^K and ^O).

Screen output: In Terminal i/o, output from the called application goes to theapplication screen, and may garbage it. In GUI mode, the output goes to stdout orstderr, which is usually assigned to the console (or console window), and hencedoes not affect the current screen. See more in (CMD) RUN.

Compatibility note: since the Unix and MS-Windows commands usually differsfrom each other, you may use#ifdef FS_WIN32

RUN Windows-Command...#else

RUN Unix-Command...#endif

Example:This example shows how to use RUN in combination with MEMOREAD() andMEMOWRIT() to create a user-defined function that calls the editor with the currentmemo field:

PUBLIC FlagShip, Clippereditor = if (FlagShip, "vi", "edlin")success = MemoEditor (editor, "Notes")

FUNCTION MemoEditor (editor, memofld)IF MEMOWRIT ("myedit.txt", &memofld)

RUN (editor + " myedit.txt")REPLACE &memofld WITH MEMOREAD ("myedit.txt")RETURN 0 // success

ELSERETURN -1 // error

ENDIF

CMD 13

Example:Start MS-Word (Winword) in Windows as sub-process, continue processing of theapplication. Note the notification of path and/or file name including spaces: theexecutable (with path) and/or the file name needs to be passed to Windowsenclosed in double quotas. When the command uses variables, enclose it inparentheses.

? "Invoking MS-Word as separate process..."RUN NOWAIT '"C:\Programs\Microsoft Office\Office\Winword.exe" /w'WAIT "press any key to continue this application..."

// or:cDocFile := '"D:\Documens and Settings\Default User\' + ;

'My Documents\myfile.doc"'cCommand := '"C:\Program Files\Microsoft Office\' + ;

'Office\Winword.exe"'RUN NOWAIT (cCommand + " " + cDocFile)

Example:See additional examples in the RUN command.

Classification:system call

Compatibility:As opposed to the equivalent DOS execution, there are practically no limits to theuse of RUN on UNIX. If the available RAM space is insufficient, the additional swapdisk area will be used automatically. Similarly works also Windows NT..XP.

Keep in mind the differences in system command names on DOS and UNIX (lsinstead of DIR etc.) and the different DOS vs. UNIX screen handling. For portability,#ifdef FlagShip... #else...#endif or the PUBLIC FLAGSHIP variable can be used tocompile platform specific code selectively.

The MESSAGE clause is new in FS4, WAIT/NOWAIT in FS6 and both are notavailable in Clipper.

Translation:__RUN (expC)

Related:RUN, REFRESH

CMD 14

* && // /*...*/ NOTESyntax:

NOTE [<text>]or:

* [<text>]or:

[<command>] && [<text>]or:

[<command>] // [<text>]or:

[<command>] /* [<text>] */ [<command>]Purpose:

Various kind of program comments: full-line, in-line and special comments.

Arguments:<text> is a character string ending with a new line.

Description:NOTE and * at beginning of the source line (leading spaces and TABs are notsignificant) marks the whole line as a (full-line) comment.

A double ampersand (&&) or double slashes (//) can be placed after the command,if there is one on the same line, the text followed && or // is a user comment, notevaluated by the compiler. Slash + star (/*) marks all following text as comment untilstar + slash (*/) is detected. This comment can continue over new lines and isaccepted within an expression.

A full-line or inline comment cannot be continued in a new line with a semicolon.

Example:************** Comment **************a = b && Inline comment,a = b + ; && usable also for

c + d && continued statement

NOTE That is an comment line,NOTE same as these* or these line.* The &macro will be not evaluated// and commands (e.g. @ 5,1 CLEAR) not executed.

REPLACE name WITH var_name, ; // Inline-zip WITH VAL(zip_var) // comment

USE address/* here starts aspecial comment, continuedon several lines */

USE /* means open a database address.dbf: */ address

CMD 15

/* Command SELECT will be executed: */ SELECT 5// Command SELECT will be not executed: SELECT 5&& Command SELECT will be not executed: SELECT 5* Command SELECT will be not executed: SELECT 5

/* this commentis continuedover several lines */

value = am /* amount */ + tx /* plus tax */

Classification:programming

Related:#comment, #nocomment

CMD 16

? | ??Syntax:

? [<expList>]? [SPLIT | COLUMN [<expN5>,<expN6>]]

[COLOR <expC1>][GUICOLOR <expC2>][PRINTCOLOR <expC3>][FONT <expO4>] [FONT FontNew(...)]<expList>

Syntax:?? [<expList>]?? [SPLIT | COLUMN [<expN5>,<expN6>]]

[COLOR <expC1>][GUICOLOR <expC2>][PRINTCOLOR <expC3>][FONT <expO4>] [FONT FontNew(...)]

<expList>Purpose:

Evaluates and displays the results of one or more expressions to the console or toGUI printer.

Arguments:<expList> is a list of values or expressions to be evaluated and displayed. If thereare more than one expression, the expressions must be separated by commas. Theexpressions can be of any data type, including memos.

If no <expList> argument is specified in the ? command, a NEW LINE code is sentto the console. If the ?? command is used without <expList>, nothing happens.

Options:SPLIT will split long string into two or more lines. The available size is calculatedfrom current Col() position up to MaxCol() for current line and MaxCol() -1 forsubsequent lines. If PrintGui(.T.) is active or SET GUIPRINT is ON,oPrinter:GuiMaxCol() is used instead. The string is splitted at the left next space ortab or dash if any. You may add conditional split position (separators) by chr(1) orchr(247), which are then interpreted as dash at line end and ignored otherwise.

COLUMN <expN5>,<expN6> or SPLIT <expN5>,<expN6> is similar to SPLIT, butinstead of full line, it will split the large text column-wise, from column <expN5> to<expN6> (in row/cols). Note that <expList> may contain only single character stringor expression. See example in <FlagShip_dir>/examples/printergui.prg

COLOR <expC1> specifies the color for displaying the <expList> data. Only thefirst color pair (standard) is significant. If this clause is not given, the current colorsetting is used. In GUI mode, first the GUICOLOR clause is checked. If not set, the

CMD 17

COLOR <expC1> or the current color is used, but only when SET GUICOLOR isON. Specifying COLOR and GUICOLOR allows you to handle different colors forGUI and Terminal mode, without switching the SET COLOR and SET GUICOLORsetting.

GUICOLOR <expC2> specifies the color for displaying the <expList> dataconsidered in GUI mode. Only the first color pair (standard) is significant. Instead ofstring, you also may use RGB triplets (or stringified triplets), see SET COLOR fordetails, and example below. If GUICOLOR is set, this color is used in GUI moderegardless the current SET GUICOLOR on/off. If omitted and SET GUICOLOR isON, either the COLOR <expC1> is used if given, or the current SetColor() is used.The GUICOLOR clause apply for GUI mode only, and is ignored otherwise.

PRINTCOLOR <expC3> specifies the color for printing. If not given, GUICOLOR isused also for printer. Considered only in GUI mode when SET GUIPRINT is ON orwith PrintGui(.T.), and ignored otherwise.

FONT <expO4> is a font specification, considered only for screen and/or SETGUIPRINT output in GUI mode and ignored otherwise. The <expO3> is alreadyinstantiated font object, which allows you to set the font/family name, size andadditional attributes like bold, underscore, italic and so on, independent on thecurrent SET FONT setting. Alternatively, instead of <expO4>, you may instantiatefont directly, by specifying e.g. FONT FontNew("courier",12,"BI"). Note that theCol() is adapted automatically to a larger/smaller font size but the Row() only whenSET ROWADAPT is ON (default is OFF). You may force the adaption manually byinvoking RowAdapt().

Description:The displayed results of the expressions are separated by a space character. The ?command outputs a linefeed (the NEW LINE code) before displaying theexpressions.

The ?? command omits the linefeed and thus allows you to display multipleexpressions on one line continuing the previous output at the current screen orprinthead position.

FlagShip supports echoing of console commands (see LNG.5.1.1) to four differentdevices/files at a time: to the default SCREEN device, and additionally to thePRINTER, ALTERNATE, and EXTRA text files or devices. Each of these SETcommands can be enabled/disabled using the ON/OFF switch; the PRINTER,ALTERNATE and EXTRA output can be redirected to any file or device using theSET...TO option. SET CONSOLE OFF can be used to suppress displaying to thescreen without affecting output to the echoed device or text file.

After completing the ? / ?? command, the cursor or printhead is located one positionto the right of the last character displayed. ROW() and COL() are updated to reflectthe new cursor position. With SET PRINTER ON, PROW() and PCOL() are alsoupdated with the new printhead position. When a different than the standard FONTis used, you may force the ROW() setting to correspond to the used font in theoutput either by the global switch SET ROWADAPT ON, or by invoking RowAdapt()

CMD 18

thereafter. To align output using different fonts on the same base line, use SETROWALIGN BASELINE.

To format any of the specified expressions, TRANSFORM() or a user- definedfunction can be used. If you need to pad a variable length value for columnalignment, you can use any of the PAD() functions to left-justify, right-justify, orcenter the value.

Terminal i/o mode: If the output from ? or ?? command reaches the edge of thescreen as reported by MAXCOL(), it wraps to the next line. If the output reaches thebottom of the screen as reported by MAXROW(), normally the screen scrolls up oneline.

In GUI mode, you may include RichText/HTML tags into the output string and eitheruse SET HTMLTEXT ON or preface the string by "<HTML>" to interpret the tags.See more in SET HTMLTEXT.

Note: to display array elements, either specify the element (e.g. ? myarray[5,3]), oruse separate Aeval() or _DisplArrStd() function. To display object properties, eitherspecify ? myObj:objInstance or ? myObj:objMethod(), or use _DisplObjStd()

Example:* This will be displayed on separate lines? "First line"? "Second line"

* This will be displayed on the same line with different colors? "Today is", CDOW(DATE()), " " COLOR "R+/B" GUICOLOR "R+/W"?? DATE()

oFont := Font{"Arial",150}oFont:Bold := .T.? "Big!" FONT oFont COLOR "B" GUICOLOR "B+"RowAdapt() // adapt current Row() setting to larger fontwait

Example:#include "color.fh"? "hello light blue on std. GUI Windows background" ;

COLOR "B+/N" ; // Terminal modeGUICOLOR {{0,0,255},{RGBCOLOR_BG_WINDOWS}} // GUI mode

? "hello dark red on std. GUI background (Windows or Linux)" ;GUICOLOR ("R/" + RGBSTRING_BG) COLOR ("R/N")

Classification:sequential screen output (SET CONSOLE ON) sequential printer output (SETPRINTER ON) sequential file output (SET EXTRA|ALTERNATE ON)

CMD 19

Compatibility:FS4 and later supports embedded zero bytes by default. The COLOR andGUICOLOR clause is available in FS5 and later, SPLIT and PRINTCOLOR sinceVFS7.

Translation: see also std.fh file? => QOUT (exp1 [, exp2 ...] )?? => QQOUT (exp1 [, exp2 ...] )

? COLOR/GUICOLOR/PRINTCOLOR/FONT=> QOUT6 (col,guiCol,font,prCol,,,exp1 [,exp2 ...])

?? COLOR/GUICOLOR/PRINTCOLOR/FONT=> QQOUT6(col,guiCol,font,prCol,,,exp1 [,exp2 ...])

?? SPLIT/COLOR/GUICOLOR/PRINTCOLOR/FONT=> QsplitText(exp,c1,c2,,font,col,guiCol,prCol,,.T.)

Related:@...SAY, @..DRAW, TEXT, COL(), ROW(), SET CONSOLE, SET ALTERNATE,SET EXTRA, SET HTMLTEXT, SET ROWADAPT, SET ROWALIGN, SETPRINTER, PrintGui()

CMD 20

?# | ??# | ??##Syntax:

?# [<expList>]Syntax:

??# [<expList>]Syntax:

??## [<expList>]Purpose:

Evaluates and displays the results of one or more expressions to the standard errordevice (stderr, usually console).

Arguments:<expList> is a list of values or expressions to be evaluated and displayed. If thereare more than one expression, the expressions must be separated by commas. Theexpressions can be of any data type, including memos.

If no argument is specified and the ?# command is used, a NEWLINE code is sentto stderr.

Description:This command is often used for debugging purposes, where

?# ... is similar to ? or Qout() and prints NewLine + text to stderr, same as the Cstatement fprintf(stderr,"\n...")

??# ... is similar to ?? or Qqout() and prints text to stderr, same as the C statementfprintf(stderr,"...")

??##... is similar to ?# but print text + NewLine to stderr, same as the usual Cstatement fprintf(stderr,"...\n")

The commands SET CONSOLE, SET ALTERNATE, SET FILE, SET PRINTER arenot affected here and are also not considered.

Redirection: you may redirect this stderr output to a file (here named 'myfile') at thetime of invoking your application 'myapp' (with optional command-line arguments):

•in Unix/Linux using sh, ksh, bash shell:myapp [cmd-line arguments] 2>myfile #overwrites myfilemyapp [cmd-line arguments] 2>>myfile #appends to myfile

•in Unix/Linux using csh, tcsh shell:( myapp [cmd-line arguments] >/dev/tty ) >& myfile #overwrites( myapp [cmd-line arguments] >/dev/tty ) >>& myfile #appends

•in MS-Windows:myapp [cmd-line arguments] 2>myfile #overwrites myfilemyapp [cmd-line arguments] 2>>myfile #appends to myfile

CMD 21

In Unix/Linux, the 'myfile' may also be any device of your choice, e.g. /dev/lpt0 or/dev/pts/12. In Windows, you may redirect it to printer by specifying e.g. PRN: orLPT2: for 'myfile'.

If no start-up/command-line redirection was specified, the ?[?#]# output appears inGUI mode on the console screen, in terminal and basic i/o mode intermixed with thestandard ?, ?? and @... output.

Example:? "Hello world"?# "hello from stderr"?# procstack(), "reaching at", time()

Compatibility:New in FS5.

Related:?, ??, OutErr(), OutStd(), Qout(), Qqout()

CMD 22

@...Syntax:

@ <expN1>, <expN2>[PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN5>)]

Purpose:Clears to the end of line.

Arguments:<expN1> and <expN2> are the starting row and column coordinates to clear.

PIXEL : the <expN1>, <expN2> are values in pixel

NOPIXEL : the <expN1>, <expN2> are row/col values

If [PIXEL|NOPIXEL] is not specified: the current SET PIXEL status is used. PIXELis shortcut for UNIT=PIXEL, NOPIXEL is shortcut for UNIT=ROWCOL

UNIT=ROWCOL or PIXEL or MM or CM or INCH or DOT or <expN5> specifies unitfor <expN1> .. <expN4> coordinates. The <expN5> is parenthesed numeric value inrange 0 to 5 (i.e. UNIT_ROWCOL to UNIT_DOT). If the UNIT=... clause is notspecified, default is row/col, or the current setting by set(_SET_PIXEL, log) orset(_SET_COORD_UNIT, num). Apply for GUI mode only, ignored otherwise.

Description:This command is used to clear the rest of the line <expN1> beginning at column<expN2>.

In GUI mode, if there is a (part of) widget in the cleared area, the widget is clearedas well, see also LNG.5.3.

After executing the command, the cursor (and ROW(), COL()) is set to <expN1>,<expN2>.

Example:@ 10,15 // clear from 10,15 to eol@ 11,0 // clears whole line 11

Classification:screen oriented output, buffered via DISPBEGIN()..DISPEND()

Translation:SCROLL (expN1, expN2, expN1) ; SETPOS (expN1, expN2)

Related:@...CLEAR, @...CLEAR TO, CLEAR, LNG.5.3

CMD 23

@...BOXSyntax:

@ <expN1>,<expN2>,<expN3>,<expN4>BOX [<expC5>]

[COLOR <expC6>][GUICOLOR <expC7>] [PRINTCOLOR <expC8>][LINEWIDTH <expN9>][SUNKEN|RAISED|PLAIN][FRAMEONLY][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|

(<expN10>)]Syntax:

@ <expN1>,<expN2>,<expN3>,<expN4>GUI BOX [<expC5>]

[COLOR <expC6>][GUICOLOR <expC7>] [PRINTCOLOR <expC8>][LINEWIDTH <expN9>][SUNKEN|RAISED|PLAIN][FRAMEONLY][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|

(<expN10>)]Syntax:

@ <expN1>,<expN2>,<expN3>,<expN4>TERM BOX [<expC5>]

[COLOR <expC6>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|

(<expN10>)]Purpose:

Draws a customized box on the screen.

Arguments:GUI BOX the box is driven only in GUI mode and ignored otherwise TERM BOX thebox is driven only in Terminal mode and ignored otherwise.

<expN1...expN4> are the coordinates, upper, left, lower, and right respectively. Therow coordinates can range from zero to 24, and the column coordinates can rangefrom zero to 79 (or MAXROW() and MAXCOL() respectively, depending on theused terminfo description or the set screen size. In GUI mode, the coordinatesspecify mid of the character so the look-and-feel is comparable to Terminal i/omode; to set the coordinate exactly at pixel value, use the PIXEL clause (or enable

CMD 24

SET PIXEL ON). In GUI mode, you may use numeric values with decimal fractionsfor row and column, which are then rounded to integer if Terminal i/o mode is used.

<expC5> is a character string containing eight border characters and one fillcharacter. The first character is used for the upper left-hand corner, the next for theupper line, and so on, the clockwise. The box is filled with the ninth character. If<expC5> is a variable named same as the significant part of BOX clauses, e.g.FRAM*, COLO*, LINE*, SUNK* etc, enclose the variable in parentheses to avoidconfusions. If <expC5> is not specified, the default value is taken from globalvariable _aGlobSetting[GSET_T_C_AT_TO_SINGLE] or _aGlobSetting [GSET_T_C_AT_TO_DOUBLE] defined in initio.prg. The border is always applicable inTerminal i/o but in GUI mode only if neither LINEWIDTH nor SUNKEN, RAISED,PLAIN was specified and SET GUITRANSL BOX is ON, or the GUI clause is used.

COLOR <expC6> is an optional color specification (according to SET COLOR). Ifnot specified, the box is drawn using the current color setting. Only the first colorpair is used. The frame is drawn by foreground/background, the box is filled by thebackground color. Apply for Terminal i/o. Apply also for GUI mode when SETGUICOLOR is ON, otherwise the GUICOLOR clause is used.

GUICOLOR <expC7> is an optional color specification (according to SET COLOR).If not specified, the box is drawn using the current color setting. Only the first colorpair is used. The frame is drawn by foreground/background, the box is filled by thebackground color. Apply for GUI mode only and overrides the optional COLORclause. If not specified, the default color is used to fill the box area, except theFRAMEONLY clause was given.

PRINTCOLOR <expC8> is an optional color specification (according to SETCOLOR) for GUI/GDI printout by SET GUIPRINT ON. Only the first color pair(foreground or foreground/background) is considered. If not given, GUICOLOR isused also for printer, but with foreground only.

LINEWIDTH <expN9> is optional line width (in pixel) of the frame used in GUImode, overrides the <expC5> setting. If the argument is 0, no frame is drawn, onlybackground color is filled. When LINEWIDTH is not specified, and neither SUNKEN,RAISED, PLAIN or FRAMEONLY is used, the frame is drawn by the <expC5>characters.

SUNKEN : creates 3-dim panel with sunken effect, ignores foregr.color

RAISED : creates 3-dim panel with raised effect, ignores foregr.color

PLAIN : draws plain (2-dimensional) box frame using foreground color

These three clauses apply for GUI mode and overrides <expC5>. All are ignored inTerminal i/o mode.

FRAMEONLY : draw the sunken/raised/plain box frame but don't fill the inside boxarea by COLOR or GUICOLOR; the current screen content within the box arearemain visible.

PIXEL : the <expN1> .. <expN4> are values in pixel

CMD 25

NOPIXEL : the <expN1> .. <expN4> are row/col values


UNIT=ROWCOL or PIXEL or MM or CM or INCH or DOT or <expN10> specifiesunit for <expN1> .. <expN4> coordinates. The <expN10> is parenthesed numericvalue in range 0 to 5 (i.e. UNIT_ROWCOL to UNIT_DOT). If the UNIT=... clause isnot specified, default is row/col, or the current setting by set(_SET_PIXEL, log) orset(_SET_COORD_UNIT, num). Apply for GUI mode only, ignored otherwise.

Description:The command @...BOX is used for drawing boxes using a configurable border andfilling it with a specified character. After @...BOX is executed, the cursor andROW(), COL() are set into the boxed region at <expN1> +1, <expN2> +1.

In GUI mode, you may:•use sunken, raised or plain box frame, when SUNKEN, RAISED, PLAIN,

FRAMEONLY or LINEWIDTH clause is specified. The background color ofGUICOLOR is considered, filling character of <expC5> is ignored.

•use the semi-graphic characters in <expC5>, simulated via line drawing, whenSET GUITRANSL BOX is ON, or the GUI clause was specified, and no SUNKEN,RAISED, PLAIN, FRAMEONLY, LINEWIDTH clauses was given. The backgroundcolor and filling character in <expC5> is ignored, since almost unwanted resultsoccurs with proportional fonts. This is the "old", backward compatible syntax.

In Terminal i/o mode, the box is always drawn by the <expC5> chars. The optionalSUNKEN, RAISED, PLAIN, LINEWIDTH, GUICOLOR, FRAMEONLY and PIXELclauses are ignored. The color set by COLOR clause, as well as the fill character of<expC5> are considered.

Note that @...BOX does not create new widget (control) but draws a rectangle filledby the specified color directly in the user window (or in current sub-window). Itframe may therefore be overwritten by subsequent @..SAY, ?, ?? or Qout() output.If you wish to create new widget (sub-window) with protected frame, use eitherWopen() from the FS2 Toolbox, or it subset MDIopen() for MDI based GUIapplication.

The @..BOX command is processed also for GUI/GDI printout (when SETGUIPRINT ON is active) and accepts only PRINTCOLOR, LINEWIDTH, PIXEL andUNIT= clauses, other (incl. <expC5>) are ignored.

An alternative to @..BOX in GUI mode is @..DRAW RECTANGLE which does notrequire GUITRANSL BOX ON and optionally draws rounded rectangle.

CMD 26

Example:* Draw box with standard or extended ASCII char set:** ########################################################* ###+----------+#####╔═══════════╗########┌──────────┐###* ###| |#####║xxxxxxxxxxx║########│##########│###* ###| |#####║xxxxxxxxxxx║########│##########│###* ###+----------+#####╚═══════════╝########└──────────┘###* ########################################################*

// SET GUITRANSL BOX ON// SET GUICOLOR ON#include "box.fh" // for B_DOUBLE and B_SINGLE

filler1 = "+-+|+-+| " // filler2 = replicate(chr(219), 8) + "x"filler2 = chr(201, 205, 187, 186, 188, 205, 200, 186) + "x"filler3 = chr(218, 196, 191, 179, 217, 196, 192, 179)

@ 1, 8,15,79 BOX replicate("#", 9) // Background@ 3,10,14,20 BOX filler1 // Box 1@ 3,30,14,50 BOX B_DOUBLE + "x" // Box 2@ 3,60,14,78 BOX filler3 COLOR "R+/B" // Box 3@ 16,60,20,78 BOX B_SINGLE // Box 3

Example:// Draw double-line box in Terminal i/o mode and raised box// panel in GUI mode with thick frame, fill by red background.

#include "box.fh"@ 2,10,20,72 BOX B_DOUBLE COLOR "N/R" ;

RAISED LINEWIDTH 4 GUICOLOR "N/#FF6464"

Example:See <FlagShip_dir>/examples/boxcommand.prg for additional examples

Include:The #include file "box.fh" contains predefined PC-8 border character combinations.

Classification:screen oriented output, buffered via DISPBEGIN()..DISPEND() as well as GUIprintout

Compatibility:The physical output on the screen depends on the terminal description selected(environment variable TERM), the ability of the terminal to output mapping appliedvia FSchrmap.def. See also LNG.5.1.4, section SYS, and FS_SET ("outmap")

Defaults for <expC5> in initio.prg, and LINEWIDTH, PIXEL|NOPIXEL, GUICOLOR,SUNKEN|RAISED|PLAIN clauses are new in FS5

GUI printout (by SET GUIPRINT ON) is available in GUI mode only.

CMD 27

Translation:DISPBOX (expN1, expN2, expN3, expN4, expC5, [color], [lPixel],

[lGUI], [GuiColor], [nPlainMode], [nLineWidth], [lFrame],[PrintColor] )

Related:@..DRAW RECTANGLE, @...CLEAR, @...TO, LNG.5.3

CMD 28

@...CLEARSyntax:

@ <expN1>,<expN2> CLEAR[TO <expN3>,<expN4>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN5>)]

Purpose:Clears a screen region.

Arguments:<expN1> and <expN2> are the row and column coordinates of the upper leftcorner. In GUI mode, you may use numeric values with decimal fractions for rowand column, which are then rounded to integer if Terminal i/o mode is used.

Options:TO <expN3> and <expN4> are the row and column coordinates of the lower rightcorner. If this option is not specified, the screen is cleared from the specified upperleft corner to 24,79 (or MAXCOL() and MAXROW() respectively), as specified in theterminfo description used.





Description:This command can be used to clear a rectangular region of the screen by filling itwith space characters of the current color setting.

After @...CLEAR erases the designated region, the cursor is positioned in theupper left corner of the cleared region at <expN1> and <expN2>. In GUI mode, ifthere is a (part of) widget in the cleared area, the widget is erased as well. ROW()and COL() coordinates are updated to reflect the new cursor position.

In Terminal i/o mode, the screen background corresponds to the standard colorpair, set by SetColor() or SET COLOR TO command.

In GUI mode, the background color (assigned by SET COLOR) is set only whenSET GUICOLOR is ON (default is OFF - according to GUI design specs). You mayset the background also explicitly by invoking SetColorBackground(cColor) followedby CLS, CLEAR SCREEN, Scroll() or @ ... CLEAR [TO..]

CMD 29

Example:LOCAL scrscr = SAVESCREEN (10,10,20,60)@ 10,10 CLEAR TO 20,60@ 10,10 TO 20,60 DOUBLE** additional output in the window*RESTSCREEN (10,10,20,60,scr)

Classification:screen oriented output, in terminal i/o mode buffered via DISPBEGIN()..DISPEND()

Compatibility:FS5: [PIXEL|NOPIXEL] clause is new

Translation:SCROLL (expN1, expN2 [, expN3, expN4] )SETPOS (expN1, expN2)

Related:@...BOX, @...TO, CLEAR, RESTSCREEN(), SAVESCREEN(), LNG.5.3

CMD 30

@...DRAW ARCSyntax 1:

@ <expN1>,<expN2> [GUI]DRAW ARC RADIUS <expN3> ANGLE <expN5>,<expN6>[COLOR <color>][GUICOLOR <color>][PRINTCOLOR <expC7>][LINEWIDTH <expN8>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN9>)]

#Syntax 2:@ <expN1>,<expN2>, <expN3>,<expN4> [GUI]

DRAW ARC ANGLE <expN5>,<expN6>[COLOR <color>][GUICOLOR <color>][PRINTCOLOR <expC7>][LINEWIDTH <expN8>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN9>)]

Purpose:Draws circle or ellipse part in GUI mode, specified by radius or bounding rectangle.

Arguments Syntax 1:<expN1>, <expN2> are row/col or y/x coordinates of the circle center in specified ordefault <units>.

RADIUS <expN3> is the circle radius in specified or default <units>. With row/colsunit, <expN3> is assumed as (fractional) number of columns.

ANGLE <expN5>,<expN6> are the start angle and the arc length in positive ornegative degrees (-360..0..360). Positive values mean counter-clockwise whilenegative values mean the clockwise direction. Zero degree of <expN5> is at the 3o'clock position, the 12 o'clock position is either 90 or -270. The arc length <expN6>is the drawn part of circle or ellipse in positive or negative degrees starting at<expN5>. The direction is clockwise when both <expN5> and <expN6> are positiveor negative, or counter-clockwise otherwise, see also example below.

Arguments Syntax 2:<expN1>, <expN2> are top left row/col or y/x coordinates of the bounding rectanglein specified or default <units>.

<expN3>, <expN4> are bottom right row/col or y/x coordinates of the boundingrectangle in specified or default <units>. If the bounding rectangle (calculated inpixels) is quadratic, circle arc is drawn.

CMD 31

ANGLE <expN5>,<expN6> are the start angle and the arc length in positive ornegative degrees (or degree fractions), same as in Syntax 1 above.

Options:COLOR <color> or GUICOLOR <color> is optional color specification. The circleor ellipse arc is drawn by foreground color in width of <expN8> pixel, backgroundcolor is ignored.

PRINTCOLOR <expC7> specifies the color for printing by SET GUIPRINT ON, orwith PrintGui(.T.). The circle or ellipse arc is drawn by foreground color. IfPRINTCOLOR is not given, GUICOLOR is used also for printer.

LINEWIDTH <expN8> is the line width of the circle or ellipse arc in pixels. If notgiven, line width of 1 pixel is used.

PIXEL : the <expN1>..<expN4> are values in pixel

NOPIXEL : the <expN1>..<expN4> are row/col values



Description:@...DRAW ARC draws parts of ellipse or circle specified by rounding rectangle orcircle radius on screen and/or printer in GUI mode. It is processed also for GUI/GDIprintout (when SET GUIPRINT ON or PrintGui(.T.) is active).

The row() and col() values are set accordingly to draw end.

To draw full circle or ellipse, @..DRAW CIRCLE or @..DRAW ELLIPSE may beused instead which supports also filling color. The @..DRAW PIE command isanother alternative to @..DRAW ARC.

Tuning:In GUI mode, drawing graphic lines sometimes requires refresh. If your displayflickers, you may disable the refresh by assigning _aGlobSetting[GSET_G_N_REFRESHDRAW] := -1 // default = 300 ms

Example:@ 5,15, 11,20 DRAW ARC ANGLE -90, 180 LINEW 2 // ")"@ 5,25, 11,30 DRAW ARC ANGLE 90,-180 LINEW 2 // ")"@ 5,35, 11,40 DRAW ARC ANGLE 90, 180 LINEW 2 // "("@ 5,45, 11,50 DRAW ARC ANGLE -90,-180 LINEW 2 // "("@ 5,55, 11,60 DRAW ARC ANGLE 0, 90 LINEW 2 // ")" top@ 5,57, 11,62 DRAW ARC ANGLE 0, -90 LINEW 2 // ")" bott

CMD 32

@ 15,10 DRAW ARC RADIUS 4 ANGLE -90, 180 GUICOLOR "B+" // ")"@ 15,20 DRAW ARC RADIUS 4 ANGLE 90,-180 GUICOLOR "N" // ")"@ 15,30 DRAW ARC RADIUS 4 ANGLE 90, 180 GUICOLOR "R+" // "("@ 15,40 DRAW ARC RADIUS 4 ANGLE -90,-180 GUICOLOR "G+" // "("@ 15,50 DRAW ARC RADIUS 4 ANGLE 0, 90 GUICOLOR "R+" // ")" top@ 15,52 DRAW ARC RADIUS 4 ANGLE 0, -90 GUICOLOR "G+" // ")" bott

Example:See complete example in <FlagShip_dir>/examples/printergui.prg

Classification:screen oriented output in GUI mode, GUI printout

Compatibility:New in FS7, not available in Clipper nor in FoxPro.

Translation: in std.fhGuiDrawArc(...)

Related:@..DRAW CIRCLE, @..DRAW ELLIPSE, @..DRAW PIE, @..DRAW LINES,@..DRAW IMAGE, @..DRAW POLYON, @..DRAW RECTANGLE, @...BOX,@...TO.., SET GUIPRINT, PrintGui()

CMD 33

@...DRAW CIRCLESyntax:

@ <expN1>,<expN2> [GUI]DRAW CIRCLE RADIUS <expN3>[COLOR <color>][GUICOLOR <color>][PRINTCOLOR <expC5>][LINEWIDTH <expN6>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN7>)]

Purpose:Draws a circle in GUI mode (ignored in Terminal i/o) of specified radius, color andline width, optional fill.

Arguments:<expN1, expN2> are row/col or y/x coordinates of the circle center in specified ordefault <units>.


Options:COLOR <color> or GUICOLOR <color> is optional color specification. The circle isdrawn by foreground color in width of <expN6> pixel, and filled by background color(if such given). To draw circle in mono color, use the same color for foreground andbackground.

PRINTCOLOR <expC5> specifies the color for printing by SET GUIPRINT ON, orwith PrintGui(.T.). The circle is drawn by foreground and filled by background color.If PRINTCOLOR is not given, GUICOLOR is used also for printer.

LINEWIDTH <expN6> is the line width of the circle in pixels. If not given, line widthof 1 pixel is used.

CMD 34

Description:@...DRAW CIRCLE draws a circle of specified radius (the diameter is twice of theradius) on screen and/or printer in GUI mode. This command is processed also forGUI/GDI printout (when SET GUIPRINT ON or PrintGui(.T.) is active).


To draw circle fragments, use @..DRAW ARC or @..DRAW PIE instead. To drawcircle specified by bounding rectangle, use @..DRAW ELLIPSE.

Tuning:In GUI mode, drawing graphic lines sometimes requires refresh. If your displayflickers, you may disable the refresh by assigning

_aGlobSetting[GSET_G_N_REFRESHDRAW] := -1 // default = 300 ms

Example:@ 13, 15 DRAW CIRCLE RADIUS 5 // diameter is 10 columns@ 13, 25 DRAW CIRCLE RADIUS 5.6 GUICOLOR "R+/G+" LINEWIDTH 3@ 8.3,5.5 DRAW CIRCLE RADIUS 2.4 GUICOLOR "RG+/RG+" UNIT=CM




Translation: in std.fhGuiDrawCircle(...)

Related:@..DRAW ELLIPSE, @..DRAW ARC, @..DRAW PIE, @..DRAW LINES,@..DRAW POLYON, @..DRAW IMAGE, @..DRAW RECTANGLE, @...BOX,@...TO.., SET GUIPRINT, PrintGui()

CMD 35

@...DRAW ELLIPSESyntax:

@ <expN1>,<expN2>, <expN3>,<expN4> [GUI]DRAW ELLIPSE[COLOR <color>][GUICOLOR <color>][PRINTCOLOR <expC5>][LINEWIDTH <expN6>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN7>)]

Purpose:Draws ellipse or circle (specified by bounding rectangle) in GUI mode, optional fillby specified color.

Arguments:<expN1>, <expN2> are top left row/col or y/x coordinates of the bounding rectanglein specified or default <units>.

<expN3>, <expN4> are bottom right row/col or y/x coordinates of the boundingrectangle in specified or default <units>.

Options:COLOR <color> or GUICOLOR <color> is optional color specification. The ellipse(or circle) is drawn by foreground color in width of <expN6> pixel, and filled bybackground color (if such given). To draw it in mono color, use the same color forforeground and background.

PRINTCOLOR <expC5> specifies the color for printing by SET GUIPRINT ON, orwith PrintGui(.T.). The ellipse or circle is drawn by foreground and filled bybackground color. If PRINTCOLOR is not given, GUICOLOR is used also forprinter.

LINEWIDTH <expN6> is the line width of the ellipse or circle in pixels. If not given,line width of 1 pixel is used.

CMD 36

Description:@...DRAW ELLIPSE draws ellipse on screen and/or printer in GUI mode. If thebounding rectangle (calculated in pixels) is quadratic, circle is drawn. Thiscommand is processed also for GUI/GDI printout (when SET GUIPRINT ON orPrintGui(.T.) is active).


To draw ellipse or circle fragments, use @..DRAW ARC or @..DRAW PIE instead.To draw circle specified by it radius, use @..DRAW CIRCLE.



Example:@ 10,10,20,20 DRAW ELLIPSE // ellipse, not a circlerSize := pixel2row(col2pixel(10)) // = 10 columns into rows@ 10,30,10+rSize,40 DRAW ELLIPSE // circle@ 100,50,150,100 DRAW ELLIPSE GUICOLOR "R+/RG+" UNIT=MM // circle




Translation: in std.fhGuiDrawEllipse(...)

Related:@..DRAW CIRCLE, @..DRAW ARC, @..DRAW PIE, @..DRAW LINES, @..DRAWPOLYON, @..DRAW IMAGE, @..DRAW RECTANGLE, @..BOX, @...TO.., SETGUIPRINT, PrintGui()

CMD 37

@...DRAW IMAGESyntax 1:

@ <expN1>, <expN2>, [<expN3>], [<expN4>]DRAW IMAGE[USING] <expC5>[SCALE] [CLIP|NOSCALE][IMGTYPE <expC7>][BORDER|FRAME <expN8>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN9>)]

Syntax 2:@ <expN1>, <expN2>, [<expN3>], [<expN4>]

DRAW IMAGE[FROM] FILE <expC6>[SCALE] [CLIP|NOSCALE][IMGTYPE <expC7>][BORDER|FRAME <expN8>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN9>)]

Purpose:Display bitmap image at specified screen position. Applicable in GUI mode only,ignored otherwise.

Syntax 1 uses image data stored in database or character variable, Syntax 2 readsthe image from file.

Arguments:This command and it arguments is fully equivalent to @...SAY IMAGE, see detaileddescription there.

Description:This command displays bitmap image at specified position in GUI mode, consideredalso by GUI/GDI printout (when SET GUIPRINT ON or PrintGui(.T.) is active). Thisis an alternative syntax for the @...SAY IMAGE command, see the full descriptionthere.

Example:#include "box.fh"@ 10,40 DRAW IMAGE file "myimg.gif"cImgVar := "..\images\otherimage.bmp"@ 15,50,18 DRAW IMAGE from file (cImgVar)@ 350,500,480,600 SAY IMAGE file myimg.jpg PIXEL NOSCALE

local cImgData := memoread("../images/myimg.png")@ 10,40, ,20 DRAW IMAGE cImgData SCALE border BOX_SUNKEN

CMD 38

Example:see also <FlagShip_dir>/examples/images.prg and printergui.prg foradditional examples

Classification:screen oriented output in GUI mode as well as GUI printout

Compatibility:New in FS7

Translation:DispImageData() or DispImageFile()

Related:@..DRAW CIRCLE, @..DRAW ELLIPSE, @..DRAW ARC, @..DRAW LINES,@..DRAW PIE, @..DRAW POLYON, @..DRAW RECTANGLE, @...BOX, @...TO..,SET GUIPRINT, PrintGui(), MemoCode(), MemoDecode()

CMD 39

@...DRAW LINESyntax 1:

@ <expN1>,<expN2> [GUI]DRAW [LINES] [TO] <expN3>,<expN4>[COLOR <color>][GUICOLOR <color>][PRINTCOLOR <expC5>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN6>)][WIDTH <wpix> | LINEWIDTH <wpix>]

Syntax 2:@ [GUI] DRAW [LINES] [TO] <expN3>,<expN4>

[COLOR <color>][GUICOLOR <color>][PRINTCOLOR <expC5>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN6>)][WIDTH <wpix> | LINEWIDTH <wpix>]

Purpose:Draws a line in GUI mode (ignored in Terminal i/o) of specified width.

Arguments:<expN1...expN4> are the start and end coordinates of the drawn line With Syntax2, the line drawing is continued from the current position. You may use numericvalues with decimal fractions for row and column, or the PIXEL clause (or SETPIXEL ON) to set the pen exactly at specified pixel position relative to the userscreen.

Options:COLOR <color> or GUICOLOR <color> is optional color specification. Only theforeground color is considered.

PRINTCOLOR <expC5> specifies the color for printing. If not given, GUICOLOR isused also for printer. Considered only in GUI mode when SET GUIPRINT is ON, orwith PrintGui(.T.), and ignored otherwise.




UNIT=ROWCOL or PIXEL or MM or CM or INCH or DOT or <expN6> specifies unitfor <expN1> .. <expN4> coordinates. The <expN6> is parenthesed numeric value inrange 0 to 5 (i.e. UNIT_ROWCOL to UNIT_DOT). If the UNIT=... clause is not

CMD 40

specified, default is row/col, or the current setting by set(_SET_PIXEL, log) orset(_SET_COORD_UNIT, num). Apply for GUI mode only, ignored otherwise.

WIDTH <wpix> is the width of the drawn line in pixels

Description:@...DRAW draws a line from the start to the end coordinate (syntax 1) or from thecurrent position to the end coordinate (syntax 2). It apply for GUI mode only,ignored in other modes. The setting of SET GUITRANSL LINES is not relevanthere.

You alternatively may use @..DRAW POLYGON to draw lines specified in array ofcoordinate pairs, and optionally fills the polygon area by background color.

The @..DRAW command is processed also for GUI/GDI printout (when SETGUIPRINT ON or PrintGui(.T.) is active) and accepts only PRINTCOLOR, WIDTH,PIXEL and UNIT=... clauses, other are ignored.



Example:Draw a large "X" and "L"

@ 3, 5 DRAW TO 20,40 COLOR "B+"@ 3,40 DRAW TO 20,5 COLOR "B+"@ 3, 5 DRAW TO 20,5 COLOR "R+" WIDTH 5@ DRAW TO 20,40 COLOR "R+" WIDTH 5


Compatibility:New in FS5, not available in Clipper. GUI printout is available since VFS7.

Translation:GuiDrawLine(...)

Related:@..DRAW CIRCLE, @..DRAW ELLIPSE, @..DRAW ARC, @..DRAW PIE,@..DRAW POLYON, @..DRAW IMAGE, @..DRAW RECTANGLE, @...BOX,@...TO.., SET GUIPRINT, PrintGui()

CMD 41

@...DRAW PIESyntax 1:

@ <expN1>,<expN2> [GUI]DRAW PIE RADIUS <expN3> ANGLE <expN5>,<expN6>[COLOR <color>][GUICOLOR <color>][PRINTCOLOR <expC7>][LINEWIDTH <expN8>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN9>)]

Syntax 2:@ <expN1>,<expN2>, <expN3>,<expN4> [GUI]

DRAW PIE ANGLE <expN5>,<expN6>[COLOR <color>][GUICOLOR <color>][PRINTCOLOR <expC7>][LINEWIDTH <expN8>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN9>)]

Purpose:Draws circle or ellipse pie (i.e. closed and filled part of ellipse or circle) in GUImode, specified by radius or bounding rectangle.

Arguments Syntax 1:<expN1>, <expN2> are row/col or y/x coordinates of the circle center in specified ordefault <units>.


ANGLE <expN5>,<expN6> are the start angle and the arc length in positive ornegative degrees (-360..0..360). Positive values mean counter-clockwise whilenegative values mean the clockwise direction. Zero degree of <expN5> is at the 3o'clock position, the 12 o'clock position is either 90 or -270. The arc length <expN6>is the drawn part of circle or ellipse in positive or negative degrees starting at<expN5>. The direction is clockwise when both <expN5> and <expN6> are positiveor negative, or counter-clockwise otherwise, see also example below.

Arguments Syntax 2:<expN1>, <expN2> are top left row/col or y/x coordinates of the bounding rectanglein specified or default <units>.

<expN3>, <expN4> are bottom right row/col or y/x coordinates of the boundingrectangle in specified or default <units>. If the bounding rectangle (calculated inpixels) is quadratic, circle pie is drawn.

CMD 42

ANGLE <expN5>,<expN6> are the start angle and the arc length in positive ornegative degrees (or degree fractions), same as in Syntax 1 above.

Options:COLOR <color> or GUICOLOR <color> is optional color specification. The circleor ellipse arc and closing lines are drawn by foreground color in width of<expN8>pixel, the pie area is filled by background. To draw and fill it in mono color, use thesame color for foreground and background.

PRINTCOLOR <expC7> specifies the color for printing by SET GUIPRINT ON, orwith PrintGui(.T.). The circle or ellipse arc is drawn by foreground color and the piefilled by background. If PRINTCOLOR is not given, GUICOLOR is used also forprinter.

LINEWIDTH <expN8> is the line width of the circle or ellipse arc in pixels. If notgiven, line width of 1 pixel is used.

PIXEL : the <expN1>..<expN4> are values in pixel

NOPIXEL : the <expN1>..<expN4> are row/col values



Description:@...DRAW PIE draws parts of ellipse or circle specified by rounding rectangle orcircle radius on screen and/or printer in GUI mode. It is often used to draw piecharts by using the same coordinates and different angles. This command isprocessed also for GUI/GDI printout (when SET GUIPRINT ON or PrintGui(.T.) isactive).


To draw full circle or ellipse, @..DRAW CIRCLE or @..DRAW ELLIPSE may beused instead. The @..DRAW ARC command is another alternative to draw part ofcircles or ellipses w/o filling the area.

CMD 43

Example:@ 5,15, 11,20 DRAW PIE ANGLE -70, 140 GUICOLOR "B+/BG+" // <)@ 5,25, 11,30 DRAW PIE ANGLE 70,-140 GUICOLOR "N/W+" // <)@ 5,35, 11,40 DRAW PIE ANGLE 110, 140 GUICOLOR "R+/RG+" // (>@ 5,45, 11,50 DRAW PIE ANGLE -110,-140 GUICOLOR "G+/G+" // (>@ 5,55, 11,60 DRAW PIE ANGLE 0, 90 GUICOLOR "R+/GR+" // <) top@ 5,65, 11,70 DRAW PIE ANGLE 0, -90 GUICOLOR "G+/BG+" // <) bot

@ 15,10 DRAW PIE RADIUS 4 ANGLE -70, 140 GUICOL "B+/BG+" // <)@ 15,20 DRAW PIE RADIUS 4 ANGLE 70,-140 GUICOL "N/W+" // <)@ 15,30 DRAW PIE RADIUS 4 ANGLE 110, 140 GUICOL "R+/RG+" // (>@ 15,40 DRAW PIE RADIUS 4 ANGLE -110,-140 GUICOL "G+/G+" // (>@ 15,50 DRAW PIE RADIUS 4 ANGLE 0, 90 GUICOL "R+/GR+" // <) top@ 15,60 DRAW PIE RADIUS 4 ANGLE 0, -90 GUICOL "G+/BG+" // <) bot




Translation: in std.fhGuiDrawPie(...)

Related:@..DRAW CIRCLE, @..DRAW ELLIPSE, @..DRAW ARC, @..DRAW LINES,@..DRAW POLYON, @..DRAW IMAGE, @..DRAW RECTANGLE, @...BOX,@...TO.., SET GUIPRINT, PrintGui()

CMD 44

@...DRAW POLYGONSyntax:

@ [GUI] DRAW POLYGON <expA1>[CLOSED][COLOR <color>][GUICOLOR <color>][PRINTCOLOR <expC2>][LINEWIDTH <expN3>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN4>)]

Purpose:Draws (open or closed) polygon according to given array of coordinate pairs.Applicable in GUI mode only.

Arguments:<expA1> is a two-dimensional array of coordinates in specified or default <units>,e.g. {{row,col},{row,col},{row,col},...}. At least two coordinate pairs are required.

Options:CLOSED forces to close the polygon, i.e. the last point in <expA1> array is implicitlyconnected to the first point, and the polygon is filled by background color, if any.

COLOR <color> or GUICOLOR <color> is optional color specification. Thepolygon lines are drawn by foreground color in width of <expN6> pixel, and withCLOSED clause filled by background color. To draw the polygon in mono color, usethe same color for foreground and background.

PRINTCOLOR <expC5> specifies the color for printing by SET GUIPRINT ON, orwith PrintGui(.T.). The polygon is drawn by foreground and with CLOSED clausefilled by background color. If PRINTCOLOR is not given, GUICOLOR is used alsofor printer.

LINEWIDTH <expN6> is the line width in pixels. If not specified, line width of 1 pixelis used.

CMD 45

Description:@...DRAW POLYGON connects given coordinate points by lines; with the CLOSEDclause it also closes the polygon, and fills it by background color. It may also beused to draw line charts, see example. This command is processed also forGUI/GDI printout (when SET GUIPRINT ON or PrintGui(.T.) is active).


You alternatively may use @..DRAW LINES to draw lines, it is similar to @...DRAWPOLYGON without CLOSED clause.



Example:aCoord := {{34.5,8},{32.5,13},{34.5,18},{38,18},{38,14},{36,14}, ;

{36,12},{38,12},{38,8}}@ DRAW POLYGON (aCoord) GUICOLOR "R+/RG+" PRINTCOLOR "R+/RG+" ;

LINEWIDTH 2 CLOSED NOPIXEL

Example:See complete example in <FlagShip_dir>/examples/printergui.prg withbody of diagram chart.


Compatibility:New in VFS7, not available in Clipper nor in FoxPro.

Translation: in std.fhGuiDrawPolygon(...)

Related:@..DRAW CIRCLE, @..DRAW ELLIPSE, @..DRAW ARC, @..DRAW PIE,@..DRAW LINES, @..DRAW IMAGE, @..DRAW RECTANGLE, @..BOX, @...TO..,SET GUIPRINT, PrintGui()

CMD 46

@...DRAW RECTANGLESyntax:

@ <expN1>,<expN2>,<expN3>,<expN4> [GUI]DRAW RECTANGLE[ROUNDED <expN5>][COLOR <color>][GUICOLOR <color>][PRINTCOLOR <expC6>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN7>)][LINEWIDTH <expN8>]

Purpose:Draws rectangle (in GUI mode) optionally rounded and filled by background color.

Arguments:<expN1...expN4> are the coordinates, upper, left, lower, and right respectively,starting at 0. With the default row/col units, the coordinates specify mid of thecharacter or line.

Options:ROUNDED <expN5> is a rounding ratio (0..99) for the corners. Zero value drawsangled corners, 99 is maximum roundedness.

COLOR <color> or GUICOLOR <color> is optional color specification. Rectanglelines (and corners) are drawn by foreground color in width of <expN8> pixel, therectangle is filled by background color (if such given).






LINEWIDTH <expN8> is the line width in pixels. If not given, line width of 1 pixel isused.

CMD 47

Description:@...DRAW RECTANGLE is an alternative command to @..BOX and supports alsorounded corners. Applicable on screen and/or printer output in GUI mode. Thiscommand is processed also for GUI/GDI printout (when SET GUIPRINT ON orPrintGui(.T.) is active).



Example:@ 3, 5, 8, 16 DRAW RECTANGLE COLOR "B+/BG+" PRINTCOLOR "B/B+"@ 3,15, 8, 26 DRAW RECTANGLE ROUNDED 75 COLOR "R+/RG+"

Example:See complete example in <FlagShip_dir>/examples/printergui.prg withalternative rounded corners by given radius.


Compatibility:New in FS7.

Translation:GuiDrawRectangle(...)

Related:@..DRAW CIRCLE, @..DRAW ELLIPSE, @..DRAW ARC, @..DRAW PIE,@..DRAW POLYON, @..DRAW IMAGE, @..DRAW LINE. @...BOX, @...TO.., SETGUIPRINT, PrintGui()

CMD 48

@...PROMPTSyntax:

@ <expN1>, <expN2>PROMPT <expC3>[MESSAGE <expC4>][FONT <oFont>][HEIGHT <nRows>][WIDTH <nCols>][CENTER][COLOR <color>] [GUICOLOR <guicol>][STYLE <naBox>][LINEWIDTH <naPix>][SELECT <block>][TOOLTIP <cTip>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN6>)]

Purpose:Defines menu prompts and their messages used in MENU TO and displays themon the screen.

Arguments:<expN1> and <expN2> are the row and column where the prompt is displayed. InGUI mode, you may use numeric values with decimal fractions for row and column,which are then rounded to integer in Terminal i/o mode. To set coordinates at exactpixel value, use the PIXEL clause (or enable SET PIXEL ON).

<expC3> is the character string displayed in the menu. If null- string "" is given, anun-selectable item is generated. You may specify hot-key by prefacing the selectedcharacter by "&", "\&" or "\<". If you wish to display ampersand "&", add a spacebehind it. The hot-key is displayed underscored in GUI mode. In Terminal i/o mode,the hot-key it is displayed by using the 4th color pair of COLOR clause if suchavailable, otherwise using inverse intensity of 1st (standard) color pair.

Options:MESSAGE <expC4> is the character string displayed on the message line. If thisoption is specified, the message of the highlighted prompt is displayed on the linedefined with SET MESSAGE. The screen section below the message is saved, andrestored later at clear of the next MESSAGE, or manually by invoking _Message("")function. In GUI mode, the message is displayed in status bar. In Terminal i/omode, the message is displayed either in the status bar (if active) or in the SETMENU row otherwise. The <expC4> message can also be a code block which isevaluated at the time of MENU TO and must return a string to be displayed,otherwise no status bar message appears.

FONT <oFont> (GUI only) You may specify other than the default font [email protected] Font{"Helvetica",12}

CMD 49

HEIGHT <nRow> specifies the height (rows/pixel) of prompt (GUI mode only). Forhorizontal prompt menus, a pleasant display is achieved with HEIGHT 1.0 (default)to 1.5.

WIDTH <nCol> specifies the width (chars/pixels) of the prompt text, which may bedisplayed centered when the CENTER clause is used.

COLOR <color> overwrites temporarily (for this PROMPT) the standard SETCOLOR specification in Terminal i/o mode. The <color> parameter is a stringcontaining at least two (standard, enhanced) color pairs.

GUICOLOR <guicol> specifies colors of this PROMPT in GUI mode. The <guicol>is either a string containing at least two (std, enh) color pairs, or ColorPair object oran array of RGB triplets. Considered in GUI mode, when the STYLE clause is alsogiven. When the GUICOLOR clause is not specified and SET GUICOLOR is ON,the COLOR <color> specification is used (if given) also in GUI mode.

STYLE <nBox> is either numeric expression or an array of two numeric elementsspecifying the frame around the prompt. When <nBox> is an array, the first elementis the style of standard display, and 2nd element the style of selected prompt viaMENU TO. When <nBox> is numeric, the same style is used for both menu states.For the <nBox> or {<nBox>,<nBox>} styles, use constants specified in box.fh:

BOX_NONE 0 display the prompt plain, w/o any frameBOX_PLAIN 1 draw plain 2-d frame around the promptBOX_SUNKEN 2 draw sunken 3-d frame around the promptBOX_RAISED 3 draw raised 3-d frame around the prompt

When the STYLE clause is not given, or the <nBox> style is invalid, a standardbutton-alike prompt is used. STYLE is considered in GUI mode only, and ignoredotherwise.

LINEWIDTH <nPix> is optional numeric value specifying the line width (in pixel) ofa box drawn by the STYLE clause. The default value is 2. Same as with STYLE,you may specify <nPix> as array of two numeric elements for the standard andselected item. LINEWIDTH is ignored when STYLE is not used or when in otherthan GUI mode.

SELECT <block> is optional codeblock evaluated in MENU TO when the item wasselected (by enter or mouse double-click or hotkey). The code block receives threeparameters: <posOfSelItem>, <oMenuItem>, <oPrompt>. If the codeblock returns.F., MENU TO selection will be continued, otherwise MENU TO is terminatedthereafter.

TOOLTIP <cTip> (GUI only) short pop-up message/info displayed when mousecursor is over the PROMPT item, even w/o focus

PIXEL : the <expN1>,<expN2> are values in pixel

NOPIXEL : the <expN1>,<expN2> are row/col values

CMD 50



Description:A highlight bar menu is constructed in two stages. First the menu choices arepainted on the screen using @...PROMPTs. Then, MENU TO may be used toactivate the highlight-bar. The highlight-bar can be navigated by the cursor keys inthe same order that the prompts were specified. In addition to, you may select anitem via hotkey. In GUI mode also mouse left(double)click activates the promptitem. See details about navigation keys in MENU TO command.

Menu items can be specified in any order and configuration of row and columnpositions. MENU TO, however, navigates the current list of menu items in the orderthey were defined. After a choice is made, its sequence number is returned in theMENU TO variable.

After each @...PROMPT command, the cursor is placed one column position to theright of the last menu item character and ROW() and COL() are updated to reflectthe new cursor position, so the next @ ROW(),COL() PROMPT.... aligns toprevious. In GUI mode, the COL() position is set so, that also the next @ROW(),COL() PROMPT.. aligns to previous one.

Colors: in Terminal i/o mode, either the supplied colors via COLOR clause is used,or the standard color otherwise. In GUI mode, the GUICOLOR clause is consideredtogether with STYLE, if both are given. The standard, unselected @..PROMPT itemis displayed by the 1st color pair, selected item in MENU TO by using 2nd colorpair. Hot-keys, if specified, are underscored (in GUI mode) or displayed in Terminali/o by using the 4th color pair. Unselectable items are displayed by the 5th colorpair. See SET COLOR for further details.

Nesting: FlagShip supports nested @...PROMPT / MENU TO, triggered either bySET KEY TO <myUdf> or by SELECT <block> clause. The only pre-requirement is,you declare either LOCAL _oPrompt [AS Usual] or PRIVATE _oPrompt := NILvariable which then automatically hold the nested prompts. If _oPrompt is notexplicitly declared, internally declared PUBLIC _oPrompt variable is used otherwise.

Selection: The selection of @..PROMPT items is handled by MENU TO command.Refer there for further information about navigation and supported keys. If you wishto clear all @..PROMPT items without invoking MENU TO, use the CLEAR MENUcommand or _oPrompt:Clear()

The Prompt class is used internally for @..PROMPT items and MENU TOprocessing, the object is hold in _oPrompt. See also menuclass.fh

CMD 51

Example:SET MESSAGE TO (MAXROW())@ 10,20 PROMPT "One"@ 12,20 PROMPT "Two" MESSAGE "Help message for option Two"@ 14,20 PROMPT "Three"MENU TO ch

Example:Build an SAA look-alike menu, using un-nested @..PROMPT/MENU TO:

PRIVATE choice1 := 1, choice2 := 0, action := -1, submenuDO WHILE .T.

@ 0, 0 CLEAR@ 0, 0 PROMPT "Main menu &1"@ 0,20 PROMPT "Main menu &2"@ 0,40 PROMPT "Main menu &3"@ 0,60 PROMPT "Exit "MENU TO choice1 // --horizontal--

SET KEY 4 TO my_right_left // CuR passed to UDPSET KEY 19 TO my_right_left // CuL passed to UDP

submenu := 0DO WHILE choice1 > 0 .AND. choice1 < 4

@ 1,(choice1-1)*20 TO 5,(choice1-1)*20+19DO CASECASE choice1 = 1

@ 2,1 PROMPT "1.text" // choice1=1, choice2=1@ 3,1 PROMPT "2.text" // choice1=1, choice2=2@ 4,1 PROMPT "3.text" // choice1=1, choice2=3

CASE choice1 = 2@ 2,21 PROMPT "Submen.1"@ 3,21 PROMPT "Submen.2"

CASE choice1 = 3@ 2,41 PROMPT "text" ; @ 3,41 PROMPT "other text"

ENDCASEaction := -1; submenu := 1MENU TO choice2 // --vertical--IF action != -1 // left /right

@ 1, action * 20 CLEAR TO 5, action * 20 + 19ELSEIF LASTKEY() = 13 .OR. LASTKEY() = 27

EXIT // exit the submenuENDIF

ENDDO // ESC: exitSET KEY 4 TO ; SET KEY 19 TO // disable CuR/CuLIF (choice2 > 0 .and. lastkey() = 13) .OR. ;

(LASTKEY() = 27 .AND. submenu = 0)EXIT

ENDIFENDDO? "choice1=",choice1,"choice2=",choice2

CMD 52

PROCEDURE my_right_left (p1, p2, p3)action := choice1 - 1 // leave Submenuchoice1 = IF(LASTKEY()==4,if(choice1 >= 4,4,choice1+1), ;

if(choice1 <= 1,1,choice1-1) )KEYBOARD chr(3) // leave SubmenuRETURN

Example:for using the HEIGH, WIDTH, COLOR, GUICOLOR, STYLE, SELECT clauses andnesting, see complete example in .../examples/prompt.prg


Compatibility:Unlimited PROMPTs for one MENU TO are supported in FlagShip, up to 32 inClipper, which also does not support nesting.

Translation:__ATPROMP2 (@_oPrompt, expN1, expN2, expC3 [, expC4], ... )old syntax (FS4.48 and VFS up to 5.1.4), w/o nesting:__ATPROMPT (expN1, expN2, expC3 [, expC4] )

Related:MENU TO, CLEAR MENU, SET MESSAGE, SET WRAP, ACHOICE()

CMD 53

@...SAYSyntax:

@ <expN1>,<expN2>SAY <exp3>

[PICTURE <expC4>][COLOR <expC5>][GUICOLOR <expC5>][PRINTCOLOR <expC6>][FONT <expC7>, <expN8>][FONT <expO9>][PIXEL|NOPIXEL][SPLIT | COLUMN [<expN10>,<expN11>]][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|

(<expN12>)]Purpose:

Displays data at the specified row and column positions according to an optionalpicture format on screen or printer.

Arguments:<expN1>, <expN2> are numeric expressions for positioning data at specific rowand column coordinates (0..24 and 0..79 for 25x80 screen or MAXROW() andMAXCOL() respectively). In GUI mode, you may use numeric values with decimalfractions for row and column, which are then rounded to integer in Terminal i/omode. To set coordinates at exact pixel value, use the PIXEL clause (or enableSET PIXEL ON).

<exp3> is evaluated by SAY and the result of a character, date, logical, or numericexpression is shown on the display (or the current DEVICE).

Options:COLOR <expC5> specifies the color in which to display <exp3>. Only the first colorpair (standard) is significant. If this clause is not given, the current color setting isused. In GUI mode, first the GUICOLOR is checked if set. If not, the COLOR<expC5> or the current color is used, but only when SET GUICOLOR is ON.Specifying COLOR and GUICOLOR allows you to handle different colors for GUIand Terminal i/o mode w/o switching the SET GUICOLOR setting.

GUICOLOR <expC5> specifies the color for the <exp3> data display considered inGUI mode, where only the first color pair (standard) is significant. Instead of string,you also may use RGB triplets (or stringified triplets), see SET COLOR for details,and example below. If GUICOLOR is set, it is used regardless the current SETGUICOLOR on/off setting. If omitted and SET GUICOLOR is ON, either the COLOR<expC5> is used if given, or the current SetColor() is used. The GUICOLOR clauseapply for GUI mode only, and is ignored otherwise.

CMD 54


FONT <expC7>, <expN8> (GUI only) You may specify other than the default fonte.g. @...SAY...FONT "Helvetica",12

FONT <expO9> (GUI only) This is alternative font specification. The <expO9> isalready instantiated font object, which allows also setting of font attributes like bold,underscore, italic and so on.

PICTURE <expC4> gives formatting rules for outputting <exp3>. When noPICTURE is given, the format is determined by analyzing the value of <exp3>.




SPLIT will split long string into two or more lines. The available size is calculatedfrom current Col() position up to MaxCol() for current line and MaxCol() -1 forsubsequent lines. If PrintGui(.T.) is active or SET GUIPRINT is ON,oPrinter:GuiMaxCol() is used instead. The string is splitted at the left next space ortab or dash if any. You may add conditional split position (separators) by chr(1) orchr(247), which are then interpreted as dash at line end and ignored otherwise.

COLUMN <expN10>,<expN11> or SPLIT <expN10>,<expN11> is similar toSPLIT, but instead of full line, it will split large text column- wise, from column<expN5> to <expN6> (in row/cols or units). Note that FONT <expC7>,<expN8> isnot accepted here, only FONT <expO9>. See example in <FlagShip_dir>/examples/printergui.prg

UNIT=ROWCOL or PIXEL or MM or CM or INCH or DOT or <expN12> specifiesunit for <expN1>...<expN2> and <expN10>,<expN11> coordinates. The <expN6> isparenthesed numeric value in range 0 to 5 (i.e. UNIT_MM or UNIT_ROWCOL etc).If the UNIT=.. clause is not specified, default is row/col, or the current setting bySET(_SET_PIXEL, logVal) or SET(_SET_COORD_UNIT, numVal). Apply for GUImode only, ignored otherwise.

Description:SAY <exp3> displays the result of the expression at the given coordinates on thecurrent device (printer, screen). The output obeys the optional PICTURE formatting.

SAY uses the "standard" pair from the current or given SET COLOR string. Seealso SETENHANCED and SETUNSELECTED commands to use another color pair.

By default, the output is directed to the screen, but if SET DEVICE TO PRINT isspecified, the output is re-directed to the printer. To direct the output to a text file,use SET PRINTER TO <file_name> followed by SET DEVICE TO PRINT. Unlikeconsole commands (like ? and ??), the @...SAY output to the printer is not echoedto the screen and SET CONSOLE has no effect on SAY output.

CMD 55

When using SAY to produce printer output, care must be taken to proceedsequentially from top to bottom. An EJECT is performed if the current row is lessthan the last position printed. If the column is greater than the previous one(including the SET MARGIN), BACKSPACEs are sent to reposition the printer head.To override such default repositioning, SETPRC() can be used to define a newlogical "printer head" position. You may tune the printer device driver byFS_SET("prset").

After @..SAY output, the cursor is left one column position to the right of the lastcharacter displayed. ROW() and COL() (or PROW() and PCOL() respectively) arethen updated with this position. Note that when different FONT is used, the COL() isadapted automatically to a larger/smaller font size but the ROW() only when SETROWADAPT is ON (default is OFF). You also may force the adaption manually byinvoking RowAdapt() thereafter. To align an output using different fonts on the samebase line, use SET ROWALIGN BASELINE.

In GUI mode, any output is pixel oriented. For your convenience and to achievecross compatibility to textual based applications, FlagShip supports alsocoordinates in common row/column values. It then internally re-calculates the givenrows by using Row2pixel() and columns by using Col2pixel() function. The line andcharacter spacing is affected by the currently used default font. For minimal portingeffort, best to use fixed fonts (SET FONT "Courier", 12).

For additional hints how to manage proportional fonts, see further details inLNG.5.3, LNG.5.4, Col2pixel(), Row2pixel(), SET FONT, SET ROWALIGN, SETROWADAPT.

In GUI mode, you may include RichText/HTML tags into the output string and eitheruse SET HTMLTEXT ON or preface the string by "<HTML>" to interpret the tags.See more in SET HTMLTEXT.

The @..SAY command is processed also for GUI/GDI printout (when SETGUIPRINT ON is active) and accepts PRINTCOLOR, PICTURE, FONT, PIXEL andUNIT= clauses, other are ignored.

Picture:<expC4>, the PICTURE clause, is a string and consists of two optional parts, theFUNCTION and the TEMPLATE, separated by at least one blank when both arepresent. Functions apply to the entire <exp3> while templates mask correspondingcharacters of <exp3>. Function and template symbols are not case sensitive.

The FUNCTION part, when given, must precede the template and start with the "@"sign. All the symbols which follow the first blank are interpreted as functions. Therest is taken as TEMPLATE. In the absence of the "@", the whole string isconsidered a template.

Picture FUNCTIONS are applied to the entire SAY <exp>. Multiple functiondefinitions are allowed. Characters not belonging to the TEMPLATE symbol setoverwrite existing characters of the <exp>. The "@R" function enables the insertioninstead of the overwriting of non-template characters.

CMD 56

If you set FS_SET("devel", .T.), PICTURE problems and fixes are displayed asdeveloper's warning.

Picture FUNCTION Symbols "@x". For @..SAY, the SAY or S/G apply:

Func Type used DefinitionA C GET in SAY: same as 'X' templateB N SAY Numbers are displayed left-justifiedC N SAY 'CR' for credit is displayed after positive numbersD D S/G Dates are displayed in the SET DATE formatE D S/G Dates are displayed in European format (day and month are exchanged)E N S/G Numerics are displayed in European format (comma & period are

exchanged)K all GET GET is cleared if the first key is not a cursor or Insert keyP C GET Password: display '*' instead of textR C S/G Non-template characters from the TEMPLATE part of picture are

inserted during in/output but removed from the valueSn C S/G Horizontal scrolling within a GET window of <n> columns is allowed,

SAY displays only the first <n> charactersX N SAY 'DB' for debit is displayed after negative numbersZ ND S/G Leading zeros are displayed as blanks( N SAY Negative numbers are enclosed in parentheses with leading spaces) N SAY Negative numbers are enclosed in parentheses without leading spaces! C S/G Alphabetic characters are converted to uppercaseF N SAY fill leading spaces with stars "*"T all SAY remove leading and trailing spaces

Picture TEMPLATE Symbols:

TEM Type used DefinitionX C S/G Any character is acceptedA C GET in SAY: same as 'X' templateB C GET in SAY: same as 'X' templateN C GET in SAY: same as 'X' template9 CND S/G Digits for any data type including the sign for numerics are displayed# CND S/G Digits, signs and spaces for any data type are displayedL L S/G The logicals "T" or "F" are displayedY CL S/G Only "Y" or "N" are allowed! all S/G An alphabetic character is converted to uppercase$ N SAY The Dollar sign $ is displayed in place of a leading space in a numeric* N SAY The asterisk is displayed in place of a leading space in a numeric. N S/G The period defines the decimal point position, regardless of the given @E

conversion, N S/G The comma defines the 'thousands' comma position, regardless of the

given @E conversion

CMD 57



If you write to row or column not currently visible on the screen, you may force anautomatic horizontal/vertical scroll by assigning

_aGlobSetting[GSET_G_L_ROW_VISIBLE] := .T. // default = .T._aGlobSetting[GSET_G_L_COL_VISIBLE] := .T. // default = .F.

Example:The string is shown in the 11th row and the 5th column. Non- template characterswill overwrite a part of the value string if no @R function is used.

value = "Peter"@ 11,5 SAY value // Result: Peter@ 11,5 SAY value PICTURE "@!" // Result: PETER@ 11,5 SAY value PICTURE "xx-x" // Result: Pe-e@ 11,5 SAY value PICT "@! xxtxx" // Result: PEtER@ 11,5 SAY value PICT "@R! xx xxx" // Result: PE TER

value1 = "long pict"value2 = "long string"@ 5,5 SAY value1 PICT "xxxxxxxxxxxxxxx" // "long pict"@ 6,5 SAY value2 PICT "XXXX" // "long"

Example:With an 80 column terminal, the string value will be shown on screen as depicted,starting from 11th row and 77th column.

value = "abcdefgh" // Result : ─────┐@ 11,77 SAY value // line 11: abc│

// line 12: def│// line 13: gh │

Example:Numbers are converted by default, according to the SET DEFAULT or the currentfield length, or by using the PICTURE clause

value = 12345.67negval = -123.45@ 12,12 SAY value // 12345.67@ 12,12 SAY value PICT "999999.99" // 12345.67@ 12,12 SAY value PICT "99,999.99" // 12,345.67@ 12,12 SAY value PICT "9,999.99" // 12345.67<-note!@ 12,12 SAY value PICT "9999.99" // 12345.6 <-note!@ 12,12 SAY value PICT "99.99" // 12345 <-note!@ 12,12 SAY value PICT "9999" // **** <-note!

@ 12,12 SAY value PICT "@E 99,999.999" // 12.345,670@ 13,12 SAY value PICT "@B 99999999.99" // 12345.67@ 13,12 SAY value PICT "@C 999999.99" // 12345.67 CR@ 13,12 SAY negval PICT "@( 99999.99" // (123.45)@ 13,12 SAY negval PICT "@) 99999.99" // (123.45)

CMD 58

Example:The date may be displayed and entered according to PICTURE and/or settings bySET DATE and SET CENTURY

value = CTOD("12/31/93")@ 14,10 SAY value // 12/31/93@ 14,10 SAY value PICTURE "@D" // 12/31/93@ 14,10 SAY value PICTURE "@E" // 31/12/93@ 14,10 SAY value PICTURE "@E 99.99.99" // 31.12.93SET CENTURY ON@ 14,10 SAY value PICTURE "@E" // 31/12/1993SET DATE USA@ 14,10 SAY value PICTURE "@D" // 12-31-1993SET DATE GERMAN@ 14,10 SAY value // 31.12.1993@ 14,10 SAY value PICTURE "@E" // 12.31.1993

Example:SET FONT "Helvetica", 12@ 0,0 say "Hello" ; ?? COL() // text columns differs@ 1,5 say "Hello" ; ?? COL() // with proportional fontSET FONT "Courier", 12@ 2,0 say "Hello" ; ?? COL() // text columns aligns@ 3,5 say "Hello" ; ?? COL() // with fixed font

Example:#include "color.fh"@ 5,2 SAY "hello light blue on std. GUI Windows background" ;

COLOR "B+/N" ; // Terminal modeGUICOLOR {{0,0,255},{RGBCOLOR_BG_WINDOWS}} // GUI mode

@ 6,2 SAY "hello dark red on std. background (Windows or Linux)" ;GUICOLOR ("R/" + RGBSTRING_BG) COLOR ("R/N")

Classification:screen oriented output (SET DEVICE TO SCREEN), buffered via DISPBEGIN() ...DISPEND() coordinates oriented printer/file output (SET DEVICE TO PRINT)

Compatibility:Clipper ignores illegal PICTURE characters, FlagShip reports them in developermode. FlagShip tries to correct them: if no space is given between the PICTUREfunction and template, it will be corrected by inserting the whitespace character.The leading and trailing spaces in the PICTURE definition will be truncated.

FlagShip does not cut off the most significant digits of numeric output within shortpictures, it tries, if possible, to output the whole number by removing inserted charsor by shortening the PICTURE deci part containing zeros. To disable this feature,and to display stars instead, assign _aGlobSetting[GSET_L_ADAPT_PICT] := .F.

When using a numeric PICTURE which does not display all decimal digits stored inthe variable, FlagShip cuts the remaining decimal digits like all other Xbase dialects,but unlike Clipper which rounds it. For example, the statement

@ y,x SAY 1234.567 PICT "9999.99"

CMD 59

will display 1234.57 in Clipper 5.2, but 1234.56 in FlagShip and other Xbasedialects. For fully compatible output to Clipper 5.2, use e.g.

num = ROUND(num,2)@..GET num PICTURE "99.99"

[email protected] ROUND(num,2) PICTURE "99.99"

etc.

Similarly to strings: if the template PICTURE characters does not match the stringlength, the template is automatically extended by "X" instead of truncating theoutput (like Clipper illegally do). This means in generally: FlagShip does not modifythe output variable length, but only the PICTURE template, if required.

If the line number <expN1> is out of range, FlagShip displays the text at the first orlast line available, according to C87. When the text is longer than the availablecolumn, and the "@S" picture is not specified, the rest will be continued insubsequent lines, see example above.

The physical output on the screen depends on the chosen terminal emulation(environment variable TERM), the ability of the terminal to display the requiredgraphical characters, and the output mapping defined in the file FSchrmap.def.

In contrast to DOS, the color capability and the size of the screen is not fixed to80x25, but depends on the current terminal used (environment variable TERM) andthe terminal description in the terminfo file, e.g. FStinfo.src. If possible, use one ofthe extended terminal descriptions FSxxx, see (REL) Predefined Terminals.

In GUI mode, the @..SAY cannot overwrite widgets located in higher layer, see alsoLNG.5.3

Embedded zero bytes are not supported.

Note: because some older UNIX terminals allow only 24 instead of 25 lines to beused, use @ MAXROW(),x SAY... instead of @ 24,x SAY... for programs runningon different terminals. See also LNG.5.1, section SYS, and FS_SET ("outmap").

Translation:DEVPOS (expN1, expN2) ; DEVOUT (exp3 [, expC5] )DEVPOS (expN1, expN2) ; DEVOUTPICT (exp3, expC4 [, expC5] )

Related:?/??, @...GET, @...TO, @...CLEAR, CLEAR, SET DEVICE, COL(), ROW(),FS_SET("devel"), FS_SET("term"), FS_SET("prset"), PCOL(), PROW(), SETPRC(),SETSTANDARD, SETENHANCED, SETUNSELECTED, SET HTMLTEXT, SETROWADAPT, SET ROWALIGN, SET GUIPRINT, description in LNG.5.1, LNG.5.3and sections REL, SYS.

CMD 60

@...SAY [email protected] IMAGESyntax 1:

@ <expN1>, <expN2>, [<expN3>], [<expN4>]SAY IMAGE|BITMAP[USING] <expC5>[SCALE] [CLIP|NOSCALE][IMGTYPE <expC7>][BORDER|FRAME <expN8>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN9>)]

Syntax 2:@ <expN1>, <expN2>, [<expN3>], [<expN4>]

SAY IMAGE|BITMAP[FROM] FILE <expC6>[SCALE] [CLIP|NOSCALE][IMGTYPE <expC7>][BORDER|FRAME <expN8>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN9>)]

Purpose:Display bitmap image at specified screen position. This command is equivalent [email protected] IMAGE command. It is considered also by GUI printout (when SETGUIPRINT ON or PrintGui(.T.) is active). Applicable in GUI mode only, ignoredotherwise.

Syntax 1 uses image data stored in database or character variable, Syntax 2 readsthe image from file.

Arguments:<expN1>, <expN2> are numeric expressions, specifying the row and columncoordinates (i.e. the top left corner) where the image is displayed. You may usenumeric values with decimal fractions for row and column. To set coordinates atexact pixel value, use the PIXEL clause (or enable SET PIXEL ON).

<expN3> is optional numeric value, specifying the bottom line (or Y pixel value)bounding the image height. If not given, the image height is used.

<expN4> is optional numeric value, specifying the right column (or X pixel value)bounding the image width. If not given, the image width is used.

[USING] <expC5> is the character variable or field containing the image datadisplayed according to Syntax 1.

CMD 61

[FROM] FILE <expC6> is the image file name (optionally with path) displayedaccording to Syntax 1, optionally with path. The file name extension is not relevant;FlagShip determines the image type from the data self, or by considering theIMGTYPE clause.

CLIP or NOSCALE will clip the image at bottom and/or right if it does not fit into thespecified rectangle <expN1>...<expN4>. If neither CLIP nor NOSCALE wasspecified, SCALE is the default.

SCALE will scale the image to fit into the specified rectangle <expN1>...<expN4>. If<expN3> is not given, the image is scaled to fit into width of <expN4> - <expN2>. If<expN4> is not given, the image is scaled to fit into height of <expN3> - <expN1>. Ifneither <expN3> nor <expN4> was specified, the image is displayed as is.

IMGTYPE <expC7> is optional image specification. If not given, FlagShip reads fewbytes of the image to determine the image type. You may override this pre-scan byspecifying <expC7>:

"BMP" (Windows Bitmap) is uncompressed image format common on MS-Windows

"GIF" (Graphic Interchange Format) is compressed lossless image format usedoften for Web images. Note: GIF format uses LZW compression patentedby Unisys and needs to be licensed (by Unisys) in some countries(alternative is PNG format).

"JPEG" (Joint Photographic Experts Group) is a compressed lossy image formatthat gives high compression for real-world and photo-realistic images.

"PNG" (Portable Network Graphics) is compressed lossless image format, offeringalmost better compression than JPEG, used also as patent-freereplacement of GIF or TIFF images.

"PPM" (Portable PixMap) is uncompressed image format common on Unix,offering few advantages over PNG or JPEG

"XBM" (X11 BitMap) is uncompressed monochrome image format.

"XPM" (X11 PixMap) is uncompressed image format, which can be triviallyincluded in source files as they are C code.

BORDER <expN8> or FRAME <expN8> specifies optional frame around theimage, where the <expN8> is a constant specified in box.fh:

BOX_NONE 0 don't draw any border around image (default)BOX_PLAIN 1 draw plain 2-d frame around the imageBOX_SUNKEN 2 draw sunken 3-d frame around the imageBOX_RAISED 3 draw raised 3-d frame around the image

PIXEL : the <expN1> ... <expN4> are values in pixel

CMD 62

NOPIXEL : the <expN1> ... <expN4> are row/col values

If [PIXEL|NOPIXEL] is not specified, the current SET PIXEL status is used. PIXELis shortcut for UNIT=PIXEL, NOPIXEL is shortcut for UNIT=ROWCOL


Description:

This command is supported in GUI mode and ignored otherwise. It displays bitmapimage at specified position, optionally scaled or circumcised and/or surrounded by aframe. The image is either read from any named file (when using the FILE ...clause) or is passed as data stream in a character variable. The image may becleared by usual CLS, CLEAR SCREEN, @..CLEAR TO.. command andcorresponding functions.

Supported image types are bmp, gif, jpeg/jpg, png, ppm, xbm and xpm. See theirdescription in the IMGTYPE clause. All other file types can easily be converted toone of these supported formats by any graphic image program like Gimp,Photoshop, Paint, IfranView etc. (use export to... or save as...).

When you want to store images in databases, use MEMO field and MemoCode() tostore and MemoDecode() to access the image. If the image size is too large forMEMO fields (32/64kb), you may compress/uncompress it by CharPack() /CharUnpack() from the FS2 Toolbox. Alternatively, you may use directly FlagShip'svariable database fields VB or VBZ to store images up to 2GB, see also DbCreate()for details.

The @..SAY IMAGE command is processed also for GUI/GDI printout (when SETGUIPRINT ON is active) and accepts all except BORDER clauses.

Alternative syntax for @..SAY IMAGE is @..DRAW IMAGE

Example:#include "box.fh"@ 10,40 SAY IMAGE file "myimg.gif"cImgVar := "..\images\otherimage.bmp"@ 15,50,18 SAY IMAGE from file (cImgVar) border BOX_PLAIN@ 350,500,480,600 SAY IMAGE file myimg.jpg PIXEL NOSCALE

local cImgData := memoread("../images/myimg.png")@ 10,40,,20 SAY IMAGE cImgData SCALE border BOX_SUNKEN

Example:see also <FlagShip_dir>/examples/images.prg and printergui.prg foradditional examples

CMD 63

Classification:screen oriented output in GUI mode as well as GUI printout

Compatibility:New in FS5, printer support is new in FS7

Translation:DispImageData() or DispImageFile()

Related:@..DRAW CIRCLE, @..DRAW ELLIPSE, @..DRAW ARC, @..DRAW LINES,@..DRAW PIE, @..DRAW POLYON, @...BOX, @...TO.., SET GUIPRINT,MemoCode(), MemoDecode(), SET GUIPRINT

CMD 64

@...[SAY..] GETSyntax 1:

@ <expN1>,<expN2>GET <variable>

[CAPTION <capt>][CLEAR|DESTROY][COLOR <expC9>][GUICOLOR <expC9>][DEFAULT <defa>][ENABLE|DISABLE][ERRORVALID <errBlk>][GUIFAST][MESSAGE <text>][NOALIGN][PICTURE <expC4>][RANGE <expN6>,<expN7>][SEND <exp11>][TOOLTIP <ttip>][USERMSG <exp10>][USING <obj>][VALID <expL8>][WHEN <expL5>][HEIGHT <expN11>][WIDTH <expN12>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|

(<expN13>)]Syntax 2:

@ <expN1>,<expN2>SAY <exp3>

[PICTURE <expC4>][COLOR <expC9>][GUICOLOR <expC9>]

GET <variable>[CAPTION <capt>][CLEAR|DESTROY][COLOR <expC9>][GUICOLOR <expC9>][GUIFAST][DEFAULT <defa>][ENABLE|DISABLE][ERRORVALID <errBlk>][MESSAGE <text>][NOALIGN]

CMD 65

[PICTURE <expC4>][RANGE <expN6>,<expN7>][SEND <exp11>][TOOLTIP <ttip>][USERMSG <exp10>][USING <obj>][VALID <expL8>][WHEN <expL5>][HEIGHT <expN11>][WIDTH <expN12>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|

(<expN13>)]Purpose:

Prepares one entry field for the full-screen data input using the READ command.Displays the current data at the specified row and column positions. Creates a newobject within the GETLIST array. Optionally, displays an additional text using theSAY clause.

Syntax 2 represents a combination of syntax 1 and the command @...SAY. In thefollowing description syntax 1 will normally be referred to.

Arguments:<expN1>, <expN2> are numeric expressions, specifying the row and columncoordinates of the input field (syntax 1) or of the text being displayed (syntax 2). InGUI mode, you may use numeric values with decimal fractions for row and column,which are then rounded to integer in Terminal i/o mode. To set coordinates at exactpixel value, use the PIXEL clause (or enable SET PIXEL ON).

The coordinates are in the range 0..24 and 0..79 for a 25x80 screen or MAXROW()and MAXCOL() respectively. With syntax 2, the input field starts at the end of the<exp3> text and an additional space character. Output which extends beyond thevisible end of the display is clipped and does not appear.

GET <variable> is a database field or a memory variable, the contents of which isdisplayed and added to the list of pending GETs to be enabled for input and editingby the READ command. The <variable> can be of the type character, numeric, dateor logical. If the storage class is ambiguous, FIELD is assumed. Fields from otherworking areas can be used as <variable> by referring to them via their alias.

Options: (in alphabetical order)CAPTION <capt> is the displayed text instead of @..SAY

CLEAR|DESTROY forces to clear the GET display at the end of variable visibilityscope. See also READ CLEAR

COLOR <expC9> is a standard color string with 5 to 8 color pairs for displaying theGET field <variable>. An inactive GET field is displayed by using color pair 5(unselected), an active GET field with input focus (get:HasFocus) is displayed bycolor pair 2 (enhanced). Disabled GETs by using the DISABLE clause is displayed

CMD 66

by color pair 7 if such is available, otherwise by pair 5. In GUI mode the color pair 8,if available, is used for GETs in unselected window. See SET COLOR for moredetails. With syntax 2, different colors for the SAY and GET command parts can beused. If omitted, the current color setting is used. In GUI mode, first the GUICOLORis checked if set. If not so, either this COLOR <expC9> or the current color is used,but only when SET GUICOLOR is ON. Specifying COLOR and GUICOLOR allowsyou to handle different colors for Terminal and GUI i/o mode.

DEFAULT <defa> set the GET <variable> to <defa> value if <variable> is NIL,empty() or of different type than <defa>

ENABLE|DISABLE enable (default) or disable the item from READ processing

ERRORVALID <errBlk> use the code block <errBlk> to display post- validateerror/failure

GUICOLOR <expC9> specifies the color for the display of the input field <variable>considered in GUI mode only. If set, it is used regardless the current SETGUICOLOR setting. If omitted and SET GUICOLOR is ON, either the COLOR<expC9> is used if given, or the current SetColor() is used. The GUICOLOR clauseapplies for GUI mode only, and is ignored otherwise. <expC9> is a standard colorstring with 5 to 8 pairs, where color pair 2 is used to display the active GET, colorpair 5 is used for the unselected GETs, color pair 7 for disabled GETs, and colorpair 8 for GETs in an unselected window. See 'SET COLOR TO' for more details.

MESSAGE <text> display message <text> in status bar or in the SET MESSAGEline when the GET field receives focus

NOALIGN don't align this field even if SET GUIALIGN is ON

PICTURE <expC4> gives formatting rules for the <variable> input. With syntax 2,different pictures for the SAY and GET command parts may be used. When noPICTURE is given, the format is determined by examining the value in <exp3>and/or <variable>.

RANGE <expN6>,<expN7> (post-validation) are the lower and upper limits ofacceptable numeric input. The lower limit <expN6> must always precede the upperlimit <expN7>. If the input or the edited value is not inside the interval, a message tothis effect will be displayed and the control will be returned to the GET. This checkis performed only when a new value is entered or the available data edited (sameas in Clipper), except you set

_aGlobSetting[GSET_L_GET_RANGE_ALWAYS] := .T. // default = .F.which is then tested always at exiting GET, same as VALID clause.

SAY <exp3> is an expression displayed prior to the entry field and evaluated by theSAY clause (see more @...SAY).

SEND <exp11> is a full object message to be sent to the current object.

TOOLTIP <ttip> (GUI only) short pop-up message/info displayed when mousecursor is over the GET field, even w/o focus

CMD 67

USERMSG <exp10> is a message (expression) of any type, which will be sent(assigned) to the current get:CARGO instance variable.

USING <obj> use already instantiated GET object <obj>, avoid a newcreation/instantiation

VALID <expL8> (post-validation) is a logical expression (or UDF returning a logicalvalue) which is evaluated whenever the user attempts to leave the correspondingGET. Should the expression return a .F. value, the cursor will remain on the currentfield. Note: return value other than logical assumes success and developer warningoccurs when FS_SET("devel", .T.) was set. This feature is often used for lookupsusing post-processing functions.

WHEN <expL5> (pre-validation) specifies an expression (or UDF or codeblockreturning a logical value) that must be satisfied in order to enter the GET field duringa READ. Note: return value other than logical assumes success, additionally adeveloper's warning occurs when FS_SET("devel", .T.) was set.

HEIGHT <expN11> specifies the widget height in rows or pixels according to thecurrent SET PIXEL on/OFF setting. This clause is considered in GUI mode only andis equivalent to the oGet:Height access.

WIDTH <expN12> specifies the widget width in columns or pixels according to thecurrent SET PIXEL on/OFF setting. This clause is considered in GUI mode only andis equivalent to the oGet:Width access. It behaves similarly to PICTURE "@S..." butis applicable also for non-character fields.




UNIT=ROWCOL or PIXEL or MM or CM or INCH or DOT or <expN13> specifiesunit for <expN1> .. <expN2> coordinates. The <expN13> is parenthesed numericvalue in range 0 to 5 (i.e. UNIT_ROWCOL to UNIT_DOT). If the UNIT=... clause isnot specified, default is row/col, or the current setting by set(_SET_PIXEL, log) orset(_SET_COORD_UNIT, num). Apply for GUI mode only, ignored otherwise.

Description:The @...GET command performs several actions. It displays the default contents ofa variable or a database field at row and column, and formats the output accordingto the optional picture format. Appending it to the GETLIST array will create a newGET object. The <variable> is associated with that object, as well as the other,optional modifiers. A subsequent READ command enables full-screen editing, usingthe data stored by the GET command.

In GUI mode, the GET field appears in widget (control), which is a kind of small sub-window. You therefore cannot overwrite the GET field by subsequent SAY or byother widget. The GET will be cleared automatically by CLEAR GETS, end of READor by any kind of CLEAR.

CMD 68

When SET DELIMITERS are set ON, the @...GET command will display the defaultor user defined delimiters around the GET edit field and will shift the GET objectdisplay by one column right. This is fully supported in Terminal i/o mode; in GUImode the delimiters are not displayed, but the GET column is corrected.

If the GETLIST variable has not been declared PRIVATE or LOCAL in the currentprocedure, the predefined PUBLIC GETLIST variable is used. Declaring aPRIVATE, LOCAL (or STATIC) array allows you to nest GET/READs to any depth.

The READ command performs a full-screen edit of the GETs in the GETLIST array.As the user moves the cursor into each GET field, evaluating the user defined ordefault code block saved in the GET object retrieves the value of the associated<variable>. The value is converted to textual form and placed in a buffer within theGET field (object). This buffer is displayed on the screen, and the user is allowed toedit the text from the keyboard. When the user moves the cursor out of the GET,the updated buffer is converted back to the appropriate data type and assigned to<variable>.

For more information, refer to (CMD) READ.

Color:If the COLOR clause is not specified, the GET field is displayed in the current"enhanced" color pair (see SET COLOR and SETCOLOR()). If the "unselected"color is specified in SETCOLOR() as well, only the currently active GET is displayedin enhanced color while executing READ. All the other GET fields are thendisplayed in the "unselected" color.

Each GET field can have a different color specification defined by using the COLORclause or the command SET COLOR; the current color setting is stored in the GETobject during execution of the @...GET command.

When the COLOR clause of @..GET is specified, this color attributes are passed tothe instance variable get:COLORSPEC (see sect. OBJ). Since the specialCOLORSPEC notation <inactiveField>,<activeField>, the COLOR clause [email protected] command differ from the standard SETCOLOR() notation. Foryour convenience, you may use the SETCOL2GET() function to transform thecurrent (or any user defined) color setting into the proper notation, see examplebelow.

In GUI mode, colors are disabled by default. You may enable it by SET GUICOLORON and/or use the GUICOLOR clause, see details above.

Picture:<expC4>, the PICTURE clause, is a string and consists of two optional parts, theFUNCTION and the TEMPLATE, separated by at least one blank. Functions applyto the entire <variable> while templates mask corresponding characters of<variable>. Function and template symbols are not case-sensitive.

The FUNCTION part, when given, must precede the template and start with the "@"sign. All the symbols thereafter up to the first blank are interpreted as functions. Therest is taken as TEMPLATE. In the absence of the "@", the whole string is

CMD 69

considered a template. Picture FUNCTIONS are applied to the entire <variable>field. Multiple function definitions are allowed.

A TEMPLATE part specifies formatting or validation rules on a character bycharacter basis. The template string consists of a series of characters, some ofwhich have special meanings (see the following table). Each position in thetemplate string corresponds to a position in the displayed GET value. Characters inthe template string that do not have assigned meanings are copied verbatim intothe displayed GET value as un-editable characters. If you use the @R pictureFUNCTION, these characters are inserted between characters of the display value,and are automatically removed when the display value is reassigned to <variable>;otherwise, they overwrite the corresponding characters of the display value andalso affect the value assigned to <variable>. You may specify a template stringalone or with a function string. If you use both, the function string must precede thetemplate string, and the two must be separated by a single space.

If you set FS_SET("devel", .T.), PICTURE problems and fixes are displayed asdeveloper's warning.

Picture FUNCTION Symbols "@x". For @..GET, the GET or S/G apply:

Func Type used DefinitionA C GET Only alphabetic characters are allowedB N SAY Numbers are displayed left-justifiedC N SAY 'CR' for credit is displayed after positive numbersD D S/G Dates are displayed in the SET DATE formatE D S/G Dates are displayed in European format (day and month are

exchanged)E N S/G Numerics are displayed in European format (comma & period are

exchanged)K all GET GET is cleared if the first key is not a cursor or Insert keyP C GET Password, displayed as '*'R C S/G Non-template characters from the TEMPLATE part of picture are

inserted during in/output but removed from the valueSn C S/G Horizontal scrolling within a GET window of <n> columns is

allowed, SAY displays only the first <n> charactersX N SAY 'DB' for debit is displayed after negative numbersZ ND S/G Leading zeros are displayed as blanks( N SAY Negative numbers are enclosed in parentheses with leading

spaces) N SAY Negative numbers are enclosed in parentheses without leading

spaces! C S/G Alphabetic characters are converted to uppercaseF N SAY fill leading spaces with stars "*"T all SAY remove leading and trailing spaces_ C S/G (= underscore) replace "_" in template picture to protected space.~ C S/G (= tilde) replace "~" in template picture part to protected space.

CMD 70

Picture TEMPLATE symbols. For @..GET, the S/G and GET apply:

TEM Type used DefinitionX C S/G Any character is acceptedA C GET Only alphabetic characters w/o space are acceptedB C GET Only alphabetic characters and space are acceptedN C GET Only alphanumeric characters w/o space are accept.9 CND S/G Digits for any data type including the sign for numerics are

accepted# CND S/G Digits, signs and spaces for any data type are acceptedL L S/G The logicals "T" or "F" are acceptedY CL S/G Only "Y" or "N" are allowed! all S/G An alphabetic character is converted to uppercase$ N SAY The dollar sign $ is displayed in place of a leading space in a

numeric* N SAY The asterisk is displayed in place of a leading space in a numeric. N S/G The period defines the decimal point position, regardless of the

given @E conversion, N S/G The comma defines the 'thousands' comma position, regardless

of the given @E conversion^ C S/G (= circumflex) Un-editable (protected) output char_ C S/G (= underscore) Set un-editable space in output when also "@_"

is set, as alternative to " " in picture~ C S/G (= tilde) Alternative to "_", set un-editable space in output when

also "@~" is setany other Template symbol is copied to output and treated as un-editable

character

Validation:During GET execution, no validation takes place. The READ command checks thepre-valid condition (WHEN clause) to decide whether to enter the correspondingfield. If the condition returns FALSE, the field is skipped. Post-validation, (RANGEand VALID clause) will be done any time the user wants to leave the current field. Ifthe VALID condition returns TRUE, the user is allowed to leave; otherwise, thecursor remains in the current GET field.

If RANGE is specified, the data entered has to be within the defined limits to enableleaving the field. If the test fails, a message appears on the screen. In FlagShip, themessage is user- definable using FS_SET("load"/"set") and can be enabled ordisabled using the SET SCOREBOARD command.

With SET ESCAPE ON, no post-validation is performed.

Executing an UDF:For user friendly programs, it is common to create a context sensitive help system,using F1 (or other key) for the current data being edited: the command SET KEYTO may redefine any required key to execute a user procedure. On applicationstart, FlagShip pre-defines SET KEY 28 TO HELP, so that by adding thePROCEDURE HELP to your application, you may access it automatically when

CMD 71

pressing [F1] in any READ field. You may also use other keys or redefine F1 usingSET KEY <code> TO <udp> prior the READ command and, if necessary, disable itafterwards using SET KEY <code> TO. For information, refer to LNG.5.2.2 and(CMD) SET KEY.

Within the UDP or UDF, the current <variable> being edited can be determined byREADVAR() or with the current GET object using GETACTIVE().

The UDP or UDF may change the contents of any GET field being edited. To abortthe READ, CLEAR, CLEAR GETS or KEYBOARD CHR(27) commands can beused.

Cut & Paste:Depending on the currently used i/o mode (GUI, Terminal), you may insert/overwritecharacters in the GET field by cut and paste.

In GUI mode, FlagShip supports the global X11 or Windows clipboard forexchanging/transfer keyboard data. You may copy and paste text via clipboardfrom/to other windows or applications on the screen, or from/to other/current GETfield or MemoEdit() text. Insert the clipboard text into GET field by Alt-V key, copyby Alt-C key (both user modifiable). See CMD.READ for further details andsettings.

In Terminal i/o mode, similar functionality is provided (in Unix) via the "gpm" cut-and-paste console utility/daemon and FlagShip keyboard buffer by using it pre-defined keys and/or mouse buttons. To copy large strings, you probably may needto extend the buffer size by SET TYPEAHEAD, e.g. SET TYPEAHEAD TO 500.

Tuning:In GUI mode with proportional font, @ 5,1 SAY "XXXX" get var1 and @ 6,1 SAY"iiii" get var2 would set fields var1 and var2 at different column position, since theGET column in this compound statement is calculated from the last SAY position +one space. Because the width of "XXXX" differs from "iiii" with proportional font,also these GET columns differs. FlagShip's READ therefore re-calculates andadjust all GETs to fit among each other, if applicable. You may disable this featureby NOALIGN clause or globally by SET GUIALIGN OFF.

In GUI mode, drawing graphic lines sometimes requires refresh. If your displayflickers, you may disable the refresh by assigning


In GUI mode, the @..GET/READ field size width is calculated to fit the requestedamount of characters. In some cases and fonts, you may need to add a smalldisplacement to avoid horizontal scrolling, by assigning some more pixel to

_aGlobSetting[GSET_G_N_GET_WIDTH ] := 8 // default = 8 pixel

You also may modify general adjustment to field width/height_aGlobSetting[GSET_G_L_GET_ADJ ] := .T. // adjust row/col?_aGlobSetting[GSET_G_N_GET_ROW ] := 0 // add pix Get row_aGlobSetting[GSET_G_N_GET_COL ] := -2 // add pix Get column_aGlobSetting[GSET_G_N_GET_HEIGHT] := 0 // add pix Get height

Additional tuning is described in the READ command.

CMD 72

Example:The cursor is positioned under the first element (during the READ command) of thestring and the program waits for input. Only numerical input is allowed for the firstthree positions. Three non-template symbols then follow, which allows no input. Therest of the string allows only alphabetic input. The blank is a non- templatecharacter and input is not possible in its place in the PICTURE string.

value = "123---paris london"@ 11,11 GET value PICTURE "@! 999---AAAAA XXXXXX"READ* Result: 123---PARIS LONDON

Example:When the first key pressed is not a cursor key, the input field will be cleared. Thesame effect appears on numeric data entry, where the "@K" is by default.

value = "Text "@ 11,11 GET value PICTURE "@K! XXXXXX"* Result : TEXT

Example:The entry of long string within a short input window is supported using the "@S"format function:

@ 6,5 GET value PICTURE "@S10 !!!!XXXXXXXXXXXXX"* Result : THE long string* pressing the -> key THE long string* etc. THE long string* │ │

│ └── currently invisible└────────── the input field

Example:All the following statements set the active GET field to yellow on red, the inactiveGET field is displayed in white on cyan:

SET COLOR TO "W+/B,GR+/R,,,W+/BG"xxx = "W+/BG,GR+/R"@...GET varname // uses automatically SETCOL2GET()@...GET varname COLOR SETCOL2GET() // the same color as [email protected] varname COLOR xxx // passes xxx to get:COLORSPECGETNEW (,,,,,SETCOL2GET()) // sets get:COLORSPEC to curr.colorget:COLORSPEC := SETCOL2GET() // sets get:COLORSPEC to curr.colorget:COLORSPEC := "W+/BG,GR+/R" // equivalent to the above

Example:Example of several validity checks:

LOCAL value := 0, passw := space(10)PRIVATE numzip := 0, country := " ", city := space(30)@ 10,11 SAY "Please enter a two-digit number: " ;

GET value PICTURE "99" RANGE 10, 99@ 11,11 SAY "Enter your password : " ;

GET passw VALID ","+trim(passw)+"," $ ",Peter,Paul,"@ 15,10 SAY "Country : " GET country PICTURE "@!"

CMD 73

@ 16,10 SAY "Zip code : " GET numzip ;PICTURE "99999" ;WHEN TRIM(country) == "D" ;VALID check_zip()

@ 17,10 SAY "City : " GET cityREADif lastkey() = 27 // Exit per ESC ?return // yes, back to menu

endif

FUNCTION check_zip /* check zip codes */LOCAL act_select, okact_select = SELECT() // save act.working areaSELECT 25 // select ZIP databaseSEEK numzip // seek current entryok = FOUND() // found ?IF ok // yes,city := FIELD->zip_city // predefine city name

ENDIFSELECT (act_select) // restore act.working areaRETURN (ok) // validation .T. or .F.

Example:Example of an array validation. Do not use the FOR index ii to VALIDate, since inREAD it will already have the value 4.

LOCAL ii, arr := {1,2,3}, check := {{1,10}, {2,22}, {3,33}}LOCAL col := {SETCOLOR(), "W+/B,GR+/G,,,W+/R", "W/B,N/W"}FOR ii := 1 TO LEN(arr)@ ii,1 GET arr[ii] PICTURE "999" COLOR (col[ii]) ;

SEND CARGO := ii ; // or: USERMSG ii;VALID arrcheck (arr, check)

NEXTREAD

FUNCTION arrcheck (inarr, checkarr)LOCAL element := GETACTIVE():CARGO, valuevalue := inarr [element]IF value >= checkarr[element, 1] .AND. ;

value <= checkarr[element, 2]RETURN .T.

ENDinarr[element] += 1 // assign new valueRETURN .F.

Example:The same array check routine, generalized for any GET type and for multi-dimensional GET array entry and access. The SEND clause in a @..GET statementis used for checking purposes only and may be omitted, using e.g.get:SUBSCRIPT[1].

FUNCTION arrcheck (inarr, checkarr)

LOCAL get := GETACTIVE(), elem, value, chkidxPRIVATE arrname := get:NAMEPRIVATE &arrname := inarr // get orig.arr ptr

CMD 74

elem := READVAR() // e.g. "ARR[3]"value := &(elem) // current valuechkidx:= get:CARGO // or get:SUBSCRIPT[1]

IF value < checkarr[chkidx, 1] .OR. ;value > checkarr[chkidx, 2]RETURN .F.

ENDIF&(elem) += 1 // assign new valueRETURN .T.

Classification:screen oriented output, buffered via DISPBEGIN()..DISPEND(), used forsubsequent screen oriented input (via READ)

Compatibility:New in FS4 are the clauses SEND and USERMSG, as well as the usage of theGET object.

In FlagShip, both the RANGE and the VALID clauses may be specified. RANGE ischecked first.

Clipper ignores wrong PICTURE characters, FlagShip reports them in developmentmode. When there are no separating spaces between the function and the templatepart, FlagShip tries to determine the template from the context, where possible.

FlagShip does not truncate the most significant digits of numeric output within shortpictures; it tries, if possible, to output the whole number by removing inserted charsor by shortening the PICTURE deci part containing zeros. To disable this feature,and to display stars instead, assign _aGlobSetting[GSET_L_ADAPT_PICT] := .F.

Similarly to strings: if the template PICTURE characters does not match the stringlength, the template is automatically extended by "X" instead of truncating the inputvariable (as Clipper illegally do). This means in generally: FlagShip does not modifythe input variable length, but only the PICTURE template, if required.

FlagShip's GETs are performed via the GET class (see section OBJ), and aretherefore fully user modifiable. The standard READ command is available in sourcecode in the getsys.prg file.

See also terminal & GUI information in @..SAY and LNG.5.

The clauses DEFAULT, GUICOLOR, USING, ERRORVALID, CAPTION,MESSAGE, TOOLTIP, CLEAR, DESTROY, ENABLE, DISABLE, PIXEL, NOPIXEL,NOALIGN, WIDTH are new in FS5

Class:GET, prototyped in <FlagShip_dir>/include/getclass.fh

Translation:__SUBSCARR (.T.) ; __scratch := variable ; __SUBSCARR (.F.)AADD (GetList, _FSGET_ (expN1, expN2, "variable", ;

Standard_GET_CodeBlock, [expC4], ;[Range_Valid], [{expL4}], [expC9], _subscarr) )

CMD 75

[ ATAIL(GetList):Cargo := exp10 ][ ATAIL(GetList):exp11 ]

Standard_GET_CodeBlock := {|input| ;IF(input == NIL, variable, variable := input) }

Range_Valid := {|input| .T. ;[ .AND. RANGE_CHECK (input, expN6, expN7) ] ;[ .AND. expL8] }

Related:?/??, @...SAY, @...TO, @...CLEAR, CLEAR, CLEAR GETS, KEYBOARD, READ,SET BELL, SET CONFIRM, SET DELIMITERS, SET DEVICE, SET FORMAT, SETINTENSITY, SET KEY, COL(), FS_SET(), READVAR(), ROW()

CMD 76

@...[SAY..] GET CHECKBOXSyntax 1:

@ <expN1>,<expN2>GET <varL> CHECKBOX[CAPTION <cCapt>][COLOR <cColor>][DEFAULT <lDef>][ENABLE|DISABLE][ERRORVALID <bError>][FOCUS <fblock>][MESSAGE <cText>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN5>)][SEND|GUISEND <snd>][STATE <sBlock>][STYLE <cStyle>][TOOLTIP <cTip>][USERMSG <cargo>][USING <obj>][VALID <lValid>][WHEN <lWhen>]

Syntax 2:@ <expN1>,<expN2>

SAY <cSaytext>[PICTURE <cSayPict>][COLOR <cSayColor>]

GET <varL> CHECKBOX[CAPTION <cCapt>][COLOR <cGetColor>][DEFAULT <lDef>][ENABLE|DISABLE][ERRORVALID <bError>][FOCUS <fblock>][MESSAGE <cText>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN5>)][SEND|GUISEND <snd>][STATE <sBlock>][STYLE <cStyle>][TOOLTIP <cTip>][USERMSG <cargo>][USING <obj>][VALID <lValid>][WHEN <lWhen>]

CMD 77

Purpose:Creates CheckBox widget and let it process via common READ.

Arguments:<expN1>, <expN2> are numeric expressions, specifying the row and columncoordinates. With Syntax 1: coordinates of the widget. With Syntax 2: coordinate ofthe capture text, the widget column coordinate is the over-next column behind thetext <cSaytext> end, same as in @..SAY..GET. In GUI mode, you may use numericvalues with decimal fractions for row and column, which are then rounded to integerin Terminal i/o mode. To set coordinates at exact pixel value, use the PIXEL clause(or enable SET PIXEL ON)

SAY <cSaytext> is a text caption identifying the CheckBox on the screen.

GET <varL> is a database field or a memory variable of logical type storing the"checked" status of the CheckBox.

CHECKBOX clause is mandatory here.

Options:CAPTION <cCapt> is a text explaining the CheckBox

COLOR <cSayColor> is an optional color specification for the @..SAY text.

COLOR <cGetColor> defines the color settings for the check box, applicable forTerminal i/o only. The string may contain 5 color pairs:

Pair# Used for Default1 Check box without input focus Unselected2 Check box with input focus Enhanced3 The check box's caption Standard4 The check box caption's accelerator key Background5 Border Border

For not specified pair, the default from current SetColor() is used

DEFAULT <lDef> set the GET <varL> to <lDef> value if <varL> is NIL, empty() orof different type than <lDefa> which must be logical.


ERRORVALID <bError> specifies to use the <bError> code block to display post-validate error/failure

FOCUS <fblock> specifies a code block that is evaluated each time the CheckBoxreceives focus. The code block receives two parameters, the current CheckBoxobject, and the oBox:HasFocus status.

MESSAGE <cText> displays message <text> in status bar or in the SETMESSAGE line when the CheckBox receives focus

PICTURE <cSayPict> is the optional picture of @..SAY text

PIXEL : the <expN1> and <expN2> are values in pixel

CMD 78

NOPIXEL : the <expN1> and <expN2> are row/col values



SEND <instance> } allows you to assign any valid class instanceGUISEND <instance> } or method. Supported for Clipper compatibility.

STATE <sBlock> specifies a code block that is evaluated each time the CheckBoxstate changes, i.e. is checked or unchecked. The code block receives twoparameters, the current CheckBox object, and the oBox:Buffer status.

STYLE <cStyle> specifies a character string that indicates the CheckBox delimitercharacters for Terminal i/o. The default style is pre-defined in the global arrayelement _aGlobSetting[GSET_T_C_CHBOX_STYLE] := "[X ]?" which is used whenthe STYLE clause is omitted.

TOOLTIP <cTip> (GUI only) short pop-up message/info displayed when mousecursor is over the CheckBox widget, even w/o focus

USERMSG <cargo> assigns the <cargo> value to the CheckBox:Cargo instance

USING <obj> use already instantiated CheckBox object <obj>, avoid a newcreation/instantiation

VALID <lValid> (post-validation) is a logical expression (or UDF returning a logicalvalue) which is evaluated whenever the user attempts to leave the correspondingGET. Should the expression return a .F. value, the cursor will remain on the currentfield. This feature is often used for lookups using post-processing functions.

WHEN <lWhen> (pre-validation) specifies an expression that must be satisfied inorder to enter the CheckBox during a READ

Description:The @...GET...CHECKBOX uses the CheckBox class. You may use it additionalproperties by e.g. Atail(GetList):<instance> := <value>

Tuning:The action on a key or mouse button press is defined in the user modifiable handler<FlagShip_dir>/system/checkboxhand.prg. Mouse is supported in GUI mode only.The default behavior on mouse button click is: Left mouse click selects/clears theCheckBox and leaves the CheckBox to next GET (if any), same as the +, -,space, x, y, t, n, f key press. Mid and right mouse button toggles thebutton but stays in the CheckBox until the corresponding key leaves it. Space or 'x'key toggles the status, the +, y, t key sets the CheckBox on, and -, n, f keypress sets it off.

CMD 79

By assigning _aGlobSetting[GSET_G_L_CHBOX_SINGLE] := .F. you may avoidleaving CheckBox by left mouse button. The supported mouse buttons are specifiedin _aGlobSetting[GSET_G_A_CHBOX_MOUSE] array, see <FlagShip_dir>/system/initio.prg

Example:local lBox1 := .F., lBox2 := .T., cText := space(20)@ 10,5 get lBox1 CHECKBOX CAPTION "Checkbox 1"@ 12,5 get lBox2 CHECKBOX CAPTION "Checkbox 2"@ 14,5 get cTextreadsetpos(15,0)? "box1=", lBox1, "box2=", lBox2wait

Example:see <FlagShip_dir>/examples/getread*.prg

Classification:screen oriented i/o (via READ)


Related:@..GET, READ, CheckBox class

CMD 80

@...GET COMBOBOXSyntax 1:

@ <expN1>,<expN2>,<expN3>,<expN4>GET <varN>COMBOBOX <aData>[CAPTION <cCapt>][COLDBOX <cFrame>][COLOR <cColor>][GUICOLOR <cGuiColor>][DEFAULT <defN>][DROPMARK <cDrop>][ENABLE|DISABLE][ERRORVALID <bError>][FOCUS <fblock>][HOTBOX <cFrame>][MESSAGE <cText>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN5>)][SCROLLBAR][SEND|GUISEND <snd>][STATE <sBlock>][TOOLTIP <cTip>][USERMSG <cargo>][USING <obj>][VALID <lValid>][WHEN <lWhen>]

Syntax 2:@ <expN1>,<expN2>,<expN3>,<expN4>

GET <varN>COMBOBOX USING <obj>[CAPTION <cCapt>][COLDBOX <cFrame>][COLOR <cColor>][GUICOLOR <cGuiColor>][DEFAULT <lDef>][DROPMARK <cDrop>][ENABLE|DISABLE][ERRORVALID <bError>][FOCUS <fblock>][HOTBOX <cFrame>][MESSAGE <cText>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN5>)][SCROLLBAR]

CMD 81

[SEND|GUISEND <snd>][STATE <sBlock>][TOOLTIP <cTip>][USERMSG <cargo>][VALID <lValid>][WHEN <lWhen>]

Purpose:Creates ComboBox widget and let it process via common READ. ComboBox is aspecial case of the ListBox and can be created also by using the @..GET....LISTBOX command with DROPDOWN clause.

Arguments:<expN1>,<expN2>,expN3>,<expN4> are numeric expressions, specifying the top,left, bottom, right coordinates (in that order) of the open ComboBox widget. In GUImode, you may use numeric values with decimal fractions for row and column,which are then rounded to integer in Terminal i/o mode. To set coordinates at exactpixel value, use the PIXEL clause (or enable SET PIXEL ON)

GET <varN> is a database field or a memory variable of numeric type specifyingthe start item (if > 0) in the list, and returning the selected position (or 0 on ESC).

COMBOBOX USING <obj> is an alternative syntax, specifying to use an alreadyinstantiated object <obj> of ComboBox class with assigned items. When thecoordinates <expN1>...<expN4> are 0 or positive, they will overwrite previously set<obj> coordinates, negative coordinate let previous setting untouched.

Options:The optional clauses of ComboBox are equivalent to Listbox, please refer to [email protected] command.

Description:The @...GET...COMBOBOX command uses the ComboBox class. You may addother class properties by e.g.

Atail(GetList):<ComboBox_instance> := <value>

or by instantiating the object extra, set instances and using the USING <obj> clausein this @..GET..COMBOBOX command.




Related:@..GET, READ, @..GET..LISTBOX, ComboBox class

CMD 82

@...GET LISTBOXSyntax 1:

@ <expN1>,<expN2>,<expN3>,<expN4>GET <varN>LISTBOX <aData>[CAPTION <cCapt>][COLDBOX <cFrame>][COLOR <cColor>][GUICOLOR <cGuiColor>][DEFAULT <defN>][DROPDOWN][DROPMARK <cDrop>][ENABLE|DISABLE][ERRORVALID <bError>][FOCUS <fblock>][HOTBOX <cFrame>][MESSAGE <cText>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN5>)][SCROLLBAR][SEND|GUISEND <snd>][STATE <sBlock>][TOOLTIP <cTip>][USERMSG <cargo>][USING <obj>][VALID <lValid>][WHEN <lWhen>]


GET <varN>LISTBOX USING <obj>[CAPTION <cCapt>][COLDBOX <cFrame>][COLOR <cColor>][GUICOLOR <cGuiColor>][DEFAULT <lDef>][DROPDOWN][DROPMARK <cDrop>][ENABLE|DISABLE][ERRORVALID <bError>][FOCUS <fblock>][HOTBOX <cFrame>][MESSAGE <cText>][PIXEL|NOPIXEL]

CMD 83

[UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN5>)][SCROLLBAR][SEND|GUISEND <snd>][STATE <sBlock>][TOOLTIP <cTip>][USERMSG <cargo>][VALID <lValid>][WHEN <lWhen>]

Purpose:Creates ListBox or ComboBox widget and let it process via common READ.

Arguments:<expN1>,<expN2>,expN3>,<expN4> are numeric expressions, specifying the top,left, bottom, right coordinates (in that order) of the ListBox widget. In GUI mode, youmay use numeric values with decimal fractions for row and column, which are thenrounded to integer in Terminal i/o mode. To set coordinates at exact pixel value,use the PIXEL clause (or enable SET PIXEL ON)

GET <varN> is a database field or a memory variable of numeric type specifyingthe start item (if > 0) in the list, and returning the selected position (or 0 on ESC).

LISTBOX <aData> is one- or two-dimensional array. With one-dimensional, thearray elements contain the displayed text. With two- dimensional, the aData[n,1] isthe displayed text and aData[n,2] is a "hidden" item value available via obj:Value forthe selected item, or obj:GetVal(pos) for any item. The current <obj> object ispassed to the FOCUS and STATE code block.

LISTBOX USING <obj> is an alternative syntax, specifying to use an alreadyinstantiated object <obj> of ListBox or ComboBox class with assigned items.

Options:CAPTION <cCapt> is a text explaining the ListBox

COLDBOX <cFrame> (considered in Terminal i/o mode only) specifies the framedisplayed when the ListBox has no input focus. The default style is pre-defined inthe global array element

_aGlobSetting[GSET_T_C_COLDBOX] := B_SINGLEwhich is used when the COLDBOX clause is omitted.

COLOR <cColor> (considered in Terminal i/o mode only) defines the color settingsfor the ListBox. The string may contain 8 color pairs:

Pair# Used for Default1 Unselected items, without input focus Standard2 Selected item, without input focus Unselected3 Unselected items with input focus Standard4 Selected item with input focus Enhanced5 The list box's border Border6 The list box's caption Standard7 The list box caption's accelerator key Background8 The list box's drop-down button Standard

CMD 84


GUICOLOR <cGuiColor> (considered in GUI i/o mode only) defines the colorsettings for the ListBox. The string may contain 4 color pairs:

Pair# Used for Default1 Unselected items, without input focus black/white2 Selected item, without input focus white/blue3 Unselected items with input focus black/white4 Selected item with input focus white/blue

For not specified pair or for pair specified N/N, the default is used. Note that thestandard background for selected item (with and without input focus) is usually setby the window manager and may hence differ according to the used platform. It isusually W+/RGB(49,106,195) = W+/#316AC3 in Windows, and W+/RGB(8,93,139)= W+/#085D8B in Linux/KDE.

DEFAULT <defN> set the GET <varN> to <defN> value if <varN> is NIL, empty() orof different type than <defN> which must be numeric.

DROPDOWN indicates to create ComboBox instead of ListBox.

DROPMARK <cDrop> (considered in Terminal i/o mode only) specifies the drop-down character displayed for ComboBox. The default style is pre-defined in theglobal array element _aGlobSetting[GSET_T_C_COMBOMARK] := chr(31) which isused when the DROPMARK clause is omitted.



FOCUS <fblock> specifies a code block that is evaluated each time the ListBoxreceives focus. The code block receives two parameters, the current ListBox object,and the obj:HasFocus status.

HOTBOX <cFrame> (considered in Terminal i/o mode only) specifies the framedisplayed when the ListBox has input focus. The default style is pre-defined in theglobal array element _aGlobSetting[GSET_T_C_HOTBOX] := B_DOUBLE which isused when the HOTBOX clause is omitted.

MESSAGE <cText> displays message <text> in status bar or in the SETMESSAGE line when the ListBox receives focus




UNIT=ROWCOL or PIXEL or MM or CM or INCH or DOT or <expN5> specifies unitfor <expN1> .. <expN2> coordinates. The <expN5> is parenthesed numeric value in

CMD 85

range 0 to 5 (i.e. UNIT_ROWCOL to UNIT_DOT). If the UNIT=... clause is notspecified, default is row/col, or the current setting by set(_SET_PIXEL, log) orset(_SET_COORD_UNIT, num). Apply for GUI mode only, ignored otherwise.

SCROLLBAR is available for Clipper compatibility only. In FlagShip, the scrollbar isused automatically when the list is larger than the available widget size.


STATE <sBlock> specifies a code block that is evaluated each time the ListBoxselection changes, i.e. is checked or unchecked. The code block receives twoparameters, the current ListBox object and the select status.

TOOLTIP <cTip> (GUI only) short pop-up message/info displayed when mousecursor is over the ListBox widget, even w/o focus

USERMSG <cargo> assigns the <cargo> value to the ListBox:Cargo instance

USING <obj> specify to use an already instantiated object <obj> of ListBox orComboBox class. Optional only with Syntax 1, i.e. when LISTBOX <aData> is used.When the coordinates <expN1>...<expN4> are 0 or positive, they will overwritepreviously set <obj> object coordinates; negative <expN> coordinate let previous<obj> setting untouched.

VALID <lValid> (post-validation) is a logical expression (or UDF returning a logicalvalue) which is evaluated whenever the user attempts to leave the correspondingfield. Should the expression return a .F. value, the cursor will remain on the currentfield. This feature is often used for lookups using post-processing functions. Todetermine the currently selected Listbox item number, use

item := GetActive():Buffer

WHEN <lWhen> (pre-validation) specifies an expression that must be satisfied inorder to enter the ListBox during a READ

Description:The @...GET...LISTBOX command uses the ListBox or ComboBox class. You mayadd other class properties by e.g.

Atail(GetList):<ListBox_instance> := <value>or by instantiating the object extra, set instances and using the USING <obj> clausein this @..GET..LISTBOX command.

The ListBox class is also used per default in Achoice().

Tuning:The <expN1>..<expN4> coordinates usually specifies the outer box frame, commonfor both GUI and Terminal i/o mode. If you wish in GUI mode these coordinatesspecify the inner box, set

_aGlobSetting[GSET_G_L_LISTBOX_BOX] := .F. // default = .T.

CMD 86

If you don't wish to automatically adjust row/col in GUI mode, set

_aGlobSetting[GSET_G_L_LISTBOX_ADJ ] := .F. // default = .T.

If the above adjustment is on (.T.), you may set the pixel values

_aGlobSetting[GSET_G_N_LISTBOX_TOP ] := -2 // default_aGlobSetting[GSET_G_N_LISTBOX_BOT ] := 2 // default_aGlobSetting[GSET_G_N_LISTBOX_LEFT] := -7 // default_aGlobSetting[GSET_G_N_LISTBOX_RIGH] := 6 // default_aGlobSetting[GSET_G_N_COMBO_HEIGHT] := 4 // default

where the defaults are set in the <FlagShip_dir>/system/initio.prg file

The action on a key or mouse button press is defined in the user modifiable handler<FlagShip_dir>/system/listboxhand.prg. Mouse is supported in GUI mode only.

The default behavior on mouse button click is:

- Left mouse click selects the ListBox item and leaves the ListBox to next GET (ifany), same as press of the Enter or Space key.

- Mid and right mouse button select the item but stays in the ListBox until theEnter or Space key leaves it, except when the object instance SelectBySingle-Click is set .T. (default is .F.) which then behaves same as left mouse click.

By assigning _aGlobSetting[GSET_G_L_LISTBOX_SINGLE]:= .F. you may avoidleaving ListBox by left mouse button. Assigning .F. to SelectBySpace instanceprevent selection by Space key. The supported mouse buttons are specified in thearray _aGlobSetting[GSET_G_A_LISTBOX_MOUSE], see <FlagShip_dir>/system/initio.prg

Example:local ii, aItem, nListb, cTxt := "any text "

set font "courier", 10// _aGlobSetting[GSET_G_L_LISTBOX_BOX] := .F. // coord = inneraItem := {}nListb := 1for ii := 1 to 20aadd(aItem, "Listbox (array) line#" + ltrim(ii))

next@ 4, 5, 11,35 GET nListb LISTBOX aItem@ 12,5 get cTxtreadwait

Example:local ii, oLBox, nListb, cTxt := "any text "

oLBox := Listbox{} // instantiate objectnListb := 3 // start at line 3for ii := 1 to 20oLBox:AddItem("Listbox (object) line#" + ltrim(ii))

next

CMD 87

@ 4,5, 11,35 GET nListb LISTBOX USING oLBox ;GUICOLOR ",W+/#C0C0C0" ;WHEN myReport(0) VALID myReport(1)

// STATE {|obj,selected| myReport(2) }@ 12,5 get cTxtreadwait

Function myReport(mode)local rr := row(), cc := col(), obj := getactive()if mode == 0 // clear

@ 10,40 say space(30)else // display curr. selection

@ 10,40 say "Return: " + ltrim(obj:Buffer) + space(5)endifsetpos(rr, cc)

return .T.



Compatibility:New in FS5, available also (with less options) in CL53

Related:@..GET, READ, @..GET..COMBOBOX, ListBox and ComboBox classes

CMD 88

@...GET PUSHBUTTONSyntax:

@ <expN1>,<expN2>GET <varL>PUSHBUTTON[CAPTION <cCapt>][COLOR <cColor>][DEFAULT <defL>][ENABLE|DISABLE][ERRORVALID <bError>][FOCUS <fblock>][FONT <oFontObj>][FONT <cFontName> [, <nFontSize>] ][MESSAGE <cText>][NOTIFY <nBlock>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN5>)][SEND|GUISEND <snd>][SKIP][STATE <sBlock>][STYLE <cFrame>][TOOLTIP <cTip>][USERMSG <cargo>][USING <obj>][VALID <lValid>][WHEN <lWhen>]

Purpose:Creates PushButton widget and let it process via common READ.

Arguments:<expN1>,<expN2> are numeric expressions, specifying the row and columncoordinate of the push button widget. In GUI mode, you may use numeric valueswith decimal fractions for row and column, which are then rounded to integer inTerminal i/o mode. To set coordinates at exact pixel value, use the PIXEL clause(or enable SET PIXEL ON)

GET <varL> is a database field or a memory variable of logical type returning thestatus, i.e. TRUE if the push button was pressed.

PUSHBUTTON is a mandatory clause.

Options:CAPTION <cCapt> is a text displayed in the push button

COLOR <cColor> (considered in Terminal i/o mode only) defines the color settingsfor the PushButton. The string may contain 4 color pairs:

CMD 89

Pair# Used for Default1 push button w/o input focus Unselected2 push button with input focus, not pressed Enhanced3 push button with input focus, pressed Enhanced4 push button caption's accelerator key Background


DEFAULT <defL> set the GET <varL> to <defL> value if <varL> is NIL, empty() orof different type than <defL> which must be logical.

ENABLE|DISABLE enable (default) or disable the item from READ processing.See also SKIP clause for partial disabling.


FOCUS <fblock> specifies a code block that is evaluated each time thePushButton receives focus. The code block receives two parameters, the currentobj:HasFocus status and PushButton object.

FONT <oFontObj> displays button caption using font object <oFontObj>

FONT <cFontName> displays button caption using font name <cFontName>

FONT <cFontName>,<nFontSize> displays button caption using font name<cFontName> and font size <nFontSize>

MESSAGE <cText> displays message <text> in status bar or in the SETMESSAGE line when the PushButton receives focus

NOTIFY <nBlock> specifies a code block that is evaluated each time thePushButton is pressed or clicked by mouse, to enable the application to react onthe Enter or mouse button press. The code block takes one argument, thePushButton object self. Since the code block is evaluated immediately at mouseclick on the button, even if the current GET object yet differs, it is not advisable topush key(s) via KEYBOARD within the Notify code block body; it may causeunexpected READ behavior. Instead, assign key value(s) to be processed toobjPush:OnClickKeys instance. Alternatively, you may specify action to be takennext in READ by assigning GE_* value to the objPush:OnClickAction instance.The GE_* values are defined in getexit.fh and described in OBJ.Get:ExitState; e.g.GE_WRITE = 6 to save GETs by simulating press of Ctrl-W key, or GE_ESCAPE =7 to exit READ same as press on ESC key, or GE_TOP to skip to first item, etc. Tobe able to check READ exit, LASTKEY() is set K_CTRL_W on GE_WRITE andK_ESC on passing GE_ESCAPE. See example in section FUN.ReadSelect() andbelow.

CMD 90



SKIP disables selecting this button by cursor movement within READ, the item isaccessible by mouse click or by SELECT or ReadSelect() assignment from/withinREAD only. If you wish to generally disable this item, use DISABLE clause (orobjPush:Enabled := .F.) instead.

STATE <sBlock> specifies a code block that is evaluated each time thePushButton selection changes, i.e. is pressed or released. The code block receivestwo parameters, the obj:Buffer indicating the button status (pressed/released) andthe current PushButton object.

STYLE <cFrame> (considered in Terminal i/o mode only) specifies a characterstring that indicates the PushButton delimiters. The default style is pre-defined inthe global array element _aGlobSetting[GSET_T_C_PUSHB_STYLE] := "<>" whichis used when the STYLE clause is omitted.

TOOLTIP <cTip> (GUI only) short pop-up message/info displayed when mousecursor is over the PushButton widget, even w/o focus

USERMSG <cargo> assigns any <cargo> value to the PushButton:Cargo instance

USING <obj> specify to use an already instantiated object <obj> of PushButtonclass.

VALID <lValid> (post-validation) is a logical expression (or UDF returning a logicalvalue) which is evaluated whenever the user attempts to leave the correspondingfield. Should the expression return a .F. value, the cursor will remain on the currentfield. This feature is often used for lookups using post-processing functions. At thisstage, as opposite to NOTIFY, you also may push keys by KEYBOARD in UDF, thecode block however need to return logical.

WHEN <lWhen> (pre-validation) specifies an expression that must be satisfied inorder to enter the PushButton during a READ. At this stage, as opposite to NOTIFY,you also may push keys by KEYBOARD in UDF, the code block however need toreturn logical.

Description:The @..GET..PUSHBUTTON command uses the PushButton class. You may addother class properties (for example a bitmap image) by e.g.

Atail(GetList):<PushButton_instance> := <value>or by instantiating the object extra, set instances and using the USING <obj> clausein this @..GET..PUSHBUTTON command.

CMD 91

Pressing the button by mouse click (GUI only) or by Enter, space, X, Y, T or P keyscalls the codeblock specified by STATE option, which then performs the requestedprogram action. The codeblock may also perform e.g. KEYBOARD chr(K_DOWN)or chr(K_ESC) to skip to next @..GET field or to terminate the READ, otherwise theGET field is not left. But since the code block my be entered twice (one time at keypress and once on key release), better is to use obj:OnClickAction instead ofKEYBOARD, see NOTIFY above. If there is neither STATE nor FOCUS codeblock,the default behavior at pressing the button simulates Enter key to continue READprocess in next GET field.

Example:lPush := lPush2 := lPush3 := lExit := .F.cText := space(20)@ 5,15 GET lPush PUSHBUTTON CAPTION "List .prg files" ;

STATE {|push, obj| myList(push, obj) } ;TOOLTIP "List sources in current directory"

@ 7,15 GET lPush2 PUSHBUTTON CAPTION "Other button" SKIP ;NOTIFY {|obj| myUdf(obj) } ;FONT "Arial",12 ; // or FONT font{"Arial",12}TOOLTIP "Other button accessible by mouse only"

@ 7,25 GET lPush3 PUSHBUTTON NOTIFY {|obj| myUdf2(obj) }Atail(getlist):Width(120, .T.) // width = 120 pixelAtail(getlist):Height(0) // height = autoAtail(getlist):SetImage("mypicture.jpeg") // auto-scale to widthAtail(getlist):Display()@ 9, 5 SAY "any text"@ 9,15 GET cText@ 5,50 GET lExit PUSHBUTTON CAPTION "Exit" ;

NOTIFY {|obj| obj:OnClickKeys := chr(K_ESC) } ;SKIP TOOLTIP "Accessible by mouse click only"

READsetpos(16,0)? "lastkey()=",ltrim(lastkey())wait

FUNCTION myList(lPressed, oPush)local aDir, iWin, iiif !lPressed // button released:

return // nothing to doendifaDir := Directory("*.prg")// uses sub-window via FS2 toolboxiWin := Wopen(3,3, min(Maxrow()-1,len(aDir)+6), 25)for ii := 1 to len(aDir)

@ ii-1, 1 say aDir[ii,1]next?waitWclose(iWin) // close sub-windowKEYBOARD chr(K_DOWN) // exit PushButton

return

CMD 92

FUNCTION myUdf(oPush)alert("button named '" + oPush:Caption + "' pressed")

return

FUNCTION myUdf2(oPush)#include "getexit.fh"alert("button 3 pressed")oPush:OnClickAction := GE_WRITE // go to next GET

return

Example:see FUN.ReadSelect() and <FlagShip_dir>/examples/getread*.prg



Related:@..GET, READ, PushButton class

CMD 93

@...[SAY..] GET RADIOBUTTONSyntax 1:

@ <expN1>,<expN2>GET <varL> RADIOBUTTON[CAPTION <cCapt>][COLOR <cColor>][DEFAULT <lDef>][ENABLE|DISABLE][ERRORVALID <bError>][FOCUS <fblock>][MESSAGE <cText>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN5>)][SEND|GUISEND <snd>][STATE <sBlock>][STYLE <cStyle>][TOOLTIP <cTip>][USERMSG <cargo>][USING <obj>][VALID <lValid>][WHEN <lWhen>]

Syntax 2:@ <expN1>,<expN2>

SAY <cSaytext>[PICTURE <cSayPict>][COLOR <cSayColor>]

GET <varL> RADIOBUTTON[CAPTION <cCapt>][COLOR <cGetColor>][DEFAULT <lDef>][ENABLE|DISABLE][ERRORVALID <bError>][FOCUS <fblock>][MESSAGE <cText>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN5>)][SEND|GUISEND <snd>][STATE <sBlock>][STYLE <cStyle>][TOOLTIP <cTip>][USERMSG <cargo>][USING <obj>][VALID <lValid>][WHEN <lWhen>]

CMD 94

Purpose:Creates RadioButton widget and let it process via common READ. Usually, theradio button is not used stand alone, but is grouped in RadioGroup to get anexclusive ON status of one button of the group.

Arguments:<expN1>, <expN2> are numeric expressions, specifying the row and columncoordinates. With Syntax 1: coordinates of the widget. With Syntax 2: coordinate ofthe capture text, the widget column coordinate is the over-next column behind thetext <cSaytext> end, same as in @..SAY..GET. In GUI mode, you may use numericvalues with decimal fractions for row and column, which are then rounded to integerin Terminal i/o mode. To set coordinates at exact pixel value, use the PIXEL clause(or enable SET PIXEL ON)

SAY <cSaytext> is a text caption identifying the RadioButton on the screen. Better,common practice is to use the CAPTION clause.

GET <varL> is a database field or a memory variable of logical type storing the "on"status of the RadioButton.

RADIOBUTTON clause is mandatory here.

Options:CAPTION <cCapt> is a text explaining the radio button

COLOR <cSayColor> is an optional color specification for the @..SAY text.

COLOR <cGetColor> (considered in Terminal i/o mode only) defines the colorsettings for the radio button. The string may contain 8 color pairs:

Pair# Used for Default1 Radio button without input focus, unselected Unselected2 Radio button without input focus, selected Unselected3 Radio button with input focus, unselected Unselected4 Radio button with input focus, selected Enhanced5 Radio button's caption Standard6 Radio button caption's accel. key w/o focus Standard7 Radio button caption's accel. key with focus Background8 Radio button and caption, disabled Border


DEFAULT <lDef> set the GET <varL> to <lDef> value if <varL> is NIL, empty() orof different type than <lDefa> which must be logical.

CMD 95

FOCUS <fblock> specifies a code block that is evaluated each time the Radiobutton receives focus. The code block receives two parameters, the currentRadioButton object, and the oBox:HasFocus status.

MESSAGE <cText> displays message <text> in status bar or in the SETMESSAGE line when the RadioButton receives focus

PICTURE <cSayPict> is the optional picture of @..SAY text






STATE <sBlock> specifies a code block that is evaluated each time theRadioButton state changes, i.e. is checked or unchecked. The code block receivestwo parameters, the current RadioButton object, and the oBox:Buffer status.

STYLE <cStyle> (considered in Terminal i/o mode only) specifies a character stringthat indicates the RadioButton delimiter characters and status display. The defaultstyle is pre-defined in the global array element _aGlobSetting[GSET_T_C_RADBUT_STYLE] := "( *)" which is used when the STYLE clause is omitted.

TOOLTIP <cTip> (GUI only) short pop-up message/info displayed when mousecursor is over the RadioButton widget, even w/o focus

USERMSG <cargo> assigns the <cargo> value to the RadioButton:Cargo instance

USING <obj> use already instantiated RadioButton object <obj>, avoid a newcreation/instantiation

VALID <lValid> (post-validation) is a logical expression (or UDF returning a logicalvalue) which is evaluated whenever the user attempts to leave the correspondingGET. Should the expression return a .F. value, the cursor will remain on the currentfield. This feature is often used for lookups using post-processing functions.

WHEN <lWhen> (pre-validation) specifies an expression that must be satisfied inorder to enter the RadioButton during a READ

Description:The @...GET...RADIOBUTTON uses the RadioButton class. You may add otherclass properties by e.g. Atail(GetList):<RadioButton_instance> := <value> or by

CMD 96

instantiating the object extra, set instances and using the USING <obj> clause inthis @..GET..RADIOBUTTON command.




Related:@..GET, READ, @..GET..RADIOGROUP, RadioButton class

CMD 97

@...GET RADIOGROUPSyntax 1:

@ <expN1>,<expN2>,<expN3>,<expN4>GET <varN> RADIOGROUP <aData>[CAPTION <cCapt>][COLDBOX <cFrame>][COLOR <cColor>][DEFAULT <defN>][ENABLE|DISABLE][NONEXCLUSIVE][ERRORVALID <bError>][FOCUS <fblock>][HOTBOX <cFrame>][MESSAGE <cText>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN5>)][SEND|GUISEND <snd>][STATE <sBlock>][TOOLTIP <cTip>][USERMSG <cargo>][USING <obj>][VALID <lValid>][WHEN <lWhen>]


GET <varN> RADIOGROUP USING <obj>[CAPTION <cCapt>][COLDBOX <cFrame>][COLOR <cColor>][DEFAULT <lDef>][ENABLE|DISABLE][NONEXCLUSIVE][ERRORVALID <bError>][FOCUS <fblock>][HOTBOX <cFrame>][MESSAGE <cText>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN5>)][SEND|GUISEND <snd>][STATE <sBlock>][TOOLTIP <cTip>][USERMSG <cargo>][VALID <lValid>][WHEN <lWhen>]

CMD 98

Purpose:Creates RadioGroup widget and let it process via common READ. The radio groupsummarizes radio buttons and allows to exclusively select one button at a time. Youmay change this behavior to nonexclusive choice allowing multiple buttonselection by assigning Atail(GetList):Exclusive := .F. or by using already instantiatedRadioGroup object and Syntax 2.

Arguments:<expN1>,<expN2>,expN3>,<expN4> are numeric expressions, specifying the top,left, bottom, right coordinates (in that order) of the RadioGroup widget. In GUImode, you may use numeric values with decimal fractions for row and column,which are then rounded to integer in Terminal i/o mode. To set coordinates at exactpixel value, use the PIXEL clause (or enable SET PIXEL ON)

GET <varN> is a database field or a memory variable of numeric type specifyingthe pre-selected button (if > 0) in the list, and returning the selected position (or 0on ESC).

RADIOGROUP <aData> is one-dimensional array containing the buttons capture(string text) or RadioButton objects. You may instantiate the row/col of eachRadioButton absolutely or relative if the coordinate is negative. In such a case,row/col == -1 is 1st row/column of the RadioGroup, -2 is the 2nd row or column ofthe RadioGroup, and so forth.

RADIOGROUP USING <obj> is an alternative syntax, specifying to use an alreadyinstantiated object <obj> of RadioGroup class with assigned RadioButton items.You may use absolute or relative RadioButton coordinates, see above.

Options:CAPTION <cCapt> is a text explaining the RadioGroup

COLDBOX <cFrame> (considered in Terminal i/o mode only) specifies the framedisplayed when the RadioGroup has no input focus. The default style is pre-definedin the global array element _aGlobSetting[GSET_T_C_COLDBOX] := B_SINGLEwhich is used when the COLDBOX clause is omitted.

COLOR <cColor> (considered in Terminal i/o mode only) defines the color settingsfor the RadioGroup. The string may contain 3 color pairs:

Pair# Used for Default1 Radio group border Border2 Radio group caption Standard3 Radio group capt key Background


DEFAULT <defN> set the GET <varN> to <defN> value if <varN> is NIL, empty() orof different type than <defN> which must be numeric.

CMD 99


NONEXCLUSIVE The default RadioGroup behavior is "exclusive", which allows toset only one button within the group. When specifying the NONEXCLUSIVE clause,you may select any RadioButton within the group and/or disable it. It is equivalent tooGetItem:Exclusive := .F. assignment. In non-exclusive mode, the return value isthe first selected item, see example below for determining all of them. In the defaulthandler <FlagShip_dir>/system/radgrouphand.prg, the LeftMouse Button selectsand RightMouseButton de-selects the status.


FOCUS <fblock> specifies a code block that is evaluated each time theRadioGroup receives focus. The code block receives two parameters, the currentRadioGroup object, and the obj:HasFocus status.

HOTBOX <cFrame> (considered in Terminal i/o mode only) specifies the framedisplayed when the RadioGroup has input focus. The default style is pre-defined inthe global array element _aGlobSetting[GSET_T_C_HOTBOX] := B_DOUBLE whichis used when the HOTBOX clause is omitted.

MESSAGE <cText> displays message <text> in status bar or in the SETMESSAGE line when the RadioGroup receives focus






STATE <sBlock> specifies a code block that is evaluated each time theRadioGroup selection changes, i.e. if one radio button is set ON or OFF. The codeblock receives two parameters, the current RadioGroup object, and the obj:Buffercontent specifying the selected position of the button. To check the button status,you may determine it from the radio button object available via obj:GetItem():Bufferor obj:GetItem(pos):Buffer

TOOLTIP <cTip> (GUI only) short pop-up message/info displayed when mousecursor is over the RadioGroup widget, even w/o focus

USERMSG <cargo> assigns the <cargo> value to the RadioGroup:Cargo instance

CMD 100

USING <obj> specify to use an already instantiated object <obj> of RadioGroupclass. Optional only with Syntax 1, i.e. when the clause RADIOGROUP <aData> isused.

VALID <lValid> (post-validation) is a logical expression (or UDF returning a logicalvalue) which is evaluated whenever the user attempts to leave the correspondingfield. Should the expression return a .F. value, the cursor will remain on the currentfield. This feature is often used for lookups using post-processing functions.

WHEN <lWhen> (pre-validation) specifies an expression that must be satisfied inorder to enter the RadioGroup during a READ

Description:The @...GET...RADIOGROUP command uses the RadioGroup class. You may addother class properties by e.g. Atail(GetList):<RadioGroup_instance> := <value> orby instantiating the object extra, set instances and using the USING <obj> clause inthis @..GET..RADIOGROUP command. Note that some instances/settings applyafter displaying the buttons.

Tuning:The action on a key or mouse button press is defined in the user modifiable handler<FlagShip_dir>/system/radgrouphand.prg. Mouse is supported in GUI mode only.The default behavior on mouse button click is: Left mouse click selects theRadioButton and leaves the RadioGroup to next GET (if any), same as the +, -,space, x, y, t, n, f key press. Mid and right mouse button select the buttonbut stays in the RadioGroup until the corresponding key leaves it. With non-exclusive RadioGroup, left, mid and right mouse click toggles the button on/offstatus, same as space or 'x' key, the +, y, t key sets the RadioButton on, and -,n, f key press sets it off.

By assigning _aGlobSetting[GSET_G_L_RADBUT_SINGLE] := .F. you may avoidleaving RadioGroup by left mouse button. The supported mouse buttons arespecified in _aGlobSetting[GSET_G_A_RADBUT_MOUSE] array, see<FlagShip_dir>/system/initio.prg

Example:local nButt := 1, nButt2 := 2, cTxt := space(10)@ 4,10 say "select: +|y|t|-|n|f|space|x|LMB|RMB"@ 5,10,9,25 GET nButt RADIOGROUP ;

{ RadioButton{-1,-1, "&First", ""} , ;RadioButton{-2,-1, "&Second", ""}, ;RadioButton{-3,-1, "&Third", ""} }

@ 5,30,9,45 GET nButt2 RADIOGROUP {"One","Two","T&hree"}@ 11,10 GET cTxtREADsetpos(15,0)? "Selected buttons=", ltrim(nButt), ltrim(nButt2)wait

CMD 101

Example:local aGroup := array(3), nButt := 2, cTxt := space(10)local aButtons := {}aGroup[1] := RadioButton{-1,-1, "&First", ""}aGroup[2] := RadioButton{-2,-1, "&Second", ""}aGroup[3] := RadioButton{-3,-1, "&Third", ""}

@ 3,10 say "non-exclusive"@ 4,10 say "select: +|y|t|LMB, clear: -|n|f|RMB, toggle:space|x"

@ 5,10,9,25 GET nButt RADIOGROUP aGroup NONEXCL ;VALID CheckButtons(@aButtons)

aGroup[3]:Checked := .T. // set addit. button 3 on@ 11,10 GET cTxtREAD

setpos(15,0)? "Selected buttons:"aeval(aButtons, {|x| qqout(x)})wait

FUNCTION CheckButtons(arr) // called in Valid()local ii, obj := GetActive()arr := {}if IsObjProperty(obj, 2, "exclusive") .and. !obj:Exclusivefor ii := 1 to obj:ItemCount

if obj:getitem(ii):Checked // RadioButton itemaadd(arr, ii)

endifnext

endifreturn .T.




Related:@..GET, READ, @..GET..COMBOBOX, RadioGroup and ComboBox classes

CMD 102

@...GET TBROWSESyntax:

@ <expN1>,<expN2>,<expN3>,<expN4>GET <var>TBROWSE [USING] <obj>[CAPTION <cCapt>][COLDBOX <cFrame>][COLOR <cColor>][ENABLE|DISABLE][ERRORVALID <bError>][HOTBOX <cFrame>][MESSAGE <cText>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN5>)][SEND|GUISEND <snd>][TOOLTIP <cTip>][USERMSG <cargo>][VALID <lValid>][WHEN <lWhen>]

Purpose:Creates TBrowse widget and let it process via common READ.

Arguments:<expN1>,<expN2>,expN3>,<expN4> are numeric expressions, specifying the top,left, bottom, right coordinates (in that order) of the TBrowse widget. In GUI mode,you may use numeric values with decimal fractions for row and column, which arethen rounded to integer in Terminal i/o mode. To set coordinates at exact pixelvalue, use the PIXEL clause (or enable SET PIXEL ON)

GET <var> is a memory variable of any type not explicitly used but required forREAD.

TBROWSE [USING] <obj> specifies the already instantiated object <obj> ofTBrowse class with assigned TbColumn items.

Options:CAPTION <cCapt> is not used by @..GET..TBROWSE but is supported for cross-compatibility purpose to other @..GET commands only.

COLDBOX <cFrame> (considered in Terminal i/o mode only) specifies the framedisplayed around the TBrowse widget, containing either zero or at least eightcharacters (e.g. the B_SINGLE constant in box.fh). The default is no frame, seeTbrowse:Border instance.

COLOR <cColor> (considered in Terminal i/o mode only) defines the color settingsfor the TBrowse. Unlike in other @..GET.. commands, this clause assigns the

CMD 103

Tbrowse:ColorSpec instance which can contain many different color pairs as youneed and the pair is selected thereof via Tbrowse:ColorBlock.



HOTBOX <cFrame> (considered in Terminal i/o mode only) is equivalent to theCOLDBOX <cFrame> clause and supported for cross-compatibility purpose to [email protected] commands only.

MESSAGE <cText> displays message <text> in status bar or in the SETMESSAGE line when the TBrowse receives focus






TOOLTIP <cTip> (GUI only) short pop-up message/info displayed when mousecursor is over the TBrowse widget, even w/o focus

USERMSG <cargo> assigns the <cargo> value to the TBrowse:Cargo instance

VALID <lValid> (post-validation) is a logical expression (or UDF returning a logicalvalue) which is evaluated whenever the user attempts to leave the correspondingfield. Should the expression return a .F. value, the cursor will remain on the currentfield. This feature is often used for lookups using post-processing functions.

WHEN <lWhen> (pre-validation) specifies an expression that must be satisfied inorder to enter the TBrowse during a READ

Description:The @...GET...TBROWSE command uses the TBrowse class.



Related:@..GET, READ, TBrowseArr(), TBrowseDb(), TBrowse class

CMD 104

@...TOSyntax:

@ <expN1>,<expN2>TO <expN3>,<expN4>[DOUBLE][COLOR <expC5>][GUICOLOR <expC6>][PRINTCOLOR <expC7>][PIXEL|NOPIXEL][UNIT=ROWCOL|PIXEL|MM|CM|INCH|DOT|(<expN8>)]

Purpose:Draws boxes on the screen using single or double lines using the IBM-PC8 semi-graphic character set.

Arguments:<expN1...expN4> are the coordinates for the upper, left and lower, right cornersrespectively. If <expN1> and <expN3> are the same, a horizontal line is drawn. If<expN2> and <expN4> are the same, a vertical line is drawn. The <expN3> and<expN4> are limited by MAXROW() and MAXCOL(). In GUI mode, you may usenumeric values with decimal fractions for row and column, which are then roundedto integer in Terminal i/o mode. To set coordinates at exact pixel value, use thePIXEL clause (or enable SET PIXEL ON).

Options:DOUBLE: If this clause is specified, a double-line box or otherwise a single-line boxis drawn.

COLOR <expC5> defines the color string (see SET COLOR) in which to display thebox lines. If not specified, the box is drawn using the current color setting. The"standard" color pair is used.

GUICOLOR <expC6> specifies the color of box lines in GUI mode. Only the firstcolor pair (standard) is significant. If GUICOLOR is set, this color is used in GUImode regardless the current SET GUICOLOR on/off. If omitted, default color isused. This clause apply for GUI mode only, and is ignored otherwise.

CMD 105


Description:@...TO draws a single or double line box on the screen. The cursor is set into theboxed region at <expN1> +1, <expN2> +1. For customized or filled boxes, use [email protected] command instead.

It draws always in Term mode, in GUI only if SET GUITRANSL LINES is ON. Seealso @..DRAW for GUI only drawing

Example:SET COLOR TO "W+/B"@ 10,10 CLEAR TO 20,60@ 16,10 TO 20,60 // box single lines@ 10,10 TO 15,60 DOUBLE COLOR "GR+/B" // box double lines@ 10,15 TO 20,15 // vertical line


Compatibility:The COLOR option is new in FS4. The physical output on the screen depends onthe terminal emulation chosen (environment variable TERM), the ability of theterminal to display the required graphical characters, and the via FSchrmap.defoutput mapping applied. See also LNG.5.1.4, section SYS, and FS_SET("outmap").

Translation:DISPBOX (expN1, expN2, expN3, expN4, 1|2 [, expC5 ])

Related:@...BOX, @...CLEAR, SCROLL(), SET COLOR, FS_SET("outmap")

CMD 106

ACCEPT ... TOSyntax:

ACCEPT [<exp>] TO <memvar>Purpose:

Waits for a string to be typed in from the keyboard. The result is placed in a memoryvariable.

Arguments:<memvar> is the memory variable where the input is stored. If the variable is notdeclared or is not visible, a new autoPRIVATE is created.

Options:Prompt: <exp> is the prompt which is displayed in front of the entry area. It can bean expression of any data type. If not given, no prompt is displayed.

Description:ACCEPT is a waiting console command. First, a NEW LINE and the prompt (or "")is displayed. The characters typed in from the keyboard are stored in the specifiedmemory variable. Keyboard entry is terminated by the ENTER key. If nothing wastyped in, the variable contains a null string "".

BACKSPACE is the only special key supported.

Example:ACCEPT "Enter your name: " TO name

Classification:sequential screen output, waiting keyboard input

Translation:<memvar> := __ACCEPT (exp)

Related:@...SAY...GET, INPUT, WAIT, KEYBOARD, INKEY()

CMD 107

ACCESS METHODASSIGN METHODSyntax:

ACCESS [METHOD] <methName> [( )]CLASS <className> [AS <type>]

Syntax:ASSIGN [METHOD] <methName> (<par>)

CLASS <className> [AS <type>]

See detailed description in the METHOD command.

CMD 108

ANNOUNCESyntax:

ANNOUNCE <module>Purpose:

Declares a module identifier for the linker.

Arguments:<module> is the identifier name, given as literal. The name may be of any lengthand is case-insensitive. Only the first 10 characters are significant. The name maynot start with an underscore. The <module> name must be unique for the wholeapplication.

Description:The ANNOUNCE declaration statement specifies a module identifier (referencename or tag) to satisfy the REQUEST declaration (external request) from other .prgfiles during the link phase.

ANNOUNCE is generally used together with the -na compilation switch to generatea linker definition point, when the UDFs or UDPs declared there are exclusivelyreferred to by macro or are declared as INIT/EXIT PROCEDUREs only.

Note: If the -na compiler switch is omitted, the FlagShip compiler produces anautomatic procedure <file>, which will also satisfy an EXTERN <file> or REQUEST<file> declaration given elsewhere. See also the PROCEDURE command.

Only one ANNOUNCE declaration for a .prg file is allowed. All subsequentANNOUNCE declarations produce a compiler warning and will be ignored.

The ANNOUNCE statement is nearly same as a declaration of

PROCEDURE <module>

RETURN .T.

Example:*** file test.prg, compiled with: FlagShip test*.prg ***REQUEST test1// or: EXTERNAL test1// or: EXTERNAL test2var := "test2"DO &varQUIT

*** file test1.prg ****** PROCEDURE test1 // automatic procedure*** RETURN .T. // generated by FlagShipPROCEDURE test2? "being now in test2"RETURN

CMD 109

Example:*** file test.prg, compiled with: FlagShip test*.prg -naREQUEST test1// or: EXTERNAL test2var := "test2"DO &varQUIT

*** file test1.prg ***PROCEDURE test2? "being now in test2"RETURN

Example:*** file test.prg, compiled with: FlagShip test*.prg -naREQUEST test5// or: EXTERNAL test2var := "test2"DO &varQUIT

*** file test1.prg ***ANNOUNCE test5 // new module namePROCEDURE test2? "being now in test2"RETURNEXIT PROCEDURE endproc // called by FlagShip only? "bye, bye"RETURN

Compatibility:Available in FS4 and C5.2 only.

Classification:compiler/linker

Related:REQUEST, EXTERNAL

CMD 110

APPEND BLANKSyntax:

APPEND BLANKPurpose:

Adds a new empty record to the end of the currently selected database.

Description:After APPENDing, the new blank record becomes the current record. The new fieldvalues are initialized to the empty values for each data type: character fields arefilled with spaces; numeric fields are zero; logical fields are assigned false (.F.);date fields are assigned CTOD(""); and memo fields are left empty.

Multiuser:In shared mode, APPEND BLANK automatically locks the new record. The lockremains active until UNLOCK or another lock (or APPEND BLANK) is executed inthe corresponding working area. This automatic lock does not release an FLOCK()setting. If another application or user has locked the database with FLOCK(), therecord is not APPENDed and NETERR() function returns TRUE.

When performing operations on the SAME physical database (used concurrently indifferent working areas), see chapter LNG.4.8.7.

Example:Appending a new record in multiuser/multitasking mode:

SET EXCLUSIVE OFF // SET.. is not necessary,USE employee // if USE...SHARED is used? RECCOUNT() //100APPEND BLANKWHILE NETERR()? "waiting for successful append..."INKEY (1) // delay 1 secondAPPEND BLANK // try again

ENDDO? LASTREC(), RECNO() // 101 101FOR i = 1 TO FCOUNT()fldnam = FIELD(i)? EMPTY(&fldnam) // .T.

NEXT // All fields are emptyREPLACE name WITH "Smith"UNLOCK

Classification:database

Translation:DBAPPEND ()

Related:APPEND FROM, NETERR(), RLOCK(), FLOCK(), UNLOCK, oRdd:APPEND()

CMD 111

APPEND ... FROMSyntax:

APPEND FROM <file>|(<expC1>)[<scope>][FIELDS <fieldList>][FOR <condition>][WHILE <condition>][SDF | DELIMITED [WITH

BLANK|<delimiter>|(<expC2>)]][VIA <expC3>]

Purpose:Adds records to the current database file from an ASCII or CSV text file, or anotherdatabase file.

Arguments:FROM <file>|(<expC1>) is the name of the source file. If no extension is specified,it is assumed to be .dbf. When specifying the clause SDF or DELIMITED, thedefault is the .txt extension and the file is assumed to be an ASCII text.

Options:FIELDS <fieldList> If given, data is APPENDed only to the specified fields. For SDFor DELIMITED, it determines the order of fields in the text file according to thecurrently open & selected database; otherwise the field order of the target databaseapply.

<scope> is the part of the source database file to APPEND FROM. The defaultscope is ALL source records. See other valid scope options in the generalcommand description at begin of this section.

<condition> specifies additional FOR and/or WHILE filtering of the records to beappended within the given <scope>. See the general command description at beginof the CMD section.

SDF identifies a System Data Format ASCII file. Each record is of a fixed lengthand ends with a line feed (LF) or CR/LF. Data are read until end-of-file or up to theDOS mark Ctrl-Z (1A hex), when scope is not given.

SDF: file formatField separator NoneRecord separator LF or CR/LF = 0A hex or 0D+0A hexEnd of file marker file-end or the DOS eof = 1A hexCharacter fields Padded with trailing blanksNumeric fields Padded with leading blanks or zerosDate fields YYYYMMDD or MM/DD/[YY]YY or DD.MM.[YY]YYLogical fields 'T' is true, anything else is falseMemo fields Ignored

CMD 112

DELIMITED identifies an ASCII text file, where fields are separated by commas andcharacter fields are bounded by double quotation marks, which are the defaultdelimiters. Note that character fields not bounded by delimiters will be appendedcorrectly, if commas are not part of the field contents. Fields and records arevariable length and end with a line feed or CR/LF. When scope is not given, dataare read until end of the text file, or up to the DOS mark Ctrl-Z (1A hex).

DELIMITED [WITH delimiter]:file formatField separator Comma (,) or specified in <delimiter>Record separator LF or CR/LF = 0A hex or 0D+0A hexEnd of file marker file-end or the DOS eof = 1A hexCharacter fields May be delimited by quotas ("...") or

the <delimiter>, trailing blanks or TABs may betruncated

Numeric fields Leading blanks and zeros may be truncatedDate fields YYYYMMDD or MM/DD/[YY]YY or DD.MM.[YY]YYLogical fields 'T' is true, anything else is falseMemo fields Ignored

The date field is checked for YYYYMMDD like STOD(), and on failure byDD.MM.[YY]YY or MM/DD/[YY]YY etc. like CTOD() according to current SET DATEsetting.

DELIMITED WITH <delimiter>|(<expC2>) identifies a delimited ASCII text file,where character fields are delimited with the specified delimiter, and the fields areseparated by comma or given separator. Note: this clause, if given, must be the lastone in the command. To avoid misinterpretation, it is better to enclose the delimiterin quotas. DELIMITED WITH '"' is the same as DELIMITED only clause, andassumes fields either w/o any delimiter, or enclosed in "..." quotas. The <delimiter>string may contain 0, 1, 2 or 3 characters:

0 char: equivalent to DELIMITED WITH '"' or WITH '",' or WITH '"",'1 char: left + right field delimiter, field separator is comma (,)2 char: 1st=left + right field delimiter, 2nd=field separator3 char: 1st=left, 2nd=right field delimiter, 3rd=field separator

Field delimiters are considered only when the first character after field separator isthe left delimiter and the last character before next separator is the given rightdelimiter. Delimiters are mostly used to store field separators (like commas) withinthe field, or to avoid skipping leading/trailing spaces and TABs of the character field.

For CSV text files (like export from Excel etc.), the common clause is DELIMITEDWITH '"";' or DELIMITED WITH ('""' + chr(9))

DELIMITED WITH BLANK identifies an ASCII text file, where fields are separatedby one space and character fields are not bounded by delimiters. It is equivalent toDELIMITED WITH (space(3)) clause.

CMD 113

DELIMITED WITH BLANK: fileformatField separator Single blank space or TAB = 20 or 09 hexRecord separator LF or CR/LF = 0A hex or 0D+0A hexEnd of file marker file-end or the DOS eof = 1A hexCharacter fields Not delimited, trailing blanks may be

truncated, no leading blanks or TABs areallowed.

Numeric fields Leading zeros may be truncatedDate fields YYYYMMDD or MM/DD/[YY]YY or

DD.MM.[YY]YYLogical fields 'T' is true, anything else is falseMemo fields Ignored

VIA <expC3> specifies the name of the RDD (replaceable database driver) to beused to import the desired data, given as a quoted string or character variable. Thedefault driver is "DBFIDX".

Description:If the source file is a database, only fields with the same name are appended.Fields of different type or size are automatically converted by FlagShip.

Deleted records in the source database are also appended, but not marked asdeleted in the target file. If SET DELETED is ON, deleted records from the sourcefile are not appended.

Appending from an ASCII file: if the FIELD clause is not specified, the fields areassumed to be in the order of the target file. Specifying the FIELD clause alsodeclares the order of the fields in the source file.

If the ASCII record is too short, only the available fields will be accepted. An emptysource line will be appended as an empty record in the target database.

Note: It is not recommended to use TABs in ASCII files, especially not within theSDF file. FlagShip expands the TAB mark (Ctrl-I, 09hex) to one space only,because the TAB width is variable on UNIX. When editing the ASCII file, usespaces instead of TABs and do not use the auto-indent option of your text editor.

Multiuser:APPEND FROM automatically locks and unlocks the new record. FLOCK() orexclusive usage by the programmer may be specified but is not required. Thesource database will be opened in SHARE mode, the text source in read-onlymode. If access is denied, a run-time error occurs.

CMD 114

Example:Get the first 10 records from waitlist.dbf into the current database orders.dbf, alsoremove them in waitlist.

USE orders? RECCOUNT() // 255APPEND NEXT 10 FROM waitlistUSE waitlist NEWDELETE NEXT 10PACKSELECT orders? RECCOUNT() // 265

Example:APPEND FROM file1 SDFAPPEND FROM file2 SDF FIELDS name,address,earningAPPEND FROM file3.xyz FIELDS address, name, city, memo ;

NEXT 50 FOR upper(SUBSTR(name,1)) >= "M" ;DELIMITED WITH ";"

Classification:database and ASCII file import

Compatibility:The automatic data conversion is new in FS4 and is not supported by Clipper.FlagShip supports both UNIX and MS-DOS ASCII text files. Also the end-of-linemark LF or CR/LF and the end-of-file CR/LF/EOF are supported.

Source:The text file for SDF or DELIMITED clause is read by ASCIRDD driver, available(and user-modifiable) in <FlagShip_dir>/system/ascirdd

Translation:__DBAPP ("file", {"field1" [,"field2.."]}, ;

{forCond}>, {whileCond}, [next], [record], [.rest.] )__DBAPPSDF ("file", {"field1" [,"field2.."]}, ;

{forCond}>, {whileCond}, [next], [record], [.rest.] )__DBAPPDELIM ("file", "delim", {"field1" [,"field2.."]}, ;

{forCond}>, {whileCond}, [next], [record], [.rest.] )

Related:COPY, FREAD(), MEMOREAD(), oRdd:AppendDB, oRdd:AppendSDF(),oRdd:AppendDelimited()

CMD 115

AVERAGE ... TOSyntax:

AVERAGE [<scope>] <expList> TO <memvarList>[FOR <condition>][WHILE <condition>]

Purpose:Averages a list of numeric expressions for a range of records in the currentdatabase file and puts the results in the memory variables specified.

Arguments:<expList> is a list of numeric expressions to AVERAGE each processed record.

<memvarList> specifies the set of variables in which the results of averaging are tobe put. This list must have the same number of elements as the <expList>. Existingvariables with the same names are overwritten; non-existing ones are created asautoPRIVATE.

Options:<scope> is the part of the current database file to be averaged. The default scopeis ALL.

<condition> specifies additional FOR and/or WHILE filtering of the averagedrecords within the given <scope>. See the general command description.

Example:Check the average age of the male employees. Note the usage of the WHILEclause for other purposes, here for counting:

LOCAL count := 0, male := 0USE employeeyear = YEAR(DATE())AVERAGE year - YEAR(birthdate) TO aver_age ;FOR UPPER(sex) == "M" ;WHILE (count++, IF(UPPER(sex)=="M",++male,0), .T.)

? "The average age of", male, "men, i.e.", ;male * 100/count, "% of the staff is", aver_age, "years"


Translation:M->__Avg := var := 0DBEVAL ({|| M->__Avg := M->__Avg + 1, var := var+ field },;

{for}, {while}, [next], [rec], [.rest.] )var := var / M->__Avg

Related:SUM, TOTAL, oRdd:Average()

CMD 116

BEGIN SEQUENCE...ENDSyntax:

BEGIN SEQUENCE<statements>

[BREAK [<exp>]]<statements>

[RECOVER [USING <var>]]<statements>

END|ENDSEQUENCEPurpose:

A control structure to handle program exceptions.

Arguments:BEGIN SEQUENCE defines the start of the control structure.

END[SEQUENCE] defines the end of the structure. Executing BREAK withoutRECOVER passes the control past this statement. On nested BEGIN..END, thehigher control structure becomes active for the next BREAK.

Options:BREAK: when encountered, terminates the sequence by branching the executionto the first statement following the corresponding RECOVER statement if one isspecified, or the matching ENDSEQUENCE statement. If executed outside of theBEGIN..END structure, run- time errors occur.

BREAK <exp> passes the <exp>, which is usually an error object, to the <var> ofthe RECOVER USING clause.

RECOVER defines an entry point in the BEGIN..END sequence where controlbranches, following a BREAK statement.

RECOVER USING <var> receives the value returned by the BREAK <exp>. Ingeneral, <var> is an error object.

Description:BEGIN SEQUENCE...END allows to BREAK from anywhere inside a sequence ofstatements, similar to a GOTO or JUMP <label> in other programming languages.

The BREAK statement can also be placed in nested procedures or functions,causing the same effect. FlagShip has no limitation in nesting BEGIN..END, just aswith other control structures or UDFs.

A typical use of BEGIN SEQUENCE...END is to define a section of code whereerrors may occur, as a sequence structure. You can customize the error routines toallow BREAKing the sequence from within. After being out of the sequence, orwithin the RECOVER section, you can inform the user to check the access rights,turn the printer on-line or whatever happened.

CMD 117

By using the ISBEGSEQ() function, you may check elsewhere in the application, ifthe BREAK will reach a RECOVER or ENDSEQUENCE statement.

Example:To exit nested control structures at once:

BEGIN sequencebreak_yes = .T.if ...

if ...do while .T.

if errorBREAK ──┐ Jump to end of structure

endif │enddo │BREAK ──┤ Jump to end of structure

endif │endif │break_yes = .F. │

END <─┘IF break_yes

? "Error break... "QUIT, LOOP, RETURN etc.

ENDIF

Example:Exit above structures using RECOVER:

BEGIN sequenceif ...

if ...BREAK ──┐ Jump to the recover section

end │BREAK ──┤ Jump to the recover section

endif ──┐ │RECOVER │ <─┘

? "Error handling" │END <─┘ Continue std. execution? "Continuing..."

CMD 118

Example:Exit nested procedures

BEGIN sequenceDO first? "all o.k." <───┐

END <─┐│? "watch for ok" ││

││PROCEDURE first ││if error ││

BREAK ──┤│endif ││DO nextproc ││return ──│─┘ normal return

│PROCEDURE nextproc │if error │

BREAK ──┘ Error, jump to end of structureendif

Example:LOCAL name, path := ""DO WHILE .T.

BEGIN SEQUENCEIF ! FILE("test.prg")

BREAK "text file test.prg"ENDIFTYPE test.prgIF ! FILE("mydbf.dbf")

BREAK "database mydbf.dbf"ENDIFUSE mydbf

RECOVER USING nameIF empty(path)

path = "/usr/data"SET PATH TO (path)LOOP // try another path

ENDIF? "cannot open " + nameQUIT

ENDSEQUENCEEXIT // exit the loop

ENDDO

Example:Check for correctly OPENing the database. One error handle will be activated. Theerror may be triggered in any UDF called from here:

LOCAL brEobj, saveEobjLOCAL errHand := {|e| my_err(e) }saveEobj := ERRORBLOCK (errHand) // install error handler

CMD 119

DO WHILE .T.BEGIN SEQUENCE // start of sequence

my_open_dbf ("address")? ".dbf correctly opened" // and jump to ENDSEQUENCE

RECOVER USING brEobj // receives error objectIF brEobj == NIL // BREAK only, message

: (statements) // already printedELSE // BREAK with object

? "Error :"IF !EMPTY(brEobj:CARGO)

?? brEobj:CARGO // print user messageELSE

?? LTRIM(STR(brEobj:GENCODE)) + ;" on file access " + brEobj:FILENAME + ;":" + brEobj:DESCRIPTION

ENDIFENDIFIF myErrObj:CANRETRY

LOOPENDIFQUIT

ENDSEQUENCE // end of sequenceEXIT // exit the loop

ENDDOERRORBLOCK (saveEobj) // reset ErrorObjQUIT

FUNCTION my_open_dbf (filename) /* may be included in-------------------- another .prg file */IF !FILE(filename + ".dbf")? "Install/copy database " + filename + " first."if ISBEGSEQ()

BREAK // BREAK w/o objectelse

QUITendif

ENDIFUSE (filename) SHARE // BREAK may causeRETURN NIL // in my_err()

FUNCTION my_err (myErrObj) /* executed by the--------------- error handler */IF myErrObj:OSCODE == 32 // SHARE errormyErrObj:CARGO := "Database " + ;

myErrObj:FILENAME + ;" opened by other user"

myErrObj:CANRETRY := .T.ENDIFBREAK myErrObj // pass it to RECOVERRETURN NIL

CMD 120


Compatibility:Unlike C5, FlagShip also supports the branching out of a FOR or WHILE loop.

Related:ISBEGSEQ(), RETURN, ERRORBLOCK(), (OBJ) Error objects

CMD 121

CALLSyntax:

CALL <name> [WITH <paramList>]Purpose:

Execute an external or inline C function.

Arguments:<name> is the true name of the external or inline C (void) function. The default"_bb_" prefix of FlagShip UDFs is not added to the function name by the compiler.Neither will upper/lower conversion be done or the name captured.

Options:WITH <paramList>: up to 8 parameters passed by reference into the C function.The parameters are comma separated FlagShip variables, constants, fields, arrayelements or expressions. They are passed as pointers to regular C variable types:

"N" type as: double *doubleCvar ptr to (IEEE) double"D" type as: long *longCvar ptr to julian days"L" type as: unsigned char *chrCvar ptr to T or F char"C" type as: unsigned char *chrCvar ptr to \0 termin.string"S" type as: WINDOW *windCvar ptr to window struct.

When attempting to pass a constant or expression, a pointer to the contents of theresulting temporary variable is passed. The WORD() function converts the FlagShipnumeric value to an (int) value and passes it by value rather than through a pointerto the C function.

Description:CALL executes an independent or an inline C (void) function. The parameters areplaced on the stack using the C parameter passing convention. External C functionsare compiled by cc or by FlagShip.

Warning: different number or types of arguments passed / parameters received,extending the string length and incorrect usage or manipulation of the variablepointer will inevitably result in an application crash; sometimes not in the C functionitself, but later during the regular program execution.

It is safer to use the FlagShip Extend System to execute a C function because ofparameter checking and passing.

CMD 122

Example:#Cinlinevoid My_C_Function (aaCvar, bbCvar, ccCvar, ddCvar, iiCvar)

double *aaCvar; /* ptr to FS var "N" */unsigned char *bbCvar; /* ptr to FS var "L" */unsigned char *ccCvar; /* ptr to FS var "C" */long *ddCvar; /* ptr to FS var "D" */int iiCvar; /* passed by WORD() */

{int my_integer; /* local integer */char my_string[100]; /* local string */

(*aaCvar)--; /* aa = aa - 1 */*bbCvar = 'T'; /* bb = .T. */*(ccCvar +3) = 'X'; /* cc = "my Xtring" */*ddCvar += 2; /* dd = date + 2 */typed_ee = sqrt(typed_ee); /* TYPED FS vars */my_integer = (int) (*aaCvar);my_integer *= 10;strncpy (my_string, ccCvar, 100); my_string[99] = 0;if (strlen(my_string) < 85)

strcat (my_string, " ... added in C");printw ("\nmy_integer=%d iiCvar=%d my_string=%s",

my_integer, iiCvar * 2, my_string);}#endCinline

STATIC_DOUBLE typed_ee := 9.1 // typed FS var

FUNCTION main ()LOCAL aa := 22, bb := .F.PRIVATE cc := "my string"STATIC dd := DATE()CALL My_C_Function WITH aa, bb, cc, dd, WORD(aa)? ; ? aa, bb, cc, dd, typed_ee

// Compile: $ FlagShip test.prg -na -Mmain


Compatibility:Using inline C code or typed variables is not supported by Clipper. LOADing theobject program as used in dBASE is not supported, because the required functionmust already be available when linking. The contents of the logical value pointerdiffers to Clipper: (char) instead of (short int) and is stored as 'F'/'T' instead of 0/1.The (int) value passed by WORD() is usually the same size as (long) on UNIX.

Related:WORD(), (LNG,EXT) Open C System, (PRE) #Cinline

CMD 123

CANCEL / QUITSyntax:

CANCELor:

QUITPurpose:

Terminates program execution, closes all open files, and returns control to UNIX.

Description:CANCEL or QUIT may be used from anywhere in a program to end the programand return to the operating system. The same result is achieved if the RETURNcommand is used at the top level (main module). Pressing the break key ^K twicealso terminates program execution, if the break key was not disabled withSETCANCEL().

Example:IF LASTKEY() = 27 // ESC key pressed?WAIT "Terminate (y/n) ? " TO answer // confirm,IF UPPER(answer) == "Y" // accept Y,y

QUIT // terminateENDIF

ENDIF

Classification:programming (and database)

Translation:__QUIT ()

Related:QUIT, RETURN, FS_SET ("break"), SETCANCEL(), oRdd:Close()

CMD 124

CLASS, INSTANCESyntax 1:

[STATIC] CLASS <ClassName>[INHERIT <SuperClass>][ALIAS <AliasName>]

and optional:INSTANCE <Name> [:= <exp>] [AS <type>]EXPORT [INSTANCE] <Name> ...HIDDEN [INSTANCE] <Name> ...PROTECT [INSTANCE] <Name> ...

Syntax 2:PROTOTYPE [STATIC] CLASS <ClassName>

[INHERIT <SuperClass>]and optional:

INSTANCE <Name> [AS <type>]EXPORT|HIDDEN|PROTECT [INSTANCE] <Name> [AS <type>]

Purpose:Syntax 1 declares a class name and optional its instances to the compiler. Syntax 2specifies an already elsewhere declared class to the compiler, without declaring theclass again.

Arguments:STATIC restricts the visibility of the class and its entities to the file in which it isdeclared. If omitted, the class has application-wide visibility. If a same named globalclass is already available, it will be hidden by the STATIC CLASS. But you cannotuse a globally defined class and same named STATIC class within the same file.This may cause unpredictable results.

PROTOTYPE informs the compiler about the CLASS structure (and it's instances)which is defined elsewhere later in the application. The class entities becomesvisible and their usage will be optimized, although the CLASS declaration was not(yet) specified in the same source file. PROTOTYPEing is required, when a classmodule (or access, assign) declaration is placed before (or in another file than) theclass declaration itself. Refer also to chapter LNG.2.11.1 and the PROTOTYPEstatement.

All instance names of the PROTOTYPEd class have to be declared (in any order,but with the same names) for proper compile-time addressing. Note: the FlagShipcompiler automatically creates the prototyping file named "reposit.fh" (or a file ofyour choice) for you, see chapters FSC.1.4.2 and LNG.2.11.5. For the FlagShipstandard classes, the prototypes are specified in the "stdclass.fh" file, which may be#include'd in your .prg source or in the local copy of the "std.fh" file.

CMD 125

CLASS <ClassName> is the class identifier, in the variable naming convention (10significant characters). The only restriction is, that the resulting string ofLEFT("ClassName"+"NEW",10) may not conflict with the same named function (stdor UDF), or another class, since this name becomes the creator function.

INHERIT <SuperClass> automatically defines all instances (except hiddeninstances) and methods (including access and assign methods) from the<SuperClass> for the current <ClassName>. Hidden instances and all the methodsmay be overloaded by a local entity. Since the structure of the parent class<SuperClass> must be known for the compiler, use PROTOTYPE CLASS andPROTOTYPE METHOD. Note that standard FlagShip naming convention(abbreviation to 10 significant characters) is valid also for the <ClassName> and itis therefore recommendable to use INHERIT myLongClas instead ofmyLongClassName.

ALIAS <AliasName> defines an descriptor which remain unchanged for the currentand all inherited sub-classes. It allows you to specify a global name for a group ofsingle classes, and later check an object by using IsObjProperty(obj,6,"aliasName").For example, the FlagShip's standard classes are usually splitted to a basic classand specialized sub-classes for the corresponding i/o mode. But regardless how theclass is instantiated, the object variable can be tested by using it global alias name.An alternative global descriptor used in many standard classes is the ClassName()method.

Options:INSTANCE <Name> declares instance variables that are visible only in methods ofthe class being defined, and its INHERITed subclasses (except hidden).

EXPORT | HIDDEN | PROTECT [INSTANCE] <Name> additionally protects theinstances and specifies its visibility and accessibility, see the description below.

AS <type> optionally specifies the data type associated with the instance variable.The valid <type>s are all usual and object types according to LOCAL..AS, withexception of the C-like types. If omitted, the instance variables will be polymorphic(an usual, untyped variable) and will have an initial value of NIL.

If the initializer (:= <exp>) is not given, the instance variable will be initialized to NILor the empty <type>, resp. The assignment is ignored, if specified within thePROTOTYPEd class.

Description:After the CLASS declarator statement, any number of optional INSTANCEdeclarations may follow. The instances are entities of the class, and have to bespecified altogether in the same source file. The class declaration ends with anyexecutable statement, another declarator (e.g. ACCESS, ASSIGN, MODULE,FUNCTION, CLASS etc.) or by the end-of-file.

You cannot declare the same class twice in the application, except for the STATICclass, which is then local to the UDF or source file only, similar to a STATICvariable or function.

CMD 126

Prototyping:When the CLASS <name> is declared elsewhere, you can inform the compilerabout its structure, to enable the compile-time optimization (see also chapterLNG.2.11.6). Otherwise, if the class structure, and/or the type of the object variableis unknown to the compiler (when encountering an object entity access), the slowerrun-time addressing is generated; this applies for using the class in the applicationonly.

During the class property declaration (i.e. when creating the access, assign andmethod body), the whole CLASS structure must be known for the compiler.Therefore, if the CLASS statement is not specified in the same file, you have toPROTOTYPE the CLASS and all of its METHODs (see example 1 below). Thesame applies, when you declare a new, inherited CLASS. When the CLASS isspecified in the same file, you have to use prototyping for forward declarations. As arule of thumb: it is always a good programming style to prototype all the used classentities (i.e. all instances and methods). You will so avoid confusions whenmodifying the application later.

When using (the preferred) include file, it is a common mistake to declare "CLASSxyz" instead of "PROTOTYPE CLASS xyz", resulting in compiler or linker error once#including this header file in different sources. Since the "CLASS xyz" is adeclaration (similar to the FUNCTION or PROCEDURE declarator), it hence can bedeclared only once per application; best in a .prg file.

Instances:The difference between the INSTANCE and EXPORT, PROTECT and HIDDENinstances is:

•EXPORT does not protect the instance at all, but makes it visible (accessible andassignable) both for the application, and the class methods. The name cannot beoverloaded by same named ACCESS and/or ASSIGN method.

•INSTANCE is hidden for the application, but visible in the class methods. If thesame named ACCESS and/or ASSIGN method exists, such is invoked instead ofthe instance itself (except within the same named Access/ Assign body).

•PROTECT is very similar to a usual INSTANCE, except that the instance itself isalways invoked in the class method, even if same named ACCESS and/orASSIGN method exists.

•HIDDEN is very similar to the PROTECT instance, except that this instance is notovertaken into inheriting subclasses.

The following table summarizes the instance properties:

Inst.type applic method inherit acc/ass acc/ass prefEXPORT yes yes yes no noINSTANCE no yes yes yes yesPROTECT no yes yes yes noHIDDEN no yes no yes no

CMD 127

where: (applic) is the visibility of the instance to the application; (method) is thevisibility of the instance to the class methods; (inherit) whether the instance isinherited into a subclass; (acc/ass) if an access or assign method of the same namemay be specified; (acc/ass pref) whether the access or assign method of the samename is preferred in the ACCESS, ASSIGN and METHOD body.

Note: Compound send operators are also supported, e.g.self:fillname(cParam):coAutName := cVar

which is resolved from left to right, asoTemp := self:fillname(cParam) ; oTemp:coAutName := cVar

Since the temporarily created object variable (here named as oTemp) is lateevaluated (when the method is not explicitly typed as class name), it requires to un-hide the instance "coAutName" (by EXPORT or ACCESS). Therefore, theequivalent program notationself:fillname(cParam) ; coAutName := cVar

is usually better, since it may be early evaluated and can use any instance type.

Example 1:Defines two classes and theirs entities in two different files. The prototyping in file2is required for the inheritance and used also (together with typing the objectvariables) for the compile- time resolution of the object entity addresses (seeLNG.11.6).

*** file1.prg *******************CLASS authorsINSTANCE name := ""INSTANCE first := "" AS characterPROTECT titleEXPORT issue AS date

* PROTOTYPE ACCESS name CLASS authors // note 1* PROTOTYPE ASSIGN name(cValue) CLASS authors // note 1* PROTOTYPE METHOD init(cName) CLASS authors // note 1* PROTOTYPE METHOD fillname(cInput) CLASS authors // note 1ACCESS name CLASS authorsreturn name

ASSIGN name(cValue) CLASS authorsif valtype(cValue) == "C" .and. !empty(cValue)

name := cValueendifreturn name

METHOD init(cName) CLASS authorsname := if(valtype(cName) == "C", cName, "")issue:= date()return self

*** eof file1 ***

CMD 128

*** file2.prg *******************

PROTOTYPE CLASS authors // note 3INSTANCE nameINSTANCE first AS characterPROTECT titleEXPORT issue AS date

PROTOTYPE ACCESS name CLASS authors // note 2PROTOTYPE ASSIGN name(cValue) CLASS authors // note 2PROTOTYPE METHOD init(cName) CLASS authors // note 2PROTOTYPE METHOD fillname(cInput) CLASS authors // note 2

CLASS coAuthors INHERIT authors // note 3HIDDEN coAutName AS character

* PROTOTYPE METHOD fillSubAuth() CLASS coAuthors // note 1

METHOD fillname(cInput) CLASS authors // note 2cInput := trim(strtran(cInput, ",", " "))if " " $ cInput

name := left(cInput, at(" ", cInput)-1)first:= substr(cInput,at(" ", cInput)+1)

elsename := cInputfirst:= ""

endifreturn name

METHOD fillSubAuth(cAuth, cSubAuth) CLASS coAuthorsself:fillname(cAuth) ; coAutName := cSubAuthreturn NIL

FUNCTION start() // program startLOCAL oAuth AS authors // typed Locals forLOCAL oSub1, oSub2 AS coAuthors // speed-up onlyoAuth := AUTHORS {"Miller"} // instantiate oAuthoSub1 := COAUTHORS {} // instantiate oSub1oSub1:fillSubAuth("Smith", "Maier")* oSub2 := COAUTHORS {} // instantiate new obj, or:* oSub2 := oSub1 // oSub2 points to oSub1 objoSub2:fillName("Johnson") // otherwise, RTE occurs here? oSub1:name, oSub2:name, oSub1:issue? oAuth:name, oAuth:issuequit

*** eof file2 ***

*** Compile: FlagShip file?.prg -na -m -Mstart

Note 1: it is a good programming style to prototype all the used class entities, evenif declared later. Therefore, un-comment it.

Note 2: you have to PROTOTYPE the whole class and all its properties, to be ableadd/define its entities in another source file.

Note 3: the whole "parent" class must be known when inheriting it.

CMD 129

Example 2:The same example, but the class declaration and its methods are specified in thesame file. In the second (user) file, run-time evaluation takes place, since the classstructure and/or object type is unknown at compile time. You may avoid it, andspeed-up the execution by prototyping the CLASSes in file2.prg, e.g. by #include-ing the "reposit.fh" file.

*** file1.prg ***CLASS authorsINSTANCE name := ""INSTANCE ...

ACCESS name CLASS authorsreturn name

ASSIGN name(cValue) CLASS authorsif ...return .T.

METHOD init(cName) CLASS authorsname := ...return self

METHOD fillname(cInput) CLASS authorscInput := ...return NIL

CLASS coauthors INHERIT authorsHIDDEN coAutName AS character

METHOD fillSubAuth(cAuth, cSubAuth) CLASS coAuthorsself:fillname(cAuth)coAutName := cSubAuthreturn NIL

*** eof file1 ***

*** file2.prg ***FUNCTION start()// program start

LOCAL oAuth AS AUTHORSLOCAL oSub1, oSub2oAuth := AUTHORS {"Miller"}oSub1 := COAUTHORS {}...quit

*** eof file2 ***

Example 3:The same application, but the class is declared in an already compiled file 'file1.o',available for the user as a black box (or in an object library). The application(file2.prg) knows the class structure and uses prototyping for the compile-timeaddress resolution.

*** file2.prg ***#include "file1.fh" // includes prototypesFUNCTION start() // program startLOCAL oAuth, oSub1, oSub2oAuth := AUTHORS {"Miller"}oSub1 := COAUTHORS {}...

CMD 130

*** eof file2 ***

*** file1.fh *** (created e.g. from reposit.fh)PROTOTYPE CLASS authorsEXPORT issue AS dateINSTANCE name := "" // assignment is ignoredPROTECT titleINSTANCE first AS character

PROTOTYPE ACCESS name CLASS authorsPROTOTYPE ASSIGN name(cValue) CLASS authorsPROTOTYPE METHOD init(cName) CLASS authorsPROTOTYPE METHOD fillname(cInput) CLASS authorsPROTOTYPE CLASS coauthors INHERIT authorsHIDDEN coAutName AS character

PROTOTYPE METHOD fillSubAuth()CLASS coAuthors*** eof file1.fh ***

*** Compile: FlagShip file2.prg file1.o -na -Mstart

Example 4:For additional examples, see chapter LNG.2.11 and the METHOD declarator.


Compatibility:Not available in Clipper, but compatible to CA/VO. The PROTOTYPE and ALIASclause is available in FlagShip only.

Related:[ACCESS, ASSIGN] METHOD, PROTOTYPE, LOCAL..AS, (OBJ)DBSERVER,LNG.2.11

CMD 131

CLEARSyntax:

CLEARPurpose:

Clears the screen and all active GET fields, homes the cursor.

Description:CLEAR is a full-screen command that erases the screen using the current colorsetting and releases pending GET objects in the currently visible GETLIST array.When the screen is cleared, the cursor is set to the upper left corner (0,0).

When this command is used in a VALID or SET KEY routine while being in READ,the active READ aborts on returning from the UDF.

If you want only to clear the screen without releasing the GETs, use CLEARSCREEN, CLS or @..CLEAR commands instead.

In GUI mode, the widgets are erased by CLS (or by @..CLEAR TO..) as well, seealso LNG.5.3

Example:CLEARUSE authorsLIST Firstname, Lastname

Classification:screen oriented output

Translation:SCROLL() ; SETPOS(0,0)__KILLREAD() ; GetList := {}

Related:@...CLEAR, @...GET, CLEAR GETS, CLEAR SCREEN, CLS, SCROLL()

CMD 132

CLEAR ALLSyntax:

CLEAR ALLPurpose:

Closes all open databases, indices, format files, releases all PUBLIC and PRIVATEmemory variables, clears all GETs and selects working area 1.

Description:CLEAR ALL does not release LOCAL, STATIC or typed variables. This command isa superset of CLOSE DATABASES, CLOSE FORMAT, CLEAR MEMORY, CLEARGETS and SET ALTERNATE TO.

Files associated with working areas can be explicitly closed with one of the variousforms of the CLOSE command. Private and public variables can be released usingthe RELEASE command, although explicitly releasing variables is not generallyrecommended. For more information on the scope and lifetime of variables, refer tothe LNG section.

Classification:database, programming

Translation:CLOSE DATABASES => DBCLOSEALL()CLOSE FORMAT => __SET FORMAT TO;

__SETFORMAT({|| })CLEAR MEMORY => __MCLEAR()CLEAR GETS => __KILLREAD() ; GetList := {}SET ALTERNATE OFF => SET (_SET_ALTERNATE, OFF)SET ALTERNATE TO => SET (_SET_ALTFILE, "" )

Related:CLEAR MEMORY, CLEAR GETS, CLOSE, RELEASE, SET(), oRdd:Close()

CMD 133

CLEAR GETSSyntax:

CLEAR GETSPurpose:

Clears the active set of GETs.

Description:This command explicitly releases all GET objects in the current and visibleGETLIST array and terminates the current READ if executed within a UDF of theVALID clause or if invoked by a SET KEY procedure.

There are three other mechanisms that automatically release GET objects: theCLEAR command, and READ specified without the SAVE clause, and invoking theReadKill(.T.) function. The last will not delete the GetList[] entries when executingReadSave(.T.), so you may re-issue READ without filling the GETs anew.

Note that CLEAR GETS does not clear the GET fields on the screen, but objects inthe GetList buffer. To clear the display, use CLS or CLEAR SCREEN or CLEAR or@ row,col CLEAR TO row,col or READ CLEAR. This is also required, when youwish to overwrite inactive GETs by @..SAY in GUI mode.

Example:LOCAL var1 := 10.5, var2 := "text text "SET COLOR TO "W+/B, GR+/BG"@ 1,2 GET var1 // display with@ 2,2 GET var2 // "GR+/BG" color? "Getlist{} length=", len(Getlist) // 2CLEAR GETS // GETs yet visible? "Getlist{} length=", len(Getlist) // 0wait@ 1,2 CLEAR TO 2,maxcol() // un-display these GETs

Example: Emulate @..GET displayLOCAL var1 := 10.5, var2 := "text text "SET COLOR TO "W+/B, GR+/BG"SETENHANCED@ 1,2 SAY var1 // display with@ 2,2 SAY var2 // "GR+/BG" colorSETSTANDARD


Translation:ReadKill(.T.) ; getlist := {}

Related:@...CLEAR, @...GET, CLEAR, READ, ReadKill(), ENHANCED, STANDARD

CMD 134

CLEAR MEMORYSyntax:

CLEAR MEMORYPurpose:

Clears all PUBLIC and PRIVATE memory variables.

Description:CLEAR MEMORY deletes all public and private variables from the internal memoryvariable table, unlike RELEASE ALL, which assigns NIL to PRIVATEs of theprocedure where issued.

In FlagShip, there is no real need to RELEASE or CLEAR variables since thenumber of variables is not limited. Returning from the UDP or UDF automaticallyreleases all the PRIVATE and autoPRIVATE variables declared or created there.

LOCAL, STATIC and typed variables are not affected by CLEAR MEMORY orRELEASE. See also (LNG) Variable scope and Visibility.

Example:LOCAL locvar := 1PUBLIC pub1, pub2, pub3 := .F.PRIVATE priv1 := 1234, priv2 := 5678STORE "test" TO pub1, pub2priv3 = 9876 && autoPRIVATE

? TYPE("pub1"), TYPE("priv1"), ;TYPE("pub3"), TYPE("priv3") && C N L N

RELEASE ALL? TYPE("pub1"), TYPE("priv1"), ;TYPE("pub3"), TYPE("priv3") && C U L U

CLEAR MEMORY? TYPE("pub1"), TYPE("priv1"), ;TYPE("pub3"), TYPE("priv3") && U U U U

? VALTYPE(locvar) && N


Translation:__MCLEAR()

Related:CLEAR ALL, RELEASE, RELEASE ALL

CMD 135

CLEAR MENUSyntax:

CLEAR MENUPurpose:

Clears all @..PROMPT items without user interaction.

Description:CLEAR MENU deletes all menu items previously created by @..PROMPT and notyet processed by MENU TO. The next @..PROMPT command will then start a newmenu item sequence.

This command does not clear the items/text displayed on the screen, but the menuitems only. It is similar to executing MENU TO, but there is no user interaction withCLEAR MENU.

The Prompt class is used internally for @..PROMPT items and MENU TOprocessing, the object is hold in _oPrompt. See also menuclass.fh. The CLEARMENU command is equivalent to _oPrompt:Clear()

Example:LOCAL _oPrompt, lastCol

@ 1,0 PROMPT "Item 1"@ 1,col()+3 PROMPT "Item 2"@ 1,col()+3 PROMPT "Item 3"lastCol := col()...if myConditionIsMetMENU TO myChoice //perform user selection

elseCLEAR MENU // cancel it@ 1,0 CLEAR TO 1,lastCol // and remove from screenmyChoice := 0 // for later processing...

endif


Translation:_oPrompt:Clear()

Related:@...PROMPT, MENU TO

CMD 136

CLEAR SCREEN / CLSSyntax:

CLEAR SCREENor:

CLSPurpose:

Clears the screen and homes the cursor.

Description:CLEAR SCREEN (or CLS) is a full-screen command that erases the screen usingthe current color setting. It is identical to the @ 0,0 CLEAR or @ 0,0 CLEAR TOMAXROW(),MAXCOL() command. When the screen is cleared, the cursor is set toupper left corner (0,0).

As opposed to CLEAR, the current GETs are not cleared/deleted by CLEARSCREEN or CLS.

In Terminal i/o mode, the screen background corresponds to the standard colorpair, set by SetColor() or SET COLOR TO command.

In GUI mode, the background color (assigned by SET COLOR) is set only whenSET GUICOLOR is ON (default is OFF - according to GUI design specs). You mayset the background also explicitly by invoking SetColorBackground(cColor) followedby CLS, CLEAR SCREEN, Scroll() or @ ... CLEAR [TO..]

Example:CLEAR SCREENUSE authorsLIST Firstname, Lastname, TitleWAITCLS

Example:SET GUICOLOR ON // use colors also in GUI mode (default is OFF)SET COLOR TO "W+/B,R+/GR,,,B/W"CLS? "hello world" // white text on blue backgroundwait


Compatibility:Unlike DOS, the size of the screen and the color capability is not fixed in UNIX, butdepends on the terminal emulation chosen (environment variable TERM) and theterminal description in the terminfo file. Where possible, use one of the extendedterminal descriptions FSxxx. See (REL) Predefined Terminals and LNG.2.1.

CMD 137

Translation:SCROLL() ; SETPOS(0,0)

Related:@...CLEAR, @...CLEAR TO, CLEAR, COL(), ROW(), MAXCOL(), MAXROW(),SET GUICOLOR, SetColorBackgr()

CMD 138

CLEAR TYPEAHEADSyntax:

CLEAR TYPEAHEADPurpose:

Clears the keyboard buffer.

Description:CLEAR TYPEAHEAD is used to make sure that no keystrokes remain pending inthe FlagShip buffer. This could happen if the user typed several keystrokes inadvance, which were then stored in an internal type-ahead buffer, see LNG.5.2.1.

This command is often used prior to executing a @..GET/READ,@..PROMPT/MENU, DBEDIT(), ACHOICE() etc. or before setting up keyboardtrapping using SET KEY TO, to avoid side effects from characters pending in thebuffer.

Commands KEYBORD and SET TYPEAHEAD also clear the type-ahead buffer.

Note: some Clipper versions clears (undocumented-wise) the LastKey buffer byCLEAR TYPEAHEAD, some do not. If you wish to clear the LastKey buffer inFlagShip, use LastKey([pos],,.T.).

Example:@...PROMPT...? NEXTKEY() && 27CLEAR TYPEAHEAD? NEXTKEY() && 0MENU TO choice


Translation:__KEYBOARD ()

Related:KEYBOARD, SET TYPEAHEAD, NEXTKEY(), INKEY(). LASTKEY()

CMD 139

CLOSESyntax:

CLOSE [<Alias> | ALL | ALTERNATE | DATABASES |FORMAT | INDEXES]

Purpose:Closes all files of the specified type.

Arguments:CLOSE with no argument closes the current database file and its indices, producingthe same effect as USE without an argument.

Options:<Alias> does the same as CLOSE, but with a specified working area where thefiles given are closed rather than the default current working area.

ALL: Closes the database and index files in all working areas, as well as the formatand alternate files, and releases active filters and relations.

ALTERNATE: Closes the currently open alternate file, with the same effect as SETALTERNATE TO.

DATABASES: Closes database and index files in all working areas and releasesactive filters and relations.

FORMAT: Closes the active format file, with the same effect as SET FORMAT TO.

INDEXES: Closes all open indices in the current working area.

Description:There are other commands besides CLOSE, which also close files. These are:QUIT/CANCEL, RETURN from the main procedure, CLEAR ALL and USE withoutan argument.

The "fatal error" runtime error or user termination via ^K also closes all files byusing QUIT before exiting a program.

Multiuser:If a record or the whole file is locked by RLOCK() or FLOCK(), all the locks areautomatically removed when the database file is closed.

CMD 140

Example:DO WHILE .T.CLOSE DATABASESchoice = my_menu ()DO CASECASE choice = 1

CLOSE ALLUSE personalDO pers_proc

CASE choice = 2USE stock NEWDO stock_proc

ENDCASEENDDOQUIT

Classification:programming, database

Compatibility:The option <Alias> is new in FS4.

Translation:CLOSE => DBCLOSEAREA()CLOSE ALIAS => <alias>->(DBCLOSEAREA() )CLOSE ALL => CLOSE DATA ; SELE 1; CLOSE FORMATCLOSE ALTERNATE => SET(_SET_ALTFILE, "")CLOSE DATABASES => DBCLOSEALL()CLOSE FORMAT => __SETFORMAT(NIL)CLEAR INDEX => DBCLEARINDEX()

Related:CLEAR ALL, QUIT, RETURN, SET ALTERNATE TO, SET FORMAT TO, USE,SETCANCEL(), FS_SET("break"), oRdd:Close()

CMD 141

COMMITSyntax:

COMMIT [ALL]Purpose:

Writes the internal UNIX (or Windows) buffers of all used working areas to the harddisk.

Options:COMMIT ALL will commit both SHARED and EXCLUSIVE open databases. If ALLis not given, only SHARED open databases are committed. You may set the globalswitch

_aGlobSetting[GSET_L_DBCOMMIT_EXCL] := .T. // default is .F.whereby COMMIT behaves then same as COMMIT ALL

Description:FlagShip stores the current .dbf record in internal working area buffers. These getflushed to the UNIX (or Windows) buffer upon:

•any record movement (GOTO, SKIP, SEEK etc.) SHARED•SKIP 0 SHARED•SELECT SHARED•CLOSE / USE SHARED/EXCL•QUIT, user abort (Ctrl-K) SHARED/EXCL•COMMIT or DbCommit() or DbCommitAll() SHARED(EXCL)•COMMIT ALL or DbCommit(.T.) or DbCommitAll(.T.) SHARED/EXCL

When executing any of the above commands, the current database changesbecome visible to other users in a multi-user/multitasking environment.

COMMIT, however, updates the internal buffers for all working areas as well as theUNIX (or Windows) file buffers, writing them physically to the hard disk (very similarto the system command "sync") and reads them back again into the internal buffers.Note that the executable waits until the disc access is performed successfully.

Setting the _aGlobSetting[GSET_L_DBCOMMIT_EXCL] := .T. will flush alsoEXCLUSIVE open databases, hence COMMIT behaves like COMMIT ALL orDbCommitAll(.T.). This setting however does not affect flushing on record move-ments or in SELECT, which is done for SHARED open dbf only.

COMMIT is equivalent to DbCommitAll() function, COMMIT ALL is same asDbCommitAll(.T.). To commit only current database, use DbCommit() function.

CMD 142

Multiuser:Use this command to make sure that the data is immediately physically written tothe disc. The USE and CLOSE commands and the database movement implicit theDBCOMMIT() which flushes the changes of the current database to the disc.Executing this COMMIT command or DbCommit*() functions will make thedatabase and index changes available to other users. See also LNG.4.8.5.

You may also use COMMIT prior to outputting the database record (if not SKIPpedbefore) to make sure the current data (which had been probably changed in themeantime by another user) will be read from the file and not from the internal bufferonly.

COMMIT should be executed before you free the by Flock() or Rlock() lockedrecords or database, especially on heavy loaded database. If SET AUTOLOCK isON (the default), COMMIT is executed automatically in AutoUnlock(), see also<FlagShip_dir>/system/autolock.prg.

Tuning:You may configure COMMIT, or execute it also at the time of UNLOCK, see Tuningin FUN.DbCommitAll()

Example:USE stock SHARED // check by USED()SET INDEX TO stockno // check by NETERR()SEEK 12345 // check by FOUND()WHILE !FLOCK() // wait for file-lockSleepMs(50) // with small delay to

ENDDO // avoid heavy CPU loadDO WHILE !EOF() .AND. stock_no = 12345REPLACE sold_out WITH .T., act_item WITH 0SKIP

ENDDOCOMMIT // update all buffersUNLOCK // release file-lock

Example:Display data, check the actuality every 5 seconds and redisplay new data, ifchanges detected:

LOCAL changed = .T., key, act_itemsFIELD stock_no, text, item_availUSE stock SHARED // check by USED()SET INDEX TO stockno // check by NETERR()SEEK 12345 // check by FOUND()

WHILE .T.IF changed // avoid permanent display

@ 1,0 say stock_no@ 2,0 say text@ 3,0 say item_availact_items = item_availchanged = .F.

ENDIFkey = INKEY(5) // wait 5 sec or user key

CMD 143

IF key # 0EXIT // exit the loopENDIFCOMMIT // or: SKIP 0IF act_items # item_avail // data changed,

?? chr(7) // sound bellchanged = .T.

ENDIFENDDOIF key = 27 ... // process pressed key


Compatibility:The following commands produce the same effect as COMMIT:

SKIP 0or

act_rec := RECNO() ; GOTO act_rec

Translation:DBCOMMITALL()

Related:GOTO, SKIP, REPLACE, UNLOCK, DBCOMMIT(), DBCOMMITALL(),oRdd:Commit()

CMD 144

CONTINUESyntax:

CONTINUEPurpose:

Continues the pending LOCATE search in the current working area.

Description:The search is continued from the current record. It terminates when the first recordwhich meets the most recent LOCATE condition, is found, or, the end of LOCATEscope is reached.

If the search was successful, the matching record becomes the current record, andFOUND() returns .T. Else, FOUND() returns .F., and the record pointer is positionedon EOF or the next record outside the FOR scope.

Each working area may have an active LOCATE condition which remains pendinguntil a new condition is issued or a new database file is used in that area. No otheractions release the LOCATE condition.

The <scope> and WHILE conditions of the initial LOCATE are ignored; only theFOR condition is used with CONTINUE. If you are using a LOCATE with a WHILEcondition and want to continue the search for a matching record, use SKIP and thenrepeat the original LOCATE statement adding REST as the scope.

Example:USE employee? RECCOUNT() && 100LOCATE FOR Salary > 50000? FOUND(), EOF(), RECNO() && .T. .F. 21CONTINUE? FOUND(), EOF(), RECNO() && .T. .F. 53CONTINUE? FOUND(), EOF(), RECNO() && .F. .T. 101


Translation:__DBCONTINUE()

Related:LOCATE, FOUND(), oRdd:Continue(), oRdd:GetLocate()

CMD 145

CONSTANTSyntax:

CONSTANT <memvar> := <exp>Purpose:

Creates and initializes the specified memory variable similar to PUBLIC but not re-assignable. If you wish to declare re-assignable public variable, use PROTECTPUBLIC instead.

Arguments:<memvar> is the variable to be created as fix PUBLIC. The name may be of anylength, but only the first 10 characters are significant (see more LNG.2.6). Variablenames in the FlagShip language are not case sensitive.

Initializing:<exp> is any valid FlagShip expression including a literal (constant) array toinitialize the variable. Since the CONSTANT is not re-assignable, the initializer mustbe specified at the time of declaration.

Scope, Visibility:CONSTANT variables have the same scope and visibility as the PUBLIC variables,i.e. are available (after the declaration) for the whole life-time of the application.



Related:PUBLIC, MEMVAR

CMD 146

COPY FILE ... TOSyntax:

COPY FILE <file1>|(<expC1>)TO <file2>|(<expC2>)

[ADDITIVE]Purpose:

Duplicates a file regardless of its type.

Arguments:<file1> is the name of the source file, including extension, according to UNIXconventions; DOS filenames are also supported. Standard UNIX wildcards areallowed.

<file2> is the name of the target file, including extension, according to UNIXconventions. Standard UNIX and Windows wildcards (or a path only, but not theperiod . alone) are allowed.

Option:ADDITIVE appends the contents of <file2> to <file1>. <file2> must be explicitlyspecified. If a wildcard is given in <file1>, all files found are copied to <file2>. Whenthe ADDITIVE option is omitted, <file2> is overwritten.

Description:COPY FILE copies files located in the SET DEFAULT TO path if set, or the currentdirectory, unless a path is specified. The success or error may be checked usingDOSERROR(). Both <file1> and <file2> (if such exists) must be closed before beingcopied. The file's permission of <file2> is set according to umask.

Example:FS_SET ("lower", .T.) && automat. translationCOPY FILE TestFile.tmp TO test.dummy? DOSERROR(), FILE("test.dummy") && 0 .T.COPY FILE [a-d]*x.p?g /usr/smith/allfiles.prg ADDITIVETYPE /usr/smith/allfiles.prgCOPY FILE [a-d]*x.p?g /usr/smith && directory

Classification:system, file access

Compatibility:The COPY FILE command is equivalent to the UNIX command "cp file1 file2" or"cat file1 >> file2" respectively, if the ADDITIVE option is used. The ADDITIVEclause, wildcard support and DOSERROR() checking is available in FlagShip only.

Translation:__COPYFILE ( "file1", "file2", .add.)

Related:RENAME, COPY TO, SET DEFAULT, RUN, UNIX: cp, cat

CMD 147

COPY TOSyntax:

COPY TO [<file>|(<expC1>)][<scope>][FIELDS <fieldList>][FOR <condition>][WHILE <condition>][SDF | DELIMITED

[WITH BLANK|<delimiter>|(<expC2>)][FLDSEP (<expC4>)][CHARSEP (<expC5>)][LINESEP (<expC6>)][WITHMEMO [<expN7>]] ]

[VIA <expC3>]Purpose:

Copies specified parts or the whole current database to a new file.

Arguments:TO <file>|(<expC1>) is the name of the new file. If an extension is not specified, itis assumed to be .dbf when no type clause is given, or .txt otherwise. The <file>name may be omitted, with the SDF or DELIMITED clause, when an SET EXTRAfile already opened is to be used ADDITIVEly.

Options:FIELDS: Specifies the list of fields to copy to the target file. The default is all fields.In text files the fields will appear in the order given by the FIELDS clause, ifspecified.

<scope> is the part of the current database file to COPY. The default scope is ALL.

<condition> specifies additional FOR and/or WHILE filtering of the copied recordswithin the given <scope>. See the general command description.

SDF: Specifies the output data type to be a System Data Format ASCII file.Records are of a fixed length, separated by a line feed, without a field separator.Character fields are padded with trailing blanks, numeric fields are padded withleading blanks, date fields are written in the form "yyyymmdd", and logical fields arewritten in the form T/F.

SDF: file formatField separator None or <expC4>Record separator LF or CR/LF = 0Ahex or <expC6>End of file marker file-end or the DOS eof = 1AhexCharacter fields Delimited by <expC5>...<expC5>, padded with trailing blanksNumeric fields Padded with leading blanks for zerosDate fields YYYYMMDDLogical fields T or FMemo fields Ignored without WITHMEMO <expN7> clause

CMD 148

DELIMITED identifies an ASCII text file, where fields are separated by commas andcharacter fields are bounded by double quotation marks, which are also the defaultdelimiters. Fields and records are of variable length and end with a line feed.Leading and trailing spaces for numeric and character fields are truncated, datefields are written in the "yyyymmdd" form, and logical fields are written as T/F.

DELIMITED [WITH delimiter]: file formatField separator Comma (,) or <expC4>Record separator LF or CR/LF = 0Ahex or 0D+0AhexEnd of file marker None, file-endCharacter fields Delimited by quotas ("...") or by <expC2>

or by <expC5>, trailing blanks truncatedNumeric fields Leading zeros truncatedDate fields YYYYMMDDLogical fields T or FMemo fields Ignored without WITHMEMO clause

DELIMITED WITH <delimiter>|(<expC2>) identifies a delimited ASCII text file,where character fields are delimited with the specified delimiter. Note: this clause, ifgiven, must be the last one within the command. To avoid misinterpretation, it isbetter to enclose the delimiter in quotes. DELIMITED WITH '"' is the same as theclause DELIMITED only. This clause can be overwritten by FLDSEP clause.

DELIMITED WITH BLANK identifies an ASCII text file, where fields are separatedby one space and character fields are not bounded by delimiters (except whenFLDSEP and/or CHARSEP is specified).

DELIMITED WITH BLANK: file formatField separator Single blank space or <expC4>Record separator LF or CR/LF = 0Ahex or 0D+0AhexEnd of file marker None, file-endCharacter fields Not delimited (or delimited by <expC5>),

trailing blanks are truncatedNumeric fields Leading zeros truncatedDate fields YYYYMMDDLogical fields T or FMemo fields Ignored without WITHMEMO clause

FLDSEP <expC4> is optional field separator. If given, overrides the comma orspace field separator of DELIMITED WITH, or is added into SDF output.

CHARSEP <expC5> is optional separator/delimiter of character fields. If given,overrides the quota (") or <delimiter> of DELIMITED WITH, or is added in SDFoutput. If you wish different left and right delimiters, pass an array of two elements,where the first is left, and second is the right delimiter character/string.

LINESEP <expC6> is optional record separator. If given, overrides the default LF =chr(10) or CR+LF = chr(13,10) separator specified in _aGlobSetting[GSET_C_COPY_TO_NEWLINE]. You may assign any other separator either globally by

CMD 149

assigning value to this _aGlobSetting element, or temporary by this LINESEPclause.

WITHMEMO [<expN7>] includes also memo and variable length fields in theDELIMITED or SDF output. The field is TRIM()ed, soft-CR are replaced by space,and hard-CR by chr(20). You may re-define these replace characters by your own,see "Tuning" below. For DELIMITED output, the memo field is delimited same ascharacter field by quotas or by <expC5> and the <expN7> value is ignored. ForSDF output, the string is padded by space or trimmed to total <expN7> length. If<expN7> is not given for SDF or is less than or equal 0, memo field is notprocessed.

VIA <expC3> specifies the name of the RDD (replaceable database driver) to useto export the desired data, given as quoted string or character variable. The defaultFlagShip driver is "DBFIDX".

Description:All records from the current database file are copied, unless limited by: scope, FORor WHILE conditions, filter, or SET DELETED ON. Records are copied in controllingindex order if such is set, otherwise in natural order. The file's permission of <file> isset according to the current database.

Since the DELIMITED [WITH] clause is ambiguous in dBase specification (it definesfield separator or character delimiter), FlagShip allows you to specify explicitly thefield separator by FLDSEP and the character delimiter by CHARSEP clauses, forboth DELIMITED and SDF output format.

Multiuser:If the output file is a database (i.e. neither SDF nor DELIMITED clause is used), itwill be created and opened in EXCLUSIVE mode, and then closed again. If thetarget database or file exists, it will be deleted without notice before COPYing.

To avoid inconsistent target data when the source database is open in SHAREDmode and SET AUTOLOCK is ON, the database may be automatically FLOCK()edduring the COPY TO operation, see Tuning below. Otherwise, you should lock itprogrammatically by FLOCK() before COPY TO... (and UNLOCK thereafter), so itcannot be changed by others during the COPY process.

Tuning:When SET AUTOLOCK is ON (the default), you may force the FLOCK() andUNLOCK automatically by assigning

_aGlobSetting[GSET_L_DBCOPY_LOCK] := .T. // default is .F.The replace characters for memo field can be re-defined by

_aGlobSetting[GSET_A_COPYDELIM_MEMO] := {" ", chr(20) } // def

CMD 150

Example:Prepare a mail-merging list

USE employee SHAREDlocal iCount := 0while ! FLOCK() // on lock failure, retryif ++iCount > 20 // with msg every 2 seconds

InfoBox("waiting for lock employee.dbf")iCount := 0

endifsleepms(100) // wait 0.1 seconds

enddoCOPY TO address FIELDS Name, Lastname, Address SDFUNLOCK

Classification:database and export to ASCII file

Compatibility:The new file will be created with the current access rights of the database. Theoutput text file is created using the UNIX (or Windows) convention. To translate it tothe DOS format (CR/LF), use the "unix2dos" utility. Omitting the <file> argument ispossible in FlagShip only. The FLDSEP, CHARSEP and WITHMEMO clauses areavailable in FlagShip only.

Translation:__DBCOPY ("file", {"field1" [,"field2.."]}, ;

{forCond}>, {whileCond}, [next], [record], [.rest.] )__DBCOPYSDF ("file", {"field1" [,"field2.."]}, ;

{forCond}>, {whileCond}, [next], [record], [.rest.] )__DBCOPYDELIM ("file", "delim", {"field1" [,"field2.."]}, ;

{forCond}>, {whileCond}, [next], [record], [.rest.] )

Related:APPEND FROM, COPY FILE, COPY STRUCTURE, SET DELETED,oRdd:CopyDB(), oRdd:CopySDF(), oRdd:CopyDelimited()

CMD 151

COPY STRUCTURE TOSyntax:

COPY STRUCTURE TO <file>|(<expC>)[FIELDS <fieldList>]

Purpose:Creates an empty database file with field definitions from the current database file.

Arguments:<file>|(<expC>) is the name of the file to be created. The default extension is .dbfunless another extension is explicitly specified.

Options:FIELDS <fieldList> is the set of fields to copy to the new database file in the orderspecified. The default is all fields.

Example:USE employeexx = "new_part"? FCOUNT(), RECCOUNT() && 12 100COPY STRUCTURE TO new_empCOPY STRUCTURE TO (xx) FIELDS name,city,zipUSE new_emp? FCOUNT(), RECCOUNT() && 12 0USE (xx)? FCOUNT(), LASTREC() && 3 0


Translation:__DBCOPYSTRUCT ("file", {"field1" [, "field2"...]} )

Related:COPY STRUCT EXTENDED, CREATE, CREATE FROM, DBCREATE(),oRdd:CopyStructure()

CMD 152

COPY TO...STRUCT EXTENDEDSyntax:

COPY TO <file>|(<expC>) STRUCTURE EXTENDEDPurpose:

Creates a structure extended database file containing the field definitions of thecurrent database.

Arguments:TO <file>|(<expC>) is the name of the structure extended database file.

Description:COPY STRUCTURE EXTENDED creates a database file with four fields:FIELD_NAME, FIELD_TYPE, FIELD_LEN and FIELD_DEC, and fills it with fielddefinitions of the current database file. Thereby, it is possible to create and modifystructures of database files from within an application. CREATE FROM is used tocreate a new database file from a structure extended file. To create only an emptystructure extended file, use the CREATE command.

Field name Type Length, deci1 FIELD_NAME Character 102 FIELD_TYPE Character 13 FIELD_LEN Numeric 3 0 see note4 FIELD_DEC Numeric 3 0

Note: character fields up to 64 Kbytes are supported by FlagShip. Fields greaterthan 255 characters are defined with a combination of the FIELD_DEC andFIELD_LEN fields to remain compatible with other xBASE dialects. After copyingSTRUCTURE EXTENDED, you can use the following formula to determine thelength of any character field:

act_len = IF (FIELD_TYPE = "C" .AND. FIELD_DEC != 0, ;(FIELD_DEC * 256) + FIELD_LEN, FIELD_LEN)

The structure database may be extended with additional fields for the user's ownpurposes.

CMD 153

Example:USE Employeexx = "new_part"? FCOUNT(), RECCOUNT() && 12 100COPY STRUCTURE EXTENDED TO New_struCOPY STRUCTURE EXTENDED TO (xx) FIELDS name,city,zip, noteUSE New_stru? FCOUNT(), RECCOUNT() && 4 12

USE (xx) NEW? FCOUNT(), LASTREC() && 4 3LOCATE FOR UPPER(TRIM(field_name)) == "NOTE"IF FOUND()

REPLACE field_dec WITH 4, ; // 4 * 256 = 1024field_len WITH 76 // + 76 = 1100

ENDIFCLOSECREATE new_name FROM (xx)USE new_name? LEN(note) // 1100


Translation:__DBCOPYXSTRUCT ("file")

Related:CREATE, CREATE FROM, FIELD(), TYPE(), DBCREATE()

CMD 154

COUNT ... TOSyntax:

COUNT [<scope>][FOR <condition>] [WHILE <condition>]TO <memvar>

Purpose:Counts records in the current working area, which fall into the given scope and fulfillthe specified conditions. The result is stored to the specified memory variable.

Arguments:<memvar> is the memory variable where the result of counting is stored. If thevariable does not exist, a new autoPRIVATE is created as numeric.

Options:<scope> is the part of the current database file to be counted. The default scope isALL.

<condition>: The FOR clause specifies that the set of records meeting thecondition within the given scope, are to be counted. The WHILE clause stopscounting when the first record not fulfilling the condition is reached.

Example:USE magazine? RECCOUNT() && 100COUNT FOR Price > 2 TO Exp && 12COUNT FOR Price <= 2 TO Cheap && 88


Translation:<var> := 0DBEVAL({|| <var> := <var> + 1}, ;

{forCond}>, {whileCond}, [next], [record], [.rest.])

Related:AVERAGE, SUM, TOTAL, DBEVAL(), oRdd:Count()

CMD 155

CREATESyntax:

CREATE <file>|(<expC>)[ALIAS <alias>][NEW][VIA <driver>]

Purpose:Creates an empty structure extended database file, and leaves it open in theselected working area.

Arguments:<file>|(<expC>) is the name of the empty structure extended file.

Options:ALIAS <alias> is the name to be associated with the working area. If not specified,the main part of the <file> name is assigned to <alias>.

NEW selects an unused working area making it the current one and opens thedatabase <file> there. The clause is equivalent to SELECT 0 prior to the CREATE...command. If this clause is not given, the database is opened in the currentSELECTed working area.

VIA <driver> defines the replaceable database driver (RDD) to process the currentworking area. The default driver is "DBFIDX".

Description:The empty structure extended file consists of four fields: FIELD_NAME,FIELD_TYPE, FIELD_LEN and FIELD_DEC, see CREATE FROM. To form a newdatabase file, use CREATE FROM.

Field name Type Length deci1 FIELD_NAME Character 102 FIELD_TYPE Character 13 FIELD_LEN Numeric 3 04 FIELD_DEC Numeric 3 0

Example:see example of CREATE FROM... and DBCREATE()


Translation:__DBCREATE ("file")

Related:DBCREATE(), CREATE FROM, COPY STRUCTURE EXTENDED

CMD 156

CREATE ... FROMSyntax:

CREATE <file1> | (<expC1>) FROM <file2> | (<expC2>)[ALIAS <alias>][NEW][VIA <driver>]

Purpose:Creates a new database file from a structure extended file, and leaves it open in theselected working area.

Arguments:<file1>|(<expC1>) is the name of the new database file to be created.

<file2>|(<expC2>) is the name of a structure extended file, from which the fielddefinitions for <file1> will be used during the creation process.

Options:ALIAS <alias> is the name to be associated with the working area. If not specified,the main part of the <file> name is assigned to <alias>.

NEW selects an unused working area making it the current one and opens thedatabase <file> there. The clause is equivalent to SELECT 0 prior to the CREATE...command. If this clause is not given, the database is opened in the currentSELECTed working area.

VIA <driver> defines the replaceable database driver (RDD) to process the currentworking area. The default driver is "DBFIDX".

Description:CREATE FROM creates a new database file according to the information containedin a structure extended file. A database file is regarded as a structure extended file,if it contains the following four fields:

Field name Type Length deci1 FIELD_NAME Character 102 FIELD_TYPE Character 13 FIELD_LEN Numeric 3 04 FIELD_DEC Numeric 3 0

A structure extended file can contain any number of fields, providing that these fourfields exist. The order in which the fields appear is of no importance. Only the fourfields are used when creating a new dbf file.

To create a character field longer than 256 characters, specify the FIELD_DECequal to the INT() of the required length divided by 256, and the FIELD_LEN equalto the remainder of the length divided by 256. The formula is

CMD 157

act_len = IF (FIELD_TYPE = "C" .AND. FIELD_DEC != 0, ;(FIELD_DEC * 256) + FIELD_LEN, FIELD_LEN)

The file's permission of <file2> is set for <file1>.

Note, that the function DBCREATE() performs the same functionality, but is easierto handle.

Example 1:CREATE New_struUSE New_struAPPEND BLANKREPLACE Field_name WITH "Id", ;

Field_type WITH "N",;Field_len WITH 5, ;Field_dec WITH 0

APPEND BLANKREPLACE Field_name WITH "Lastname", ;

Field_type WITH "C", ;Field_len WITH 20, ;Field_dec WITH 0

APPEND BLANKREPLACE Field_name WITH "Birthdate", ;

Field_type WITH "D", ;Field_len WITH 8, ;Field_dec WITH 0

APPEND BLANKREPLACE Field_name WITH "Longfield", ;

Field_type WITH "C", ;Field_len WITH 160, ; // 4000 % 256Field_dec WITH 15 // int(4000/256)

USECREATE New_file FROM New_stru

** use the new database

USE New_file? FCOUNT(), FIELD(1), RECCOUNT() // 4 ID 0? LEN(longfield) // 4000

Example 2:This example is equivalent to Example 1:

aDbStru := {{"Id", "N", 5, 0}, ;{"Lastname","C",20,0}, ;{"Birthdate","D",8,0}, ;{"Longfield","C", 4000, 0}}

DbCreate ("New_file", aDbStru)

CMD 158


CompatibilityFlagShip supports character field length up to 64534 bytes (FIELD_DEC = 252,FILED_LEN = 85), Clipper up to 32 or 64 Kbytes (release dependent), dBASE III upto 256 Bytes. To remain compatible to DOS, the maximal record length (the sum offield lengths) is in all cases 64534 Bytes.

Translation:__DBCREATE ("file1", "file2")

Related:DBCREATE(), COPY STRUCTURE EXTENDED, CREATE, oRdd:CreateDB()

CMD 159

DECLARESyntax:

DECLARE <array> [<dim>]DECLARE <array> [<dim1>,<dim2>,<dimn>]DECLARE <array> [<dim1>][<dim2>][<dimn>]DECLARE <array> := {<initializer>}

Purpose:Creates the specified one-dimensional or multi-dimensional array(s) of class typePRIVATE.

Arguments:In this case, the square brackets around <dim> do not specify an optionalargument, but are a required part of the syntax.

<array> is the name of the array to be created.

<dim> is the dimension of the array. With one-dimensional arrays, its syntax is[<expN>]. With multi-dimensional arrays, the dimensions may be given together inthe [ ] bracket separated by commas or each dimension separately in [ ] bracketswithout commas. You may declare more than one array in one DECLAREstatement.

Array elements can be handled like ordinary memory variables. Different elementsof the same array can have different types. Each element may contain another sub-array (non-symmetric structure), see LNG.2.6.4.

Initializing:Array elements can be declared and initialized with a starting value using an array(literal) constant (see LNG.2.7) which includes any valid expression, and the assign:= operator, e.g.:

DECLARE arr1 := {} // creates arr1[0]DECLARE arr2 := {0,date(),"test",.T.} // creates arr2[4]DECLARE arr3 := {{1,2},{3,4}} // creates arr3[2,2]DECLARE arr4:= {1, {2,3}, {"test",.T.,NIL,4, {5,DATE()}},6}

The above arrays arr1, arr2 and arr3 are symmetric, while the declaration of array4specifies a non-symmetric array. If no explicit <initializer> is specified, the variableis given an initial value of NIL. The exception is the zero length literal array { }.

Description:DECLARE creates private arrays. This hides all the private arrays or variables withthe same name created in higher level procedures. Declaring an array LOCAL,STATIC or PUBLIC is another way of specifying the visibility scope. DECLARE andPRIVATE are equivalent statements.

FlagShip uses one variable slot per array. The maximum number of array elementsis 65535 per dimension, up to 65535 dimensions will be handled. The theoretical

CMD 160

size of a symmetric array is therefore 4 billion (* 28 bytes), if non-symmetric, evenmore.

Arrays can be declared or used from within macro variables, see LNG.2.10. Asparameters to functions and procedures, arrays are passed by reference, whilearray elements are passed by the usual (variable) convention. See PROCEDUREand FUNCTION.

Example:name = "arr1"len = 20DECLARE &name.[len] && arr1[20]DECLARE arr2[15], arr3[5,6]AFILL(arr1, "John")

? &name.[5] && "John"? LEN(arr1), arr3[5,2] && 20 NIL? TYPE("name"), TYPE(name) && "arr1" "A"? TYPE("arr1"), TYPE("arr1[1]") && "A" "C"

DECLARE uarr:= {1, {2,3}, {"test",.T.,NIL,4, {5,DATE()}},6}? VALTYPE(uarr), LEN(uarr) // A 4? VALTYPE(uarr[2]), LEN(uarr[2]) // A 2? VALTYPE(uarr[3,5]), LEN(uarr[3,5]) // A 2? uarr[1], uarr[3][4], uarr[3,5,1] // 1 4 5


Compatibility:Multi-dimensional and non-symmetric arrays are new in FS4 and C5. Clipper allowsarrays with a maximum of 4096 elements, dBASE IV two-dimensional arrays with amaximum of 1170 elements. Unlike Clipper, FlagShip supports saving and restoringarrays to .mem files, see SAVE TO.

Related:PRIVATE, PUBLIC, LOCAL, STATIC, AADD(), ARRAY(), ACOPY(), ACLONE(),ADEL(), ACHOICE(), ADIR(), AFILL(), AINS(), ASCAN(), ASORT(), DBEDIT()

CMD 161

DELETESyntax:

DELETE [<scope>][FOR <condition>][WHILE <condition>]

Purpose:Marks records in the current working area for deleting.

Options:<scope> is the part of the current database file to be deleted. The default scope isthe current record if a condition is not specified, or ALL if a condition is specified.

<condition>: The FOR clause specifies that the set of records meeting thecondition within the given scope is to be deleted. The WHILE clause stops deletionwhen the first record not fulfilling the condition is reached.

Description:After deletion, the records remain in the database until removed by PACK orreinstated by RECALL. They may be queried with DELETED(), and filtered out withSET DELETED ON. Removing all records from a database file is done more easilywith ZAP than with DELETE ALL and PACK. If SET DELETED is ON, the recordstays visible until the record pointer is moved.

Multiuser:In a multiuser / multitasking environment, DELETE requires that the records belocked with RLOCK() if deleting a single record, or by FLOCK() or an EXCLUSIVEopen, to delete multiple records. Otherwise, AUTORLOCK() is used automatically, ifSET AUTOLOCK is active. See LNG.4.8.

Example:SET DELETED ONUSE employeeWHILE NETERR() ; USE employee ; END? RECCOUNT() && 100COUNT TO Sick_no FOR Sick_days > 30 && 12WHILE !FLOCK() ; ENDDELETE FOR Sick_days > 30UNLOCKCOUNT TO Healthy_no && 88


Translation:DBDELETE ()DBEVAL ({|| DBDELETE()}, for, while...)

Related:RECALL, DELETED(), SET DELETED, PACK, ZAP, oRdd:Delete()

CMD 162

DELETE FILESyntax:

DELETE FILE <file>|(<expC>)or

ERASE <file>|(<expC>)Purpose:

Removes a file from disk.

Arguments:<file> is the name of the file (including extension) to be deleted. A full path may bespecified. If omitted, only the current directory is searched; the SET PATH or SETDEFAULT path is ignored. Standard UNIX wildcards using ?, *, [..] are supported.

Description:The file will be deleted without any warning. The consequences are notrecoverable. The user must have at least "w" access rights for the file and "x" forthe directory.

The success can be checked using DOSERROR().

Example:? FILE ("data.tmp") && .T.DELETE FILE dat?.t*p? FILE ("data.t*p") && .F.? DOSERROR() && 0


Compatibility:Wildcard support and the DOSERROR() checking is available in FlagShip only.

The ERASE or DELETE FILE command is equivalent to the UNIX command "rm" orsimilar to the DOS command "DEL".

The command considers the automatic path and/or conversion using e.g.FS_SET("pathlower") and FS_SET ("lower"), the extension replacement usingFS_SET ("translext") and the drive substitution using the environment variablex_FSDRIVE.

Translation:FERASE ("file")

Related:CLOSE, USE, CURDIR(), FILE(), FS_SET ()

CMD 163

DELETE TAGSyntax:

DELETE TAG <expC1>[IN|OF <file1>][ , <expC2> [IN|OF <file2>]... ]

Purpose:Deletes a tag (subindex) or the whole index file.

Arguments:<expC1> is a literal string or parenthesized character expression that representsthe subindex (tag) name, within the index file. For the default "DBFIDX" replaceabledriver RDD, the <expC1> is equivalent to <file1>.

IN <file1> (or OF <file1>) is a literal string or parenthesized character expressionthat represents the index file name containing the <expC1> subindex (tag). For thedefault "DBFIDX" replaceable driver RDD, which contains only one subindex (tag),the <file1> entry is ignored. If the <file1> is omitted, all active indices in the currentworking area are searched for the subindex name <expC1>.

Description:This command is designed to delete one tag (subindex) in a multiple index filesupplied by other RDDs. With single index files, like the default "DBFIDX", thewhole index file is deleted, equivalent to the DELETE FILE command.

If the removed <expC1> is the active index, the next tag of the index file is selected.If the removed <expC1> is the last, or the only one subindex (tag) in the index file<file1>, the index is deselected, equivalent to the CLOSE INDEXES command orSET INDEX TO without arguments.

Multiuser:With some RDD drivers, the database must be used exclusively, but is not requiredfor the default "DBFIDX" driver.

Example:USE employee VIA "dbfmdx" NEWSET INDEX TO employeeDELETE TAG persno OF employee

Example:USE employee NEWSET INDEX TO persno, persname? INDEXORD(), pers_num, name // 1 101 SmithDELETE TAG persname? INDEXORD(), pers_num, name // 0 295 Miller? FILE("persname" + INDEXEXT()) // .F.

CMD 164


Compatibility:Available in FS4, C5, DB4. The clause OF is not available in C5, but IN only.

Translation:ORDERDESTROY (exp1, file1)

Related:USE, ORDDESTROY(), DBSETDRIVER(), oRdd:DeleteOrder()

CMD 165

DIRSyntax:

DIR [<skeleton>]Purpose:

Displays a listing of files from the specified path.

Options:<skeleton> is the standard wildcard notation for files (* and ?) used to select filesfor display. It may include a directory path to specify the tree structure from thecurrent (relative path) or the root (absolute path) directory to the desired files. If it isomitted, the current directory is assumed. The directory names can be separated bya slash ("/") or by the back slash ("\") character.

If <skeleton> is not specified, only database files .dbf will be displayed. Otherwise,all the files that match the skeleton will be displayed.

Description:The .dbf list includes file name, date of the last update and number of records.Specifying a <skeleton> displays the files that match a file name pattern. The listincludes file names, attributes, their size and date of the last update, in a formatsimilar to the UNIX command "ls -l" or Windows DIR.

Note, that the information about specific file is also available via the DIRECTORY()or ADIR() functions.

Example:DIR *.* // same as: ls -l *.*DIR ("./[a-d]*.dbf") // same as: ls -l ./[a-d]*.dbfDIR // standard header (1)#ifdef FlagShipFS_SET ("load", 1, "FSsortab.ger")FS_SET ("set", 1)DIR // german header (2)

#endif

------------------- Output using DIR *.* ------------------

-rwxrwxr-x 1 jan program 459198 Sep 23 14:55 a.out-rw-rw-r-- 1 peter program 1845 Apr 27 19:03 adress.dbf-rw-rw-r-- 1 hugo user 657 Jul 15 16:08 adress1.dbf-rw-rw-r-- 1 sven program 30 Sep 01 18:42 dummy.prg-rw-rw-r-- 1 guest guest 1253 Jun 29 11:52 dummy.txt-rw-rw-r-- 1 peter program 115 Sep 11 14:28 tvarmac.prg------------------- Output using DIR *.dbf ----------------

-rw-rw-r-- 1 peter program 1845 Apr 27 19:03 adress.dbf

CMD 166

------------------- Output (1) using DIR ------------------

Database Files # Records Last Update Sizeadress.dbf 15 01/27/94 1845adress1.dbf 4 07/15/93 657

------------------- Output (2) using DIR and FS_SET()------

Datenbanken Saetze Letzt.Aender Groesseadress.dbf 15 27.01.94 1845adress1.dbf 4 15.07.93 657


Compatibility:The header for displaying the databases is user-definable in FlagShip viaFS_SET("load"). The <skeleton> output on UNIX is the same as in "ls -l" and differsfrom the output on DOS.

Translation:__DIR ("skeleton")

Related:DIRECTORY(), ADIR(), PUBLIC FlagShip, #ifdef FlagShip, FS_SET()

CMD 167

DISPLAYSyntax:

DISPLAY [OFF] [<scope>] <expList>[FOR <condition>][WHILE <condition>][TO PRINTER][TO FILE <file>|(<expC>) [ADDITIVE]]

Purpose:Displays the result of one or more expressions for each processed record.

Arguments:<expList> is the list of values displayed for each processed record.

Options:<scope> is the part of the current database file to display. The default scope is thecurrent record. If a condition is specified, the scope becomes ALL.<condition> specifies additional FOR or/and WHILE filtering. See the generalcommand description.OFF: Suppresses the display of the record number.TO PRINTER: echoes output to a printer file. To disable the screen output, use SETCONSOLE OFF.TO FILE: echoes output (ADDITIVE) to the specified file. See also the generalcommand description.

Description:DISPLAY sends the results of the <expList> to screen in a tabular format, eachcolumn being separated by a space. DISPLAY is similar to LIST, with the differencethat its default scope is NEXT 1, rather than ALL as in LIST.

Example:// Esc interrupts DISPLAY:

USE EmployeeDISPLAY Lastname, Firstname, Birthdate FOR INKEY() <> 27

Classification:sequential output

Compatibility:The ADDITIVE option is available in FlagShip only. C5 will accept but ignores it, if"/ustd.fh" is used.

Translation:__DBLIST (.off., {exp1 [,exp2...]}, .all., {for}, {while},;

next, rec, .rest., .toPrint., "file")

Related:LIST, SET EXTRA

CMD 168

DOSyntax:

DO <procname> [WITH <parameterList>]Purpose:

Executes a user-defined-procedure (UDP).

Arguments:<procname> is the name of the procedure to be executed. It can be written eitherin FlagShip or in the C language using the Extend System.

Options:WITH <parameterList> allows to pass any number of arguments, separated bycommas, to the UDP, which receives them as parameters. Each argument may bea single variable, field, array, array element, expression, or an object. Beforebranching to the UDP, the arguments in the <parameterList> are evaluated. Whenthe argument is an expression, macro-evaluation, constant, or function call, it ispassed as a reference to a temporary variable. Field variables have to be precededby an alias-> or FIELD->, or enclosed in parentheses.

Arguments can be skipped or left off the end of the list. The number of argumentsspecified does not have to match the number of parameters specified in the calledprocedure. If the number of arguments is less than the number of parameters, theparameter variables with no corresponding arguments are initialized with a NILvalue when the procedure is called.

A skipped argument, given a comma only, also initializes the correspondingparameter to NIL. To detect the position of the last argument passed in the<parameterList>, use PCOUNT(). To detect a skipped argument, compare thereceiving parameter to NIL or TYPE() / VALTYPE() to "U".

Parameter passing using the WITH clause is done by reference by default. Thismeans, the formal parameter receives the address of the current argument.Changes made to the parameter within the UDP called will be reflectedautomatically in the argument; only constants, expressions and database fieldsarguments remain unchanged. Closing an argument in parentheses, passes it "byvalue" instead.

Description:The DO statement calls a procedure (UDP), optionally passing arguments to thecalled routine. It performs the same action as a user-defined function (UDF) exceptthat DO passes parameters by reference as a default, and that a UDP has no returnvalue.

Compilation:When the FlagShip compiler is invoked without the -m option, it searches thecurrent directory for a source file with the same name in order to compile it, everytime it finds a DO statement and the name of the procedure is unknown. If it is not

CMD 169

found, the compiler considers the procedure externally. At link-time, the linker looksfor such unresolved externals in other object files or libraries given. If the externalhad not been found, the linker prints an error message like "unresolved external_bb_<procname>".

Example:The FlagShip will also compile the file xchange.prg automatically (because of theDO Xchange... statement) when compiled by: "FlagShip test.prg" (i.e. without -mswitch)

*** File TEST.PRGDO DispWork WITH "Dept", "Markt"number1 := 10number2 := 20DO Xchange WITH number1, number2? number1, number2 && 20 10DO Xchange WITH number1, (number2)? number1, number2 && 10 10 (unchanged)QUIT

PROCEDURE DispWork && list fieldsPARAMETERS field1, field2LIST &field1, &field2RETURN*** eof TEST.PRG

*** File XCHANGE.PRG && ┐ do not declare PROCEDURE* PROCEDURE Xchange && ┘ for the same file namePARAMETERS num1, num2PRIVATE dummydummy = num1num1 = num2num2 = dummyRETURN*** eof XCHANGE.PRG


Compatibility:FlagShip supports any number of parameters, Clipper up to 128, dBASE up to 50.The file name for additional compilation is searched in lower case only.

Related:PARAMETERS, PRIVATE, PROCEDURE, PUBLIC, RETURN, SET PROCEDURE

CMD 170

DO CASE..CASE ... ENDCASESyntax:

DO CASECASE <condition>

<statements> ...[CASE <condition>

<statements> ...][OTHERWISE

<statements> ...]ENDCASE | END

Purpose:A control structure to execute a set of statements according to the associatedconditions.

Arguments:DO CASE defines the structure beginning.

ENDCASE specifies the end of the structure. ENDCASE may be abbreviated withEND.

Options:CASE <condition>: if the condition given is met, the statements which follow willbe executed until the next CASE, OTHERWISE, or ENDCASE command isencountered; and the program control is passed to the next statement following theENDCASE.

When the condition is not met, the control branches to check the next CASEcondition, the OTHERWISE or ENDCASE command.

OTHERWISE: If all CASE conditions are false, the statements following theOTHERWISE command up to the ENDCASE are executed. If this option is notspecified, and all the CASE conditions are false, no statements inside the CASE areexecuted.

Description:The DO CASE ...CASE .. .ENDCASE is equivalent to the IF...ELSEIF ...ELSE ...ENDIF control structure, see also LNG.2.5.

There is no limit to the number of CASEs inside the structure. This structure can benested to any depth with other control structures.

CMD 172

DO WHILE ... ENDDOSyntax:

[DO] WHILE <condition><statements>...

[EXIT]<statements>...

[LOOP]<statements>...

ENDDO | ENDPurpose:

A control structure to execute a looping when the <condition> is true (.T.).

Arguments:WHILE <condition> is the controlling condition that is evaluated every time the DOWHILE or WHILE statement executes.

ENDDO specifies the end of the structure. If encountered, the program control ispassed back for the next DO WHILE condition check. ENDDO may be abbreviatedto END.

Options:EXIT: The EXIT statement terminates the looping, and branches unconditionally tothe statement following the ENDDO. Any number of EXITs within the structure areaccepted.

LOOP: The LOOP statement repeats the loop by immediately branching back to theDO WHILE condition check. Any number of LOOPs within the structure areaccepted.

Description:The DO WHILE structure executes a block of statements repetitively, as long as thespecified condition evaluates to true (.T.). The control is passed into the structureand proceeds until an EXIT, LOOP or ENDDO is encountered. ENDDO and LOOPpass control back to the beginning of the DO WHILE statement for a new iteration.

The DO WHILE construct terminates or is not processed at all, when the conditionevaluates to false (.F.). Control is then passed to the statement immediatelyfollowing the ENDDO.

Example:Repeat until construct: You can also use the DO WHILE to create a repeat untillooping construct as follows:

more = .T. * or:DO WHILE more DO WHILE .T.

IF <end condition> IF <end condition>more = .F. EXIT

ENDIF ENDIFENDDO ENDDO

CMD 173

Example:Traversing a database file: The DO WHILE looping construct enables you to movesequentially through a database file, as you can see in the following two examples:

DO WHILE .NOT. EOF()<statements>...IF <repeat the same record>

LOOPENDIFSKIP

ENDDO

Example:This example sequentially scans a database file, processing records that match acondition:

LOCATE FOR <condition>DO WHILE FOUND()

<statements>...CONTINUE<statements>...

ENDDO

Example:Macros on the DO WHILE command line: Macro variables can be used without anylimitations in the DO WHILE condition, partially or entirely.

var = "upper(trim(Name)) == 'SMITH'"DO WHILE &var .and. !EOF()

? name, cityvar = "zip = " + STR(zip)SKIP

ENDDO


Compatibility:Optionally shortening DO WHILE to WHILE is new in FS4, according to Clipper 5.x.

Related:FOR, IF, RETURN

CMD 174

EJECTSyntax:

EJECTPurpose:

Causes an advance to a new page while printing.

Description:In FlagShip, printer output normally goes to an internal print file, except when SETPRINTER TO <device> is specified (or with SET GUIPRINT ON). This avoidsprinter output being garbaged in multiuser mode.

EJECT sends a form-feed character [chr(12)] to the active SET PRINTER TO file, ifspecified, or else to the default spooling file (see SET PRINTER). The form feed issent regardless whether the current SET PRINT was ON or OFF.

EJECT also resets the internal printer row and column tracers of PROW() andPCOL() to zero. You may also reset the tracers only with SETPRC().

You may tune the printer driver by FS_SET("prset").

When printing via GUI/GDI driver (SET GUIPRINT ON), EJECT command sendform-feed, i.e. creates new page and increases the page number. For this mode, itis equivalent to _oPrinter:GuiNewPage()

Example:USE stock INDEX stocknoLIST stockno, article, price TO PRINTEJECTLIST stockno, article, retail TO PRINTEJECTprn_file = FS_SET("printfile") // get to file nameSET PRINT TO // flush fileRUN ("lp -dlaser -s " + prn_file) // spool it

Classification:sequential and GUI printer output

Compatibility:Spooled printer output is supported only in FlagShip.

Translation:__EJECT ()

Related:SET PRINTER, PCOL(), PROW(), SETPRC(), FS_SET("print"), FS_SET("prset")

CMD 175

ERASESyntax:

ERASE <file>|(<expC>)or

DELETE FILE <file>|(<expC>)Purpose:

Removes a file from disk.

Arguments:<file> is the name of the file (including extension) to be deleted. A full path may bespecified. If omitted, only the current directory is searched, the SET PATH or SETDEFAULT path is ignored. Standard UNIX wildcards using ?, *, [..] are supported.

Description:The file will be deleted without any warning. The consequences are notrecoverable. The user must have at least "w" access rights for the file and "x" forthe directory.

The success can be checked using DOSERROR().

Example:? FILE ("data.tmp") && .T.ERASE data.tmp? FILE ("data.tmp") && .F.ERASE "[k-m]d*.tm*"? DISERROR() && 0? FILE ("[k-m]d*.tm*") && .F.


Compatibility:Wildcard support and the DOSERROR() checking is available in FlagShip only.

The ERASE or DELETE FILE command is equivalent to the UNIX command "rm" orsimilar to the DOS command "DEL".

The command considers the automatic path and/or conversion using e.g.FS_SET("pathlower") and FS_SET ("lower"), the extension replacement usingFS_SET ("translext") and the drive substitution using the environment variablex_FSDRIVE.

Translation:FERASE ("file")

Related:CLOSE, USE, CURDIR(), FILE(), FS_SET ()

CMD 176

EXPORT INSTANCESyntax 1:

[STATIC] CLASS <ClassName> [INHERIT <SuperClass>]and optional:

INSTANCE <Name> [:= <exp>] [AS <type>]EXPORT [INSTANCE] <Name> ...HIDDEN [INSTANCE] <Name> ...PROTECT [INSTANCE] <Name> ...




See detailed description in the CLASS command.

CMD 177

EXTERNALSyntax:

EXTERNAL <nameList>Purpose:

Explicitly requests the procedures (UDP) or functions (UDF) to be linked into theapplication.

Arguments:<nameList> is a comma separated list of UDP/UDF names, Extend C functionsand format file names which should be added to the symbol table.

Description:EXTERNAL is used in case where user-defined-procedures or standard functionsare called only from within macro statements, included in the INDEX key, or passedas a character variable to ACHOICE(), DBEDIT() or MEMOEDIT(). Suchprocedures/functions might not be linked in at all if not specified in an EXTERNALstatement.

Generally: when you are using a UDP, UDF or standard function for the abovepurposes, and are not sure about calling it also by name elsewhere in theapplication, use EXTERNAL to ensure the name is known to the linker. Otherwise,a run-time error "unresolved external" may occur during application execution.

Example:* file test.prgEXTERNAL my_proc

var = "my_proc"DO &var WITH 1, 2* eof test.prg* File my_proc.prg* automatically declared: PROCEDURE my_procPARAMETERS p1, p2:RETURN* eof my_proc.prg


Compatibility:FlagShip does not support Clipper's division of pre-linked functions vs. libraries.

Related:SET PROCEDURE TO, REQUEST

CMD 178

FIELDSyntax:

FIELD <fieldList> [IN <alias>]Purpose:

Declares database field names to be used as if implicitly aliased.

Arguments:<fieldList> is a list of names to be declared as fields to the compiler. The fieldsfrom the <fieldList> are accessed as FIELD->fieldname or <alias>->fieldname.

Options:IN <alias> specifies an alias to assume when there are unaliased references to thenames specified in the <fieldList>. The fields will be accessed in the same manneras if <alias>->fieldname is given.

If the IN.. clause is not specified, unaliased references to <fieldList> are treated as ifthey are preceded by FIELD->fieldname alias.

Scope:The scope of the FIELD declaration is normally the procedure or function in which itoccurs. If the declaration is given prior to the first PROCEDURE or FUNCTION andthe compiler switch -na is used, the scope becomes the entire .prg file.

In FlagShip, the declarator may be placed anywhere in the code; the compiler startsthe aliasing of the FIELD variables after encountering the declaration and continuesto the end of the corresponding procedure/ function (or the .prg file).

Description:The FIELD declaration allows the compiler to resolve references to variables in the<fieldList> without explicit aliases. The FIELD statement has no effect onvariable/field references within macro expressions.

The FIELD statement neither opens a database file nor verifies the existence of thespecified fields. It is useful primarily to ensure correct references to fields to whichaccessibility is known to be guaranteed at runtime. At runtime, the field variablesare made accessible with the USE command. Attempting to access the fields whenthe associated database is not in USE will cause a run-time error.

When accessing an ambiguous variable, which was not specified by FIELD,MEMVAR or <alias>, fields of the current working area have precedence over thePRIVATE, autoPRIVATE or PUBLIC variables with the same name. The same istrue for accesses/replaces in the @...GET/READ command.

To replace a field value, the REPLACE command, an aliased field name, or theFIELD declarator have to be used; otherwise a memory variable will be used or anew autoPRIVATE created.

To check for and/or prevent from ambiguous occurrences of variables, the -w or -am option of the FlagShip compiler may be used.

CMD 179

Example:Without the -w compiler option, the missing "FIELD persno" declaration may passunnoticed; e.g. the field "persno" below remains unchanged instead of replaced.

FUNCTION output (first, last)FIELD name, lastname, zip, address, printedLOCAL recordGOTO (first)WHILE !EOF() .AND. RECNO() <= last

record = RECNO()printed := .T. // same as: REPLACE printed WITH .T.persno := record // PRIVATE persno is created/updated

** REPLACE persno WITH record // field will be replaced** FIELD->persno := record // field will be replaced** (ALIAS())->persno := record // field will be replaced

** FIELD persno // the ABOVE persno is not affected? record, name, lastname, zip, address, ;persno // output: database field

SKIPENDRETURN NIL


Compatibility:In FlagShip, the declarator may be placed anywhere in the code; in C5, thedeclarator position is fixed.

Related:LOCAL, MEMVAR, PRIVATE, PUBLIC, STATIC, @..GET

CMD 180

FINDSyntax:

FIND <keyC>|(<expC>)|&<memvar>Purpose:

Searches through an index to find the first key matching the specified characterstring and positions the record pointer onto the corresponding record.

Arguments:<keyC> is part of or the entire index key to be found. If (<expC>) is specified, FINDbehaves similar to SEEK.

Description:A search of the master index starts from the first key. If a match is found, the recordpointer is positioned to the record number found in the index, FOUND() returnsTRUE, EOF() returns FALSE.

If the searched for value is not found, the current state of SET SOFTSEEK affectsthe values returned from FOUND(), EOF() and the position of the record pointer:

•If SOFTSEEK is OFF (the default), FOUND() returns FALSE, EOF() returnsTRUE, and the database is positioned at eof = LASTREC() +1.

•If SOFTSEEK is ON, and there are keys with values greater than the searchargument, the database pointer is positioned to the first record with a key valuegreater than the searched argument, FOUND() returns FALSE and EOF() returnsFALSE.

•If SOFTSEEK is ON, and there is no key greater than the search argument, thedatabase is positioned at eof = LASTREC() +1, FOUND() returns FALSE andEOF() returns TRUE.

The SET DELETED switch and SET FILTER condition are considered. The currentstate of SET EXACT does not affect the search; the comparison is done as withSET EXACT OFF.

FIND is identical to SEEK, but has a slightly different syntax: FIND &<var> has thesame effect as SEEK <var>, FIND (<var>) is identical to SEEK <var>.

CMD 181

Example:USE employee INDEX idnumber, name* SET ORDER TO 1 && key: idnum (numeric 3)seek_id = 100find_id = "100"FIND 100 && foundFIND 005 && foundFIND 5 && foundFIND (STRZERO(10,3)) && foundFIND find_id && not foundFIND &find_id && foundSEEK seek_id && foundSEEK &seek_id && run-time-error

SET ORDER TO 2 && key: UPPER(name)find_name = upper("Smith")FIND SMITH

&& foundFIND Smith && not foundFIND (upper("Smith")) && foundSEEK upper("Smith") && foundSEEK "SMITH" && foundfind_name = upper("Smith")FIND &find_name && foundSEEK find_name && found


Translation:DBSEEK (&("key"))

Related:INDEX, LOCATE, SEEK, SET DELETED, SET EXACT, SET INDEX, SETSOFTSEEK, EOF(), FOUND(), RECNO(), oRdd:SEEK()

CMD 182

FOR ... NEXTSyntax:

FOR <memvar> = <expN1> TO <expN2> [STEP <expN3>]<statements>...

[EXIT]<statements>...

[LOOP]<statements>...

NEXT | ENDFORPurpose:

A control structure for executing a loop a specified number of times while eitherincrementing or decrementing a counter expression.

Arguments:<memvar> is the variable that controls the loop. If <memvar> is out of the boundary<expN1>..<expN2>, control is passed to the program statement following the NEXTcommand.

<expN1> is the initial value assigned to <memvar> and the lower (upper) boundaryof the looping range.

<expN2> is the upper (lower) boundary of the looping range, see also STEP.

NEXT | ENDFOR determines the end of the loop structure. When this command isencountered, the <memvar> is increased (decreased) by <expN3> (or by 1) and theprogram control is passed to the check boundary against <expN2>. If the check isfulfilled, execution continues with the next statement following the FOR... command.

Options:STEP <expN3> sets the increment value. If not specified, the default value is (plus)one.

Looping stops or is not executed at all when <memvar> is greater than <expN2>. If<expN3> is negative, the <memvar> is reduced and the looping stopped when<memvar> becomes lower than <expN2>.

EXIT: The EXIT statement terminates the looping, branching unconditionally to thestatement following the NEXT command. Any number of EXITs within the structureare accepted.

LOOP: The LOOP statement repeats the looping by branching on to complete theincrement/decrement and then back to the ...TO <expN2> condition check. Anynumber of LOOPs within the structure are accepted.

Description:The FOR...NEXT structure iterates the statements within from an initial value of thecontrol variable to a specified boundary. The control variable sweeps this range ofvalues for a increment specified in the STEP clause. In contrast to some other

CMD 183

programming languages, FlagShip evaluates the entire termination and incrementcondition each time it is encountered. This means that the upper boundary andincrement are dynamic - they can be changed as the loop operates.

Hint: Using TYPED variables and/or numeric constants for the control variable, stepand the end value increases loop speed significantly, see example LOCAL..AS.

Example:The FOR...NEXT construct is useful when dealing with arrays.

LOCAL_INT i, lenLOCAL array[1000], count := 1len = LEN(array)

FOR i = 1 TO len // Runs forward through an entire arrayarray[i] := i // 1..1000

NEXT

* Runs backwards through an entire arrayFOR i = len TO 1 STEP -1

array[i] = count++ // 1000...1NEXT


Compatibility:The ENDFOR statement is not available in Clipper, but in FoxPro.

Related:DO WHILE, BEGIN SEQUENCE

CMD 184

FUNCTIONSyntax 1:

FUNCTION <udfname> [AS <type>][PARAMETERS <paramList>]

<statements>...RETURN <exp>

Syntax 2:FUNCTION <udfname> (<paramList>) [AS <type>]

<statements>...RETURN <exp>

Syntax 3:[STATIC|INIT|EXIT] FUNCTION <udfname> (<paramList>)

[AS <type>]<statements>...

RETURN <exp>Purpose:

Declares a user-defined function (UDF) written in the FlagShip language and,optionally, its formal parameters.

Arguments:<udfname> is the declared name of the user-defined function. The function namecan be of any length, but only the first 10 characters are significant. Upper or lowercase makes no difference. The names can contain any combination of charactersA..Z, numbers, or underscores, but names with a leading underscore are reservedfor internal FlagShip functions.

RETURN <exp> terminates the execution of the UDF and passes control back tothe calling program returning the value of <exp> to the program module called. Anynumber of RETURNs, even when they have different types, may be placed withinthe UDF. The returned <exp> can be of any type, including array, code block orobject. If <exp> is not given or a RETURN command is not encountered, NIL isreturned. For typed function, the type of <exp> has to match to the declaredfunction <type>. Where the function returns different types, prototype it AS USUAL.

Options:STATIC FUNCTION declares a UDF which is visible in the current .prg file only.Several STATIC UDFs and UDPs (and only one public UDP/UDF) may be definedwith the same name in different .prg files.

Because the references to a STATIC function are resolved at compile-time, they willhide public UDF carrying the same name. STATIC functions are not generallyvisible and therefore cannot be used during a macro evaluation or as UDFs forACHOICE(), MEMOEDIT() etc.

CMD 185

When the keyword STATIC is omitted, the UDF becomes public and the namevisible to the entire application.

INIT FUNCTION declares a module, executed at program startup; see descriptionof INIT PROCEDURE.

EXIT FUNCTION declares a module, executed at program termination; seedescription of EXIT PROCEDURE.

PARAMETERS <paramList> specifies one or more comma separated PRIVATEvariables which receive the calling arguments. See more in the PARAMETERScommand.

(<paramList>) is an alternative syntax for the PARAMETERS command, but thevariables in <paramList> have LOCAL type and may optionally be typed, see below.

AS <type> (proto)types the function declaring it to return the specified <type> valueonly, see below. The specified type has to correspond to the RETURNed valuetype. If different value types (or NIL) is returned, (proto)type the function ASUSUAL. If the AS <type> is omitted, the implicit USUAL type is assumed. Note: onlyexplicitly typed functions are added to the repository file (e.g. reposit.fh) with the -rucompiler switch.

Prototyping of parameters and return value:The local parameters specified in brackets (according to syntax 2) may optionallybe typed (with all usual <type>s according to LOCAL..AS), and/or prototyped asoptional. The syntax is equivalent to (<paramList>) of the PROTOTYPE declarator,e.g.

FUNCT myUdf (p1 AS CHAR, [p2 as NUMER], p3, [p4]) AS LOGIC

If the <type> is not given (e.g. parameters p3 and p4 in this example), AS USUAL isassumed. The parameter name enclosed in square brackets [ ] (visually) signals anoptional parameter, used also in (and passed to) UDF prototypes. It does notchange the behavior of parameter passing, nor the parameter order in any way.

Also the return function <type> may be prototyped by using the syntax 1 or 2.

Purpose of the prototyping:Declaring a type of the return value allows to check the RETURN statement of aUDF and its usage (e.g. in assignments) already at compiler time. Giving theparameters a type allows a compile-time check of the parameters (arguments)passed to the function at places where it is invoked. Both of these compile-timechecks will help you to avoid unexpected RTEs (run-time errors) and simplifyparameter validation in the function body. See also "parameter passing" below.

Use the PROTOTYPE declarator (e.g. in an #include file), when the UDF is invokedin other than the current file (prototyping); or when the UDF is specified in the samefile, but is invoked before its declaration (forward prototyping) to take advantage ofthe compile-time checking.

CMD 186

Note: the PROTOTYPE statement is automatically created in the repository file (fortyped UDFs only) by using the -ru compiler switch, see FSC.1.3. All standardFlagShip functions are prototyped in the stdfunct.fh file.

Description:Functions and procedures increase both readability and modularity, andstandardize a block of frequently used statements.

A user-defined function (UDF) is called using the same notation as when calling astandard FlagShip function:

[value :=] udfName (parameters)

The UDF may be called within an expression or on a line by itself, ignoring thereturn value.

A user-defined function may also be called as an aliased expression by preceding itwith an alias and enclosing it in parentheses, like:

[value :=] alias->(udfName (parameters))[value :=] ("xyz"+var)->(udfName (parameters))[value :=] (SELECT()+1)->(udfName (parameters))

Functions called in this way will select the associated working area prior toexecution and re-select the original one on return.

Assigning the UDF return value to a typed variable is checked at compile-timeand/or run-time. If the function type is known at compile-time (see prototyping), anincorrect assignment is already reported by the FlagShip compiler. Otherwise, if thedeclared function type does not match the fixed variable type in the returnstatement, a run-time error occurs. Of course, a possible numeric conversion (e.g.AS NUMER to INTVAR etc.) is accepted and performed automatically.

A UDF may call itself recursively. The number of recursions in FlagShip is limitedonly by the available RAM + swap disk space to store the local data of eachrecursion.

Parameter passing:The calling arguments are passed to a user-defined function by value by default,except for array names and objects, which are always passed by reference.Variables other than field variables preceded by the @ operator are passed byreference.

The UDF receives the passed arguments into predefined PRIVATE or LOCALvariables in the <paramList>. The number of arguments passed and parametersreceived does not need to match. Arguments may be skipped or left off the end ofthe argument list. A parameter not receiving a value or reference is initialized toNIL. Refer to LNG.2.3.2 and (CMD) PARAMETERS for a more detailed discussion.

On typed parameters, only arguments of the specified parameter type are accepted.If the prototype of the UDF is known at compile time (see prototyping), an incorrectargument passing is reported by the FlagShip compiler. If the prototype or theargument type is unknown at compile time, and an incorrect argument type is

CMD 187

passed, a run-time error occurs. On optional parameters (i.e. enclosed in squarebrackets), only the specified type or NIL is accepted.

UDF vs. UDPIn FlagShip, the only difference between the call to a function (UDF) or procedure(UDP) is the convention of default parameter passing. Both UDFs and UDPs maybe used interchangeably. Hence, if a function (UDF) is called using the procedure'sDO...WITH invocation, the parameters are passed per default by reference, insteadof by value as with a standard UDF call.

Example:The example centers a string using a user-defined function:

center (20, "user message")text = "Hello!"@ 30, cent_col(text) SAY textFUNCTION cent_col (string)RETURN INT((MAX_COL() - LEN(string)) /2)

FUNCTION centerPARAMETERS row, string@ row, cent_col(string) SAY stringRETURN NIL

Example:Usage of typed parameters and typed function. The first parameter is optional:

PROTO FUNCT centOut ([par1 AS nume], par2 AS char) AS NUMERLOCAL xx AS logical, yy AS numericLOCAL tt := "Hello world!" as character

centOut (5, "Text in line 5") // okdevpos(10,0)centOut ( , "centered text at line 10") // okyy := centOut (NIL, tt) // okxx := centOut (NIL, tt) // compiler errorcentOut (6, xx) // compiler error

FUNCTION centOut ([row AS numer], string AS char) AS NUMERLOCAL col := INT((MAXCOL() - LEN(string)) /2) // [as numer]row := min (if (row == NIL, row(), abs(row)), maxrow())@ row, col SAY stringRETURN col

Example:In the following example a variable is passed to a user-defined function by valueand then by reference. Note that the second case changes the original variable aswell.

value = 10? change(value), value // 20 10? change(@value), value // 20 20

STATIC FUNCTION change (par)par *= 2 // par = par * 2RETURN par

CMD 188

Example:The next example demonstrates how to validate a data entry using a user-definedfunction:

x = 0@ 1,0 SAY "Enter number: " GET x VALID checkit(x, 10, 20)READRETURN

FUNCTION checkit (numb, toolow, toohigh)RETURN (numb > toolow .AND. numb < toohigh)

Example:Usage of aliases:

USE address NEW ALIAS addr // field adr_no? TYPE("adr_no"), TYPE("cust_no") // N UUSE custom NEW INDEX custno // field cust_no? TYPE("adr_no"), TYPE("cust_no") // U N? addr->(TYPE("adr_no")), TYPE("cust_no") // N N

SELECT addrIF custom->(my_replace (adr_no, 55))

? "replacing o.k."ENDIF? ALIAS () // addr

FUNCTION my_replace (number, value)? ALIAS() // customSEEK number // search for adr_noIF FOUND() // in cust_no

REPLACE cust_no WITH valueRETURN .T.

ENDIFRETURN .F.


Compatibility:The STATIC, INIT and EXIT clause and the use of formal LOCAL parameters iscompatible to C5. FlagShip accepts returning from a UDF by RETURN or when theend-of-file or next UDF declaration is reached, NIL is returned. In Clipper, the <exp>value must be specified.

Typed parameters and typed functions are supported by FlagShip and VO. Thedefinition of optional parameters by using square brackets is available in FlagShiponly.

Related:PROCEDURE, PARAMETERS, PROTOTYPE, RETURN, SELECT

CMD 189

GLOBAL ... ASSyntax 1:

GLOBAL <tvarList> [:= <constN>] AS <C-type>Syntax 2:

GLOBAL_<C-type> <tvarList> [:= <expN>]Purpose:

Declares and initializes C-TYPED GLOBAL variables.

Arguments:<tvarList> is a comma separated list specifying the names of variables, to bedeclared as TYPED GLOBAL. The same naming convention (10 significantcharacters, no case dependence, conversion to lower case) is valid as for the othertyped variables. See LOCAL..AS.

AS <C-type> is the alternate syntax to GLOBAL_<type> where <C- type> is one ofthe C-like type keywords listed in LOCAL...AS.

Example of valid syntax:GLOBAL iVar := 4, ipos := 0, iCount AS INTCLOBAL_LONG iOther := 5, myCount

Options:<constN> is a numeric constant within the <type> range to initialize the variable atprogram start. If not given, the TYPED GLOBAL variables will be initialized withzero.

Scope, Visibility:The TYPED GLOBAL variables may be described also as "STATICs with anapplication-wide visibility". They are very similar to global C variables and have alifetime of the entire program. They are visible within the entity that defines them;other entities have to enable the visibility, if needed, using the GLOBAL_EXTERNdeclaration.

•UDF wide scope: if the declaration is given within the procedure or function body,the variables are visible in this module only; all other modules may enable thevisibility using the GLOBAL_EXTERN declaration.

•File-wide scope: if the declaration is placed prior to the first FUNCTION orPROCEDURE statement and the compiler switch -na is used, the variable isvisible for all UDFs or UDPs within these .prg files. Modules in all other .prg filescan enable the visibility using GLOBAL_EXTERN.

Description:Using TYPED GLOBAL variables is identical to other typed variables, likeLOCAL..AS. They may be used directly in any expression, command or #Cinlineprogram part.

CMD 190

Like LOCAL and STATIC, typed GLOBAL variables are invisible within a macroevaluation and will hide PRIVATE or PUBLIC variables having the same name. TheTYPED variables will always be passed to UDF and UDP by value, regardless ofthe calling convention used (@ prefix or using the DO...WITH procedure call).

Normally, only one GLOBAL...AS variable of the same name is allowed for thewhole application. Some linkers accept a multiple declaration, but do not definewhich initializing value is used.

Example:Using typed variables:

*** file test1.prg, calls --> test2.prg ***#ifndef FlagShip // Clipper compatib.

#define LOCAL_INT LOCAL#define GLOBAL_EXTERN_LONG MEMVAR

#endifLOCAL_INT aa, bb := 15GLOBAL_EXTERN_LONG gg // enable visibility

? VALTYPE(aa), VALTYPE(gg) // N N? aa, bb, gg // 0 15 1aa = 3my_funct (aa, bb)? aa, bb, gg // 3 15 2bb *= 2gg := 5my_funct (3, 0)? aa, bb, gg // 3 30 6

*** file test2.prg ***#ifndef FlagShip // Clipper ?

#define LOCAL_LONG LOCAL#define GLOBAL_LONG PUBLIC

#endif

function my_funct (p1, p2)LOCAL_LONG aa, bbGLOBAL_LONG gg := 1 // declare it? VALTYPE(aa), VALTYPE(gg), aa, bb, gg // I I 0 0 1? VALTYPE(p1), VALTYPE(p2), p1, p2 // N N 3 0p1 := p2 := aa := 5gg++? aa, bb, gg, p1, p2 // 5 0 2 5 5RETURN NIL

Example:see more examples in GLOBAL_EXTERN, LOCAL...AS, STATIC...AS, CALL,#Cinline.


CMD 191

Compatibility:

Typed variables are available in FlagShip only. To be compatible to Clipper 5, usePUBLICs:

#ifndef FlagShip# define GLOBAL_INT PUBLIC# define EXTERN_INT MEMVAR#endif

Related:GLOBAL_EXTERN, LOCAL, LOCAL...AS, STATIC, STATIC...AS, PRIVATE,PUBLIC, CALL, FIELDS, DO, FUNCTION, TYPE(), VALTYPE(), #define, #ifdef,#Cinline

CMD 192

GLOBAL_EXTERN ... ASSyntax 1:

GLOBAL_EXTERN <tvarList> AS <C-type>Syntax 2:

GLOBAL_EXTERN_<C-type> <tvarList>Purpose:

Enables access to a C-TYPED GLOBAL variable from other program modules.

Arguments:<tvarList> is a comma separated list specifying the names of variables, declared inother procedure or .prg file as TYPED GLOBAL, see GLOBAL...AS.

AS <C-type> is the alternate syntax to EXTERN_GLOBAL_<type> where <type> isone of the C-like type keywords listed in LOCAL...AS.

Example of valid syntax:GLOBAL_EXTERN_INT iVar, ipos, iCount AS INTCLOBAL_EXTERN_LONG iOther, myCount

The variable's <C-type> specifies the storage range, which must be identical withthe one declared by GLOBAL...AS.

Scope, Visibility:The GLOBAL_EXTERN scope is similar to that of other typed or local/staticvariables:

•UDF wide scope: if the declaration is given within the procedure or function body,the variable visibility is enabled in this module only.

•File-wide scope: if the declaration is placed prior to the first FUNCTION orPROCEDURE statement and the compiler switch -na is used, the variable isvisible for all UDFs or UDPs within these .prg files.

Description:The GLOBAL_EXTERN enables the visibility to a GLOBAL...AS variable of thesame name, declared elsewhere in the application.

The <C-type> of GLOBAL_EXTERN will be not checked against the GLOBAL...ASdeclaration; if a different <C-type> is used, unpredictable results will occur. If thevariable is not declared at all, the linker error "unresolved external" occurs.

When the visibility is enabled, the GLOBAL variable can be modified by the currentprocedure (or by all UDF/ UDPs of the .prg file, see scope).

Example:The variable "byte" may be used/accessed also in other .prg files usingGLOBAL_EXTERN. No naming conflicts occurs with other variable types, ifGLOBAL_EXTERN is not used.

CMD 193

FUNCTION my_udf1 (par1)GLOBAL_BYTE byte? byte // 0my_udf2 ()? byte // 2my_udf3 ()? byte // 2my_udf2 ()? byte // 4RETURN NIL

FUNCTION my_udf2EXTERN_GLOBAL_BYTE bytebyte += 2RETURN

FUNCTION my_udf3LOCAL bytebyte := 5RETURN


Compatibility:Typed variables are available in FlagShip only. To be compatible to Clipper 5, usePUBLICs:

#ifndef FlagShip# define GLOBAL_INT PUBLIC# define GLOBAL_EXTERN_INT MEMVAR#endif

Related:GLOBAL, LOCAL, STATIC, PRIVATE, PUBLIC, FIELDS, DO, FUNCTION, TYPE(),VALTYPE(), #define, #ifdef, #Cinline

CMD 194

GO | GOTOSyntax:

GO <expN>|TOP|BOTTOMor:

GOTO <expN>|TOP|BOTTOMor:

GO TO <expN>|TOP|BOTTOMPurpose:

Moves the record pointer to a specific record in the current working area.

Arguments:<expN> is the record to which the record pointer is to be positioned. Positioning isdone even if the record falls outside the FILTER scope, or SET DELETED is ON.Records not present in an index created with SET UNIQUE ON orINDEX...UNIQUE can also be accessed.

TOP: GOTO TOP moves to the first record of the controlling index, if there is one,or to record 1, if there is no index in use. If there is a filter scope, GOTO TOPmoves to the first record of the scope, as in the command LOCATE. At the time ofopening a database and/or index by USE, USE...INDEX and SET INDEX TO... orassociated functions, GO TOP is executed automatically when SET GOTOP is ON.The default setting is OFF to enable programmable integrity check.

BOTTOM: GOTO BOTTOM moves to the last record of the controlling index, ifthere is one, or to LASTREC(), if there is no index in use. If there is a filter scope,GOTO BOTTOM moves to the last record of the scope.

Description:GO and the synonym GOTO are database commands which position the recordpointer in the current working area to a specified physical record or at the (logical)top or bottom of the file.

Using the TOP or BOTTOM criteria also obeys the SET FILTER and SETDELETED condition. This may be time consuming on large database, because thefulfilling criteria has to be looked for, by skipping forward or backwards from thefirst/last record.

Using GOTO <expN> is a fast database access. If the required record number<expN> is out of range, no run time error is generated, but the database pointer ispositioned to LASTREC()+1, EOF() and BOF() are both set to TRUE.

Multiuser:In multiuser environment, the internal and UNIX buffers can also be refreshed usingGOTO RECNO() (or SKIP 0, COMMIT). See more in LNG.4.8.

CMD 195

Example:USE employee? RECCOUNT() && 100GO 1 + 2 * 3? RECNO() && 7GO BOTTOM? RECNO() && 100SET INDEX TO NameGO BOTTOM? RECNO() && 17? Lastname && SmithGO TOP? RECNO() && 59? Lastname && Aaron


Translation:DBGOTO (expN)DBGOTOP ()DBGOBOTTOM ()

Related:SET GOTOP, SKIP, LOCATE, COMMIT, LASTREC(), RECNO(), oRdd:GOTO(),LNG.4.8

CMD 196

HIDDEN INSTANCESyntax 1:







CMD 197

IF ... ENDIFSyntax:

IF <condition><statements>...

[ELSEIF <condition>]<statements>...

[ELSE]<statements>...

ENDIF | ENDPurpose:

A control structure to conditionally execute a block of commands.

Arguments:<condition> is the control expression. If <condition> evaluates to true (.T.) all thecommands following are executed until an ELSEIF, ELSE or ENDIF is encountered.Otherwise, the control is passed to the next ELSEIF condition if given, or the firstcommand following the ELSE statement. If there is no ELSE statement, the controlis passed to the next program statement following the ENDIF.

ENDIF may be shortened to END.

Options:ELSEIF <condition>: The ELSEIF clause will be evaluated if the previous IF and/orELSEIF conditions are returned false. If the <condition> evaluates to true (.T.), thefollowing commands are executed until an ELSEIF, ELSE or ENDIF is encountered.The control structure may contain any number of ELSEIF clauses.

ELSE: The ELSE clause is used to identify the commands that are to be executed ifneither the previous control expression <condition> was successful.

Description:IF...ENDIF structures may be nested with other structured programmingcommands, and also within other IF...ENDIF structures. This structure is equivalentto the DO CASE...CASE...END sequence.

Example:* the structure: * is equivalent to:DO CASE |

CASE value < 10 | IF value < 10? "up to 10" | ? "up to 10"

CASE value <= 100 | ELSEIF value <= 100? "10 to 100" | ? "10 to 100"

CASE value <= 1000 | ELSEIF value <= 1000? "101 to 1000" | ? "101 to 1000"

OTHERWISE | ELSE? "1000 and up" | ? "1000 and up"

ENDCASE | ENDIF

CMD 199

INDEX ON...TOSyntax 1:

INDEX ON <exp> TO <file>|(<expC1>)[UNIQUE][NOLOCK]

Syntax 2:INDEX ON <exp> TO <file>|(<expC1>)

[TAG <tagName>][NOLOCK][FOR <condition> [<scope>]

[WHILE <condition>] ][EVAL <expL2> [EVERY <expN3>]][UNIQUE][ASCENDING | DESCENDING]

Purpose:Creates a file that contains an index to records in the current database file.

Arguments:<exp> is an expression that returns, for each record in the current database file, thekey value to be placed in the index. <exp> can be character, numeric, date, orlogical type.

In the default DBFIDX driver, the maximum length of the given <exp> string, storedin the index header, is 420 bytes, of the evaluated expression (index key) up to 238bytes.

<file> is the name of the index file to be created. The default file name extensionwith the default DBFIDX driver is .idx if none is specified.

Options:UNIQUE specifies that index <file> includes only unique key values. The result isidentical to SET UNIQUE ON, but the UNIQUE clause has precedence over theSET switch.

NOLOCK avoids check for the FLOCK() or EXCLUSIVE open, being in SHAREDmode. See "Multiuser" below.

TAG <tagName> is the name of the order to be created in the <file> bag.Supported only by RDD drivers with multiple order capability, ignored by RDDs withsingle-order bags (like the default DBFIDX).

FOR <condition> creates an index including only a subset of records met by the<condition>. If the clause is not specified, the index file includes all records of thedatabase. The <condition> is stored in the .idx header and therefore is consideredwhen updating or REINDEXing the index file. The maximum length of the FOR<condition> is 198 bytes.

CMD 200

WHILE <condition> specifies an additional index filter. Applied during indexing,and together with the FOR clause only; not used for other index operations.

<scope> is the part of the current database file to be indexed. Applied duringindexing, and together with the FOR clause only; not used for other indexoperations. The default scope is ALL records.

EVAL <expL2> is similar to the WHILE <condition> but it may be executed at aspecific record interval given by the EVERY <expN3> clause. The <expL2> mustreturn TRUE to continue the indexing. The EVAL clause may be used, for exampleto monitor the progress of the indexing, using an UDF. If <expN3> is not specified,the default value is one (each record).

ASCENDING | DESCENDING specifies that the index keys are sorted in increasingor decreasing order. The default is ASCENDING.

Note: the INDEX ON command stores the following data in the header of the .idxfile (the sizes may vary with other RDDs):

•the <exp> string as given (max. 430 bytes),•the FOR <condition> string (max. 230 bytes),•the UNIQUE (or current SET UNIQUE) status,•the ASCEND/DESCEND status.

The REINDEX command takes all these stored parameters into consideration. Allother arguments, like the scope, WHILE, EVAL, EVERY clause are used onlyduring the INDEX ON process. Additionally the following data is also stored in the.idx file header (with the DBFIDX driver):

•the name of the active database, and

•the current update counter of the .dbf to synchronize integrity checking (seeLNG.4.5)

Description:If records are required to appear in a specific order in the database file they couldbe SORTed. However, this would cause physical reordering, which is rather timeconsuming. If the application later requires ordering according to some othercriterion, it would be very inefficient.

To solve this problem, index files were designed. The command INDEX ON willbuild a file consisting of values of key expressions evaluated on the records of thedatabase and pointers to their physical location in the file. In this manner,manipulation is much quicker and as many different index files as needed can bebuilt. Changing the database contents will automatically update all assigned indices,so re-indexing is not necessary at all.

When INDEX ON is invoked, all open index files in the current working area areclosed and the new index file is created. After the command has been completed,the index file created remains open becoming the controlling index and the record

CMD 201

pointer is positioned to the first record in the index. The created index file can beused by the executable which creates it only, until SET INDEX, USE or CLOSEreleases it for sharing.

Indexing may be aborted by invoking oRdd:Abort() or by returning .F. value fromoptional codeblock(s) supplied via oRdd:BlockStart() or oRdd:BlockDone() oroRdd:BlockEval() = DbObject():Block*()

Index key size:All index keys within the same index file (or tag) must always have the same size.If TRIM() is used, the key must be extended with spaces to resolve the default keylength:

INDEX ON TRIM(name) + STR(zip,6) + ;SPACE (LEN(name) - LEN(TRIM(name))) TO ...

INDEX ON PADR(TRIM(name) + STR(zip,6), 50) TO ...

Sorting order:INDEX orders character keys according to the ASCII value of each character withinthe string, numeric values in numeric order, date values chronological order withblank dates treated as low values, and logical values sorted with the orderFALSE...TRUE. Memo fields cannot be INDEXed.

To create descending order indices use the DESCEND() function or theDESCENDING clause. The function accepts any data type as an argument andreturns the value in complemented form. Then, when performing a SEEK into theindex, use DESCEND() as a part of the SEEK argument. Using the DESCENDINGclause, use SEEK without the DESCEND() function.

Deleted records:Deleted and filtered records are included in the index until PACK is executed. Toomit them, the FOR !DELETED() clause can be used.

Using variables:LOCAL, STATIC and typed variables cannot be used in index key expressions,because the stored <exp> string is later evaluated as macro to produce the currentkey values. For the same reason, the compile-time declarations using MEMVAR orFIELD, are not valid within an index key expression; but explicit aliasing may beused instead, if required.

With a numeric key expression (i.e. not a simple database field but a calculation oran UDF call) returning floating number, a RTE (run-time error) 311 may occurduring adding/replacing the database record because of possible numericinaccuracy. To avoid this, you should use INT(expr) or ROUND(expr,n) for the indexkey. Otherwise FlagShip changes the index key automatically during INDEX ON ...to fixed decimals by ROUND(expr,deci), where <expr> is the supplied expressionand <deci> is the current SET DECIMAL value. This manual adjustment of thedecimal precision is not required nor is done automatically when indexing a simplenumeric field (i.e. with the usual INDEX ON operation), since the decimals arealways fix in the database.

CMD 202

Unique and conditional indexes:If the clause UNIQUE is used, or SET UNIQUE is set to ON during INDEX ONcreation, only the first occurrence of a key will be stored in the index file.Subsequent REPLACE, PACK and REINDEX commands do not add a new key, ifthe same one is already available. Since the unique status is stored in the index fileheader, SET UNIQUE only takes effect during the index creation using the INDEXON command.

Using the FOR, WHILE or EVAL clause may create an empty index. If such anindex is used or selected thereafter, both BOF() and EOF() return TRUE and therecord pointer is set beyond the end of database file (LASTREC()+1).

Hint: The usage of a filtered index using the FOR, WHILE or EVAL clause is similarto SET FILTER TO... but may speed-up the searching significantly compared to e.g.LOCATE, SET FILTER ... GOTO TOP etc. especially on large database. Also, theusage of filtered index in BROWSE(), DBEVAL() or TBrowse is almost much fasterthen SET FILTER.

Multiuser:During the INDEX ON, the required database must be exclusively opened usingUSE...EXCLUSIVE or SET EXCLUSIVE ON. If the index file is not being used byother users, the FLOCK() can alternatively be used in SHARED mode to ensuredata integrity, or AUTOFLOCK will be used, if not disabled. See also LNG.4.5 andLNG.4.8. You may avoid the FLOCK() check or the AUTOFLOCK() invocation bythe NOLOCK clause.

Example:Creates /usr/data1/pers_titl.idx and /usr/data2/pers_bd.idx

#ifdef FlagShipFS_SET ("lower", .T.)FS_SET ("pathlower", .T.)FS_SET ("translext", "ntx", "idx")

#endif

ind1 = "\usr\Data1/pers_titl"SET DEFAULT TO "\usr\Data2"USE Adres NEWif !FILE("Pers_BD.ntx") .or. !FILE(ind1+INDEXEXT())

INDEX ON birth_date TO Pers_bdINDEX ON title + DESCEND(DTOS(birth_date)) TO &ind1

endifSET INDEX TO Pers_bd, &ind1

CMD 203

Example:The same example for multiuser/multitasking:

SET EXCLUSIVE OFFind1 = "/usr/data1/pers_titl"SET DEFAULT TO "/usr/data2"IF !FILE("Pers_bd.idx") .or. !FILE(ind1+INDEXEXT())

USE adres EXCLUSIVE NEW && open dbf exclusiveDO WHILE NETERR() && if no success:

INKEY(3) && wait andUSE adres EXCLUSIVE && try again

ENDDOINDEX ON birth_date TO pers_bdINDEX ON title + DESCEND(DTOS(birth_date)) TO &ind1USE && close from exclusive

ENDIF

USE adres && open dbf shareableDO WHILE NETERR() && if no success:

USE adres && try againENDDOSET INDEX TO pers_bd, &ind1

Example:Report the percentage of the index processed. See other examples inDBCREATEINDEX().

LOCAL count, perc := 0USE address NEW EXCLUSIVEcount := LASTREC()INDEX ON UPPER(name) + STR(zipcode,6) TO namezip ;

EVAL mydisplay(perc++) EVERY INT(count/100) ASCENDING

FUNCTION mydisplay (out)@ 20,10 say "Indexing, " + STR(out,3) + "% ready"RETURN .T.

Example:Filtered database, similar to SET FILTER TO but the access is much faster,specially on large database. Of course, the special index may be build once onlyand assigned thereafter with SET INDEX TO ... SET ORDER.

USE address NEW SHAREDIF !file("special" + indexext())

WHILE !FLOCK(); END // at least Flock requiredINDEX ON UPPER(name) + zip ;

FOR TRIM(country)=="D" TO specialUNLOCK // free lock

ENDIFSET INDEX TO name, special // two indices usedSET ORDER TO 2GOTO TOP // only indexed recordsDBEDIT (1,1, maxrow()-1,78) // are visible nowSET ORDER TO 1 // all records are visible

which is similar to:

CMD 204

USE address NEW SHAREDSET INDEX TO nameSET FILTER TO TRIM(country) == "D" // the filter is slowerGOTO TOP // only filtered recordsDBEDIT (1,1, maxrow()-1,78) // are visible nowSET FILTER TO // all records visible

Example:Check database/index integrity:

USE address INDEX name EXCLUSIVE? "Integrity: ", INDEXCHECK() // .T.REPLACE name WITH "nobody"SET INDEX TO name, zipcodes // index integrity unknown? INDEXCHECK(1), INDEXCHECK(2) // .T. .F.

FS_SET ("develop", .T.) // set "developer" modeSET ORDER TO 2SKIP // RTE warning occurs

FOR ii = 1 TO INDEXCOUNT() // rebuild indicesIF .not. INDEXCHECK(ii) // when integrity violated

REINDEXEXIT

ENDIFNEXT


Compatibility:The index <file> has the default extension .idx in FlagShip, .NTX in Clipper and.NDX in dBASE. The internal structures of the index files and the lockingmechanism are not compatible in these different dialects.

Programs ported from DOS or other UNIX systems with different hardware have tocreate new indices using INDEX ON. To check the index file existence using FILE(),either INDEXEXT() or FS_SET("transl") can be used for portable applications.

The integrity check and the NOLOCK clause is available in FlagShip only.

FS support an unlimited number (65000) of indices for each working area/database

The index structure of FS4.x and FS6 is not compatible. On attempt to access theFS4.x index by application compiled by FS4, run-time error message occur. You willneed INDEX ON..TO.. on the first use by FS6. The new index structure issignificantly faster, support automatic PC8/ANSI conversion and the key size isincreased.

CMD 205

Translation:Syntax 1: DBCREATEINDEX ("file","exp", {||exp}, ;

.unique., .nolock.)Syntax 2: ORDCONDSET ("for", {||for}, .all., {||while}, ;

{||eval}, every, RECNO(), next, rec, ;.rest., .descend.)

ORDCREATE ("file", "tag", "exp", {||exp}, ;.unique., .nolock.)

Related:REINDEX, DBCREATEINDEX(), SET INDEX, SET ORDER, SET UNIQUE, USE,SEEK, FIND, SET EXCLUSIVE, CLOSE, DTOS(), INDEXCHECK(), INDEXEXT(),INDEXKEY(), INDEXORD(), INDEXCOUNT(), INDEXNAMES(), INDEXDBF(),NETERR(), FS_SET(), SET AUTOLOCK, AUTOFLOCK(), oRdd:SetOrder-Condition(), oRdd:CreateOrder()

CMD 206

INPUT ... TOSyntax:

INPUT [<exp>] TO <memvar>Purpose:

Waits for an expression to be typed in from the keyboard. The result is placed in amemory variable.

Arguments:<memvar> is the memory variable where the entered user input is stored. If thevariable is not visible or does not exist, a new autoPRIVATE variable is created.

Options:<exp> is the optional prompt which is displayed in front of the entry area. It can bean expression of any data type. If not given, no prompt is displayed.

Description:INPUT is a console command with wait state. First, a NEW LINE and the prompt (or"") is displayed. The user input is evaluated using the macro (&) operator, and theresult is stored in <memvar>. The type of expression entered determines the type ofmemory variable which is set.

The entry from the keyboard is terminated by the ENTER <┘key. Among specialkeys, only BACKSPACE is supported. If nothing was entered, the variable is notchanged (or created).

If the response should be a character type, it has to be enclosed in single or doublequotes; or the alternate commands ACCEPT, WAIT or @...GET are used. Unlikethese, INPUT allows a complex expression to be entered using variables, functionsetc. If the result of date type is required, the entry must be placed in curly bracketsor evaluated by the program using CTOD().

Example:This function returns .T. if the user wants to quit

FUNCTION Quitfun (text)LOCAL answPRIVATE yes := y := ja := oui := .T.PRIVATE no := nein := n := .F.INPUT text + " ? " TO answIF VALTYPE(answ) = "L"

RETURN answENDIFRETURN .F.

CMD 207


Translation:IF ( !EMPTY (__ACCEPT ("exp")) )<memvar> := &( __ACCEPTSTR () )

END

Related:@...SAY...GET, ACCEPT, WAIT

CMD 208

INSTANCESyntax 1:





INSTANCE <Name> [AS <type>]EXPORT|HIDDEN|PROTECT [INSTANCE] <Name>

[AS <type>]

CMD 209

JOIN WITH...TO...Syntax:

JOIN WITH <alias>|(<expC1>) TO <file>|(<expC2>)FOR <condition>[FIELDS <fieldList>]

Purpose:Creates a new database by merging specified records and fields from two opendatabase files.

Arguments:WITH <alias> specifies the file to merge with the database in the current workingarea to create the <file>.

TO <file> is the name of the target database file.

FOR <condition> selects only records meeting the <condition>.

Options:FIELDS <fieldList> specifies comma separated fields from both areas, which willbe the structure of the new file. Fields not from the primary working area have to bereferenced by an alias. Note that, if the primary or secondary areas have relationsset to some other working areas, those relations will be taken care of, so fields fromother working areas can also be specified.

Description:For each record in the primary area, JOIN analyzes all the records from thesecondary area, and creates a new target record each time the <condition> isfulfilled. This means, the operation will take time and can create a lot of newrecords: the product of both databases, RECCOUNT() * <alias>->(RECCOUNT()) ifno filter is used. JOIN should therefore be used with care.

Example:USE articleUSE authors ALIAS aut NEWSELECT articleJOIN WITH aut TO artauth FOR name = Authors->name


Translation:__DBJOIN ("alias", "file", {"field1",... }, {for} )

Related:APPEND FROM, REPLACE, SET RELATION, oRdd:JOIN()

CMD 210

KEYBOARDSyntax 1:

KEYBOARD <expC> [ADDITIVE]Syntax 2:

KEYBOARD <expN> [, <expN>, ...] [ADDITIVE]Purpose:

Places a string into the keyboard buffer.

Arguments:<expC> is the string to place into the keyboard buffer. Any INKEY() valid code canbe used, e.g. "Abc" + CHR(13) + CHR(-5). If the character is out of rangeCHR(1...255), a two byte character code is placed into the keyboard buffer to beremoved afterwards by any wait status command.

<expN> is the Inkey value to place into the keyboard buffer. Any INKEY() validcode can be used, e.g. K_F5, K_ALT_X, K_RBUTTONDOWN, ASC("X"). Note: ifyou add mouse movement or buttons in keyboard buffer and retrieving it later byInkey(), it does neither affect the reported Mrow() and Mcol() position, nor theautomatic mouse movement or button trapping.

Options:ADDITIVE: If the clause is specified, the string is added at the end of the keyboardbuffer. Otherwise, the current contents of the buffer will be overwritten by the newcontents.

Description:Normally, FlagShip stores all keystrokes typed on the terminal in an internal bufferof variable length, cf. LNG.5.2.1. The characters remain in the keyboard buffer untilfetched by a wait state command/function such as ACCEPT, INPUT, READ, WAIT,ACHOICE(), MEMOEDIT(), DBEDIT(), or INKEY().

KEYBOARD can be used to fill the internal buffer by simulating user input. Forexample, filling the buffer from a DBEDIT() user defined function may cause it toperform more actions at once. It can also be used to position the cursor within aREAD, if it is to be positioned at a specific GET which is not the first one.

Example:Positions the cursor initially at the fifth GET (city):

USE authorsGO TOP@ 1,2 GET adrtype@ 2,2 GET name@ 3,2 GET firstname@ 4,2 GET zip PICTURE "99999"@ 4,9 GET city

CMD 211

KEYBOARD REPLICATE(CHR(13), 4)

READ


Compatibility:The ADDITIVE clause is not supported by Clipper but is the default in dBASE.Clipper allows characters with INKEY() codes between zero and 255 only. Numericparameters are available in FS only.

Translation:__KEYBOARD ("expC", .add.)

Related:SET TYPEAHEAD, INKEY(), READ, ACCEPT, INPUT, WAIT, CHR(), LASTKEY(),NEXTKEY(), REPLICATE(), FS_SET("zerobyte")

CMD 212

LABEL EDITSyntax:

LABEL EDIT <file>|(<expC>)[SIZES <expA1>][MESSAGES <expA2>]

Purpose:Creates/modifies labels in interactive mode for later use by the LABEL FORMcommand.

Arguments:<file> is the file which holds the definition of the report. If the file exists, it ismodified, otherwise a new report is created. The default extension is .lbl.

Options:SIZES <expA1> specifies the array of available sizes. Per default <expA1> is setto:

{{'3.5x15", 16x1', 35,5,1, 1,0,0}, ;{'3.5x15", 16x2', 35,5,2, 1,0,0}, ;{'3.5x15", 16x3', 35,5,3, 1,0,0}, ;{'4x17", 16x1', 40,8,1, 1,0,0}, ;{'3.2x11", 12x3', 32,5,3, 1,2,0}, ;{'user defined ', 35,5,1, 1,0,0}}

MESSAGES <expA2> specifies the array of query and error messages. It may bechanged for another local human language. Per default <expA2> is set to:

{"LABEL F2:size F3:specify F5:fields F10:save ESC:quit", ;"CREATE", ;"MODIFY", ;"Size, remark :", ;"Label width (chars) :", ;"Label hight (lines) :", ;"Label columns :", ;"Lines between labels :", ;"Spaces between cols :", ;"Left margin (chars) :", ;"(F2) PgUp/PgDn: select size CursUp/CursDn: move ...", ;"Line ", ;"(F3) enter field or expression. CursUp/ ...", ;"(F5) PgUp/PgDn, CursUp/CursDn: move, scroll ...", ;"<->", ;"Wrong file name, press any key to return", ;"Check the correct entry: TYPE() not character, ...", ;"No LABEL data specified. Use F3 to specify, ESC ...", ;"F6:next dbf"}

Description:If the <file> does not exists, a new .lbl file is created, otherwise the available one ismodified.

CMD 213

If one or more databases are open in the current working area, the user may viewor alter the field names by pressing the F5/F6 key.

By executing the LABEL EDIT command, a full screen label design form appears:

CREATE LABEL persname.lbl F2:size F3:specify F5:fields F10:save ESC:quit┌F2─────────────────────────────────────────────┐┌F5:test2.dbf─────────┐│ Size, remark : 3.2x11", 12x3 <->││ NAME C 25 0 ││ Label width (chars) : 32 ││ FIRST C 20 0 ││ Label high (lines) : 5 ││ ZIP N 5 0 ││ Rows : 3 ││ CITY C 25 0 ││ Lines between labels : 1 ││ BIRTHDATE D 8 0 ││ Spaces between rows : 2 ││ EARNING N 8 2 ││ Left margin (chars) : 0 #3││ OK L 1 0 │└───────────────────────────────────────────────┘│ │╔F3═════════════════════════════════════════════╗│ │║ Line 1: trim(PERSONAL->NAME)+" "+FIRST+if<->║│ │║ Line 2: PERSONAL->TITLE <->║│ │║ Line 3: if(!empty(ADDRESS),ADDRESS,"") <->║│ │║ Line 4: PERSONAL->ZIP + TEST2->CITY <->║│ │║ Line 5: trim(CITY)+", "+STATE+str(ZIP) <->║│ │║ ║│ │║ ║│ │╚═══════════════════════════════════════════════╝└──────────F6:next dbf┘(F3) enter field or express. CursUp/CursDn: select,scroll ENTER: confirm

Pressing PgUp/PgDn in the F2 window, five pre-defined and one user defined labelforms may be selected and/or modified. The first line is used for user comment only,the rest specifies label size. To be compatible to the .lbl format, the label height maybe up to 16 lines, all other data may contain data in the range 0/1 to 999.

To specify or modify the data to be printed in each label, the F3 key is pressed.Now, moving the light bar up and down, the label line is selected. Enter <┘ tospecify/modify the expression (e.g. field, visible variable, function) in these labellines. Any expression may contain up to 60 characters. The contents of theseexpressions are evaluated by the LABEL FORM command using a macro operator,so the result should be a character, number, date or logical. When the linecommand is finished, press <┘, the expression will be validated. If the TYPE()results in unknown or illegal data, a warning appears; it can be safely ignored, ifsome databases, variables or functions containing the unknown data are not openor available yet.

Pressing F5 in the active F3 window, an entry of available database fields may beaccepted into the current expression entry. If more than one data÷ base is opened,the contents of the next one will be displayed using the F6 key.

To save the entry, press F10 key; to abort the LABEL EDIT command withoutsaving it, press the ESC key.

CMD 214

Example:Create and prints labels

USE test2USE personal INDEX name NEWIF !FILE(persname.lbl")

LABEL EDIT persname // create labelENDIFSEEK UPPER("smith")IF FOUND()

LABEL FORM personal TO PRINT ;FOR UPPER(TRIM(name)) = "SMITH" NOCONS

ENDIF


Compatibility:The command is available in FlagShip only. To create/modify labels in dBASE III+,use CREATE LABEL, in Clipper the program RL.EXE can be used.

Source:The file <FlagShip_dir>/system/labedit.prg is user modifiable, e.g. to support otherlanguages or to create context sensitive help.

Translation:__LABELEDIT ("file")

Related:LABEL FORM, REPORT EDIT

CMD 215

LABEL FORMSyntax:

LABEL FORM <file1>|(<expC1>)[<scope>][FOR <condition>][WHILE <condition>][TO PRINTER][TO FILE <file2>|(<expC2>) [ADDITIVE]][SAMPLE [<expA>]][NOCONSOLE]

Purpose:Displays labels defined in a .lbl file.

Arguments:<file1> is the file which holds the definition of the report. The default extension is.lbl.

Options:<scope> is the part of the current database file to traverse. The default scope isALL.

<condition> The FOR clause specifies that the set of records meeting the conditionwithin the given scope is to be displayed. The WHILE clause stops displaying labelswhen the first record not meeting the condition is reached.

TO PRINTER echoes output to a printer (spool file).

TO FILE <file2> echoes output to the specified file. If extension is not specified, .txtis assumed. The ADDITIVE clause stops from truncating <file2> if it exists. Seealso general command description.

NOCONSOLE suppresses the output to the screen, as when SET CONSOLE OFFwas set.

SAMPLE <expA>: If the SAMPLE clause is given, LABEL FORM displays labels asrows of asterisks, allowing the correct positioning of the printer paper. After eachrow of samples, the program prompts for more samples using the text of <expA> orthe default texts {"Do you want more samples?", "Yy"}, if <expA> is not given. Whenno more samples are requested, the printing of normal labels starts. For directprinter output, use SET PRINTER TO <device>.

Description:LABEL FORM displays the labels using the definitions stored in a .lbl file. The labelfile is created either by the FlagShip's command LABEL EDIT or by using the outputfrom dBASE command CREATE/MODIFY LABEL or the Clipper's utility RL.EXE.

CMD 216

Example:Prints labels for given condition

USE article INDEX nameSEEK "RISC Machines"IF FOUND()

SELECT 2USE AuthorsLABEL FORM authors TO PRINT FOR Id = Article->Id NOCONS

ENDIF


Compatibility:The ADDITIVE clause and the query text <expC3> in the SAMPLE clause issupported by FlagShip only.

Translation:__LABELFORM ("file1", .print., "file2", .noconsole., ;

{for}, {while}, next, rec, .rest., ;.sample., "expC3")

Related:LABEL EDIT, REPORT FORM, REPORT EDIT

CMD 217

LISTSyntax:

LIST [OFF] [<scope>] <expList>[FOR <condition>][WHILE <condition>][TO PRINTER][TO FILE <file>|(<expC>) [ADDITIVE]]

Purpose:Prints the result of one or more expressions for each processed record to theconsole and/or printer or file.

Arguments:<expList> is the list of values or expressions to be evaluated and displayed foreach record processed.

Options:<scope> is the part of the current database file to LIST. The default scope is ALL.

<condition> specifies additional FOR or/and WHILE filtering, see the generalcommand description.

OFF: Suppresses the display of record numbers.

TO PRINTER: echoes output to a printer file. To disable the screen output, use SETCONSOLE OFF.

TO FILE: echoes output (ADDITIVE) to the specified file. See also generalcommand description.

Description:LIST sends the results of the <expList> to screen (with optional echo to printerand/or file) in a tabular format, where each column is separated by a space. LIST issimilar to DISPLAY, except that its default scope is ALL, rather than NEXT 1.

Deleted records (see the DELETE command) are marked with a star (*). Deletedrecords are not displayed when SET DELETED is ON, and/or when the currentindex has "FOR !Deleted()" condition, and/or when the "FOR !Deleted()" clause wasspecified with the LIST command.

Example:Esc will interrupt the LIST output:

USE employeeLIST Lastname, Firstname, Birthdate FOR INKEY() <> 27


Compatibility:The ADDITIVE option is available in FlagShip only.

CMD 218

Translation:__DBLIST (.off., {exp1 [,exp2...]}, .T., {for}, {while},;

next, <rec>, .rest., .toPrint., "file")

Related:DISPLAY, SET CONSOLE, SET ALTERNATE, SET EXTRA, SET PRINTER,DBEVAL()

CMD 219

LOCALSyntax:

LOCAL <memvar> [:= <exp>] [, ...]Purpose:

Declares and optionally initializes LOCAL variables and arrays.

Arguments:<memvar> is the name of a FlagShip variable or array, to be declared in the(lexically scoped) LOCAL class. The name may be of any length, but only the first10 character are significant (see more LNG.2.6). Variable names in the FlagShiplanguage are not case sensitive.

If the <memvar> is followed by square brackets [ ], an array is created. The numberof elements for each array dimension can be specified as [dim1,dim2, ..,dimN] or[dim1][dim2][dimN]. The maximum number of dimensions and of the elements perdimension in FlagShip is 65535.

Options, Initializing:<exp> is any valid FlagShip expression including a literal (constant) array toinitialize the variable. If the initializer (:= <exp>) is not given, the variable (or allarray elements) will be set to NIL.

The LOCAL variable will be created and initialized on each entry into the programmodule (procedure or function).

Scope, Visibility:The scope, visibility and lifetime of LOCAL variables is always restricted to onefunction or procedure only. The variables are created and initialized upon entering aUDF or UDP (exactly when reaching the LOCAL statement) and are destroyedwhen returning from that module. If a procedure or UDF is invoked recursively (callsitself), each recursive activation creates a new set of local variables.

The local variables can be passed by value or by reference to other UDFs or UDPscalled at the same level. In code blocks, only LOCAL variables of the module wherethe block is declared are visible; see LNG.2.3.3.

LOCAL variable declarations hide all inherited PRIVATE, PARAMETERS, PUBLICor FIELD variables having the same name. If the variable name is already declaredin the same module by using another declarator (STATIC, GLOBAL, MEMVAR,FIELD), or by trying to re-declare such a variable from the file-wide scope, acompiler error is generated.

For more information, refer to the section LNG.2.6.

Description:LOCAL is a declaration statement that declares one or more variables or arrayslocal to the current procedure or user-defined function. A parameter list, following

CMD 220

the FUNCTION or PROCEDURE declaration, enclosed in parentheses, is treatedas a LOCAL declaration.

In FlagShip, the LOCAL declarator may be placed anywhere in the function body;the scope and visibility of the corresponding local for the compiler start from thisdeclaration.

Short notation: if the declarator is placed prior to the first FUNCTION orPROCEDURE statement and the compiler switch -na is used, the declaration (andinitialization) is placed at the beginning of every module in the .prg file. The scope,visibility and lifetime is equivalent to explicitly placed LOCAL declarations in eachone of these entities.

The variable names are known at compile-time only. Therefore, a LOCAL variablecan be evaluated by simple macros, but it cannot be used as a composed macro orwithin the macro string; see also LNG.2.10. Local variables cannot be SAVEd andRESTOREd from .mem files, nor released by CLEAR or RELEASE.

To determine the type of a LOCAL variable, only the standard functionVALTYPE(varname) can be used; since the TYPE("varname") tries to evaluate thestring using a macro and the variable is invisible during string evaluation.

Example:Declaration and initializing of LOCAL variables:

LOCAL var1 := 1, var2 := "xyz", var3 := date()LOCAL arr1 := {} // creates arr1[0]LOCAL arr2 := {0,date(),"test",.T.} // creates arr2[4]LOCAL arr3 := {{1,2},{3,4}} // creates arr3[2,2]LOCAL arr4[3,2], arr5[0] // creates arr4[3,2]LOCAL arr6 := {NIL, arr4, NIL} // non-symmetr. [3]

Example:Parameter passing to UDF (invoke it e.g.: a.out xxx):

LOCAL a1, a2 := 0PARAMETERS cmd1, cmd2? a1, a2, cmd1, cmd2 && NIL 0 xxx NILstart (cmd1, cmd2, a1, @a2)? a1, a2, cmd1, cmd2 && NIL 5 xxx NILquit

FUNCTION start (p1, p2, p3, p4)LOCAL xyz? p1, p2, p3, p4 && NIL 0 xxx NILp4 = 5xyz = p4 * 10RETURN NIL


CMD 221

Compatibility:The lexical scope is new in FS4, and is compatible to Clipper 5.x. Clipper has afixed order of the declaration and does not support the short notation (declarationon start of .prg).

Related:LOCAL..AS, STATIC, GLOBAL, PRIVATE, PUBLIC, FIELDS, DO, FUNCTION,TYPE(), VALTYPE()

CMD 222

LOCAL ... ASSyntax 1:

LOCAL <tvarList> [:= <exp>] AS <type>Syntax 2:

LOCAL_<C-type> <tvarList> [:= <expN>]Purpose:

Declares and initializes TYPED LOCAL variables.

Arguments:<tvarList> is a comma separated list specifying the names of variables, to bedeclared as TYPED LOCAL. The name may be of any length, but only the first 10characters are significant (see more LNG.2.6). The variable names in the FlagShiplanguage are not case sensitive; when accessing them from the #Cinlinestatements, use lowercase.

AS <type> is an alternate syntax for LOCAL_<type> where <type> is one of thekeywords (all of them may be abbreviated to four characters, except objects)

Local...AS <C-type>

C-like <type> DescriptionBYTE one byte char or unsigned num in the range 0..255DOUBLE double floating point, in the range +/- 4.94*10^-324 ... 1.79*10^308 with at

least 15 significant digits.DWORD unsigned long integer, in the range 0 ... 4 294 967 295.FLOAT floating point in the range +/- 1.40*10^-45... 3.40*10^38 with at least 7

significant digitsINT signed integer, in the range +/- 2 147 483 647 in Unix and Windows32 (or +/-

32 767 in DOS)LONG signed long integer, in the range +/- 2 147 483 647 .REAL4 equivalent to FLOATREAL8 equivalent to DOUBLESHORT signed short integer, in the range +/- 32 767WORD unsigned short integer, in the range 0 ... 65 535

The above C-like types do not create an overhead and are therefore much fasterthan usual variables, see additional description below.

The valid syntax is e.g.LOCAL rVar := 1.0, rVar2, rVar3 := 5.5 AS FLOATLOCAL_LONG iVar := 1, iVar2, iVar3 := 5

CMD 223

Local...AS <usual type>

Usual <type> The variable contains:ARRAY single or multidimensional arrayCHARACTER string (may include binary 0)CODEBLOCK address of a code blockDATE date values in the range 1/1/1 to 12/31/9999INTVAR long integer numbers in the LONG range.LOGICAL logical true/false statusNUMERIC floating point numbers if the DOUBLE range.OBJECT any object variable. It does not specify the object and does therefore not

force the compile-time address resolution.PSZ same as CHARACTERSCREEN screen contents from SAVESCREEN()SPECIAL user defined, eg. pointer to a C structureSTRING same as CHARACTERUSUAL any usual variable type of this table

The above usual variable types allow to check assignments already at compile-time(except for the USUAL type), instead of causing run-time error later.

The valid syntax is e.g.LOCAL getList := {}, aVar := {1,2,{3,4}} AS ARRAYLOCAL iVar1 := 1, iVar2, iVar3 := 5.2 AS NUMERIC

Local...AS <object type>

Object <type> Description, the variable containsGET Object variable of the Get classTBROWSE Object variable of the TBrowse classTBCOLUMN Object variable of the TBcolumn classERROR Object variable of the Error classDATASERVER Object variable of the DataServer classDBSERVER Object variable of the DBserver or DbfIdx class<UserClass> Object variable of the user defined class

The above object types (along with class declaration or prototyping) allow addressresolving already at compile-time, which speeds-up execution significantly.

The valid syntax is e.g.LOCAL getElem AS GETLOCAL oMyBrow AS TBROWSELOCAL oDbf1, oDbf2 AS DBFIDX

Options, Initializing:<exp> is any valid expression returning a value of the same <type> (or a numberfor C-like types) to initialize the variable at declaration time.

If the initializer (:= <exp>) is not given, the TYPED LOCAL C-like variables will beinitialized with zero, all others to NIL or the empty type, respectively.

CMD 224

The TYPED LOCAL variable will be created and initialized on every entry into theprogram module (procedure or function), just like a lexical, untyped LOCALvariable.

Scope, Visibility:The scope, visibility and lifetime of TYPED LOCAL variables is identical to theusual, untyped lexical LOCAL variables. The only difference is the fixed storagetype of C-like variables, which allows faster runtime access and their direct use in#Cinline statements, see below.

The variables are created and initialized upon entering a UDF, UDP or method(exactly when reaching the LOCAL..AS statement) and are destroyed whenreturning from that module. If a procedure or UDF is invoked recursively (callsitself), each recursive activation creates a new set of local variables.

TYPED LOCAL C-type variables can also be passed by value to other UDFs orUDPs called at the same level; passing them by reference is not supported. Theymay be used in code blocks with the same restriction as LOCAL vars.

Because TYPED variables have the same scope as lexical variables (LOCAL,STATIC), they hide all inherited PRIVATE, PARAMETERS, PUBLIC or FIELDvariables with the same name.

For more information, refer to the section LNG.2.6.

Description:LOCAL..AS is a declaration statement that declares TYPED lexical variables, verysimilar to untyped LOCAL variables. The advantages are:

•The type and storage range is fixed during compile-time and cannot be changedat runtime.

•The correct usage is already checked at compile time, which avoids possible run-time errors later during the execution.

Additional advantages of typed Object variables:

•The use of typed OBJECT variables increases program execution speedsignificantly, refer to chapter LNG.2.11.6 for additional information.

Notes about and restrictions of C-like types (BYTE, INT, LONG, DOUBLE etc):

•Since additional runtime type checking of C-like types may be omitted, their useresults in faster program execution (up to 5 times), compared to usual typed oruntyped variables. They are preferably used for large loops, calculations etc.

•The C-like typed variables can also be accessed directly in #Cinline statements,by giving the name (up to 10 significant chars) in lowercase.

•The variables occupy only 1, 4 or 8 bytes, compared to approx. 28 bytes forstandard FlagShip variables.

CMD 225

•The programmer has to consider the maximum storage range of the variable's<type>. Otherwise, the resulting value will be truncated to the (lowest) availablebytes.

•If the C-like typed variables are intermixed with usual untyped variables within anoperation or command, they will be internally, temporarily converted to usualNUMERIC (or INTVAR) ones. Therefore, use only C-typed variables or constantswithin the e.g. FOR... declaration to maintain the speed advantage.

•C-like typed variables will always be passed to a standard function, UDF andUDP by value, regardless of the calling convention used (@ prefix or using theDO...WITH procedure call). The argument is automatically converted to a usualNUMERIC (or INTVAR) variable and received by the UDF as such. The sameconversion occurs when assigning them to an array element.

•These variables cannot be used for any macro evaluation, as CLASS instances,and in code blocks. The function VALTYPE(varname) will return "N" (or "I"depending on FS_SET("intvar")), the TYPE("varname") function cannot be used.

The visibility is local to the current procedure or user-defined function. In FlagShip,the LOCAL..AS declarator may be placed anywhere within the function body; thescope and visibility of the corresponding local for the compiler starts from thisdeclaration.

Short notation:If the declarator is placed prior to the first FUNCTION or PROCEDURE statementand the compiler switch -na is used, the declaration (and initialization) is placed atthe beginning of every module in the .prg file. The scope, visibility and lifetime isequivalent to an explicitly placed LOCAL..AS declarations in each one of theseentities.

Example:This example shows the usage and speed advantages of C-typed variables(remaining compatible to Clipper 5):

*** file test.prg ***PARAMETERS cmd1, cmd2#ifndef FlagShip // Clipper redefinition

#define LOCAL_INT LOCAL // not needed, if the#define LOCAL_DOUBLE LOCAL // clipper switch#define SECONDSCPU SECONDS // Clipper test /uSTD.FH

#endif // is used#define MAXLOOP 100000start (cmd1, cmd2) // passes cmd-line paramQUIT

FUNCTION start (cmd1, cmd2)LOCAL_INT li_loopLOCAL timestart := SECONDSCPU(), loc_loopLOCAL_DOUBLE ld_resulting? "Input param.:", cmd1, cmd2

CMD 226

/* --- standard LOCAL variables --- */

FOR loc_loop = 1 to MAXLOOP // 100.000 timesld_resulting = loc_loop / 3

NEXT? "standard LOCAL: ", ;SECONDSCPU() - timestart, ld_resulting // ca. 4.75 sec.

/* --- typed LOCAL variables ------ */timestart = SECONDSCPU()FOR li_loop = 1 to MAXLOOP

ld_resulting = li_loop / 3.0NEXT? "typed LOCAL: ", ;SECONDSCPU() - timestart, ld_resulting // ca. 0.25sec.

/* --- The same using inline C code-- */

#ifdef FlagShiptimestart = SECONDSCPU()#Cinline#define MAXLOOP 100000 /* #define for C Code */for (li_loop = 1; li_loop <= MAXLOOP; li_loop++)

ld_resulti = li_loop / 3.0; /* use 10 chars only! */#endCinline? "Inline C: ", ;SECONDSCPU() - timestart, ld_resulting // ca. 0.18 sec.

#endif

RETURN NIL*** eof test.prg ***

Example:This example shows the usage of typed variables and objects. See also chapterLNG.2.11.5 and LNG.2.11.6 for additional examples:

LOCAL oDbf AS DBSERVERLOCAL Getsys := {} AS GET // local, nested GETLOCAL iIntVar := 0, iCount AS IntVarLOCAL cText := space(20) AS CHARACTERLOCAL dMyDate := date() AS DATELOCAL lOk := .F., lResult := .T. AS LOGICAL


Compatibility:The C-like types are available in FS only. CA/VO uses the same syntax (1). Toremain compatibility to Clipper 5, use syntax 2 and #defines like:

#ifndef FlagShip#define LOCAL_BYTE LOCAL#define LOCAL_LONG LOCAL#define LOCAL_DOUBLE LOCAL

#endif

CMD 227

The usual types and object types are compatible to CA/VO (except IntVar), but notavailable in Clipper. For Clipper 5, you may specify e.g.

#ifndef FlagShip#command LOCAL <xx,...> AS <yy> => LOCAL <xx>

#endif

Related:LOCAL, STATIC, GLOBAL, PRIVATE, PUBLIC, CLASS, FIELDS, PROTOTYPE,DO, FUNCTION, TYPE(), VALTYPE(), FS_SET("intvar"), INT2NUM(), NUM2INT(),#Cinline, #define, #ifdef

CMD 228

LOCATE ... FORSyntax:

LOCATE [<scope>] FOR <condition>[WHILE <condition>]

Purpose:Searches the working area for the first record meeting the specified condition.

Arguments:FOR <condition> specifies the next record to LOCATE within the given scope.

Options:<scope> is the portion of the current database file in which to perform the LOCATE.The default scope is ALL. The <scope> has no effect on CONTINUE.

WHILE <condition> specifies the set of records to be searched. These are therecords meeting the condition. The WHILE condition is operational only until the firstmatch is found, it has no effect on CONTINUE.

Description:LOCATE searches the current database file sequentially from the beginning of thescope for the first record matching the condition. The search is terminated when amatch is found, or the end of LOCATE scope is reached. After a successfulLOCATE, FOUND() returns .T. and the matching record becomes the currentrecord. Otherwise, FOUND() returns .F. and the record pointer is set to EOF or thefirst record outside the scope.

If you frequently search for a database key, SEEK on index will be the moreeffective, much faster alternative. If an index for a part of the <condition> isavailable, use SEEK and LOCATE...REST to skip unneeded records.

The LOCATE search can be initiated later by means of CONTINUE, which utilizesthe FOR condition only. For a subsequent searching scope or WHILE, use SKIPand then LOCATE REST WHILE <condition> instead of CONTINUE.

Each working area can have its own LOCATE condition, which remains active untilyou execute another LOCATE command in that working area or close the database.

Example:USE employee? RECCOUNT() && 98LOCATE FOR Lastname = "Clifton"? FOUND(), EOF(), RECNO() && .T. .F. 43CONTINUE? FOUND(), EOF(), RECNO() && .T. .F. 61CONTINUE? FOUND(), EOF(), RECNO() && .F. .T. 99LOCATE FOR Lastname = "Batman"? FOUND(), EOF(), RECNO() && .T. .F. 55CONTINUE? FOUND(), EOF(), RECNO() && .F. .T. 99

CMD 229

Example:USE address INDEX nameSEEK UPPER("smith")DO WHILE FOUND()

? name, address, zip, citySKIPLOCATE REST FOR zipcode >= 1234 ;

WHILE SUBSTR(UPPER(name),1,5) = "SMITH"ENDDO


Translation:__DBLOCATE ({for}, {while}, next, rec, .rest.)

Related:CONTINUE, FIND, SEEK, FOUND(), oRdd:LOcate(), oRdd:Locate(),oRdd:GetLocate()

CMD 230

MEMVARSyntax:

MEMVAR <varList>Purpose:

Declares a list of identifiers to be used as PRIVATE and PUBLIC memory variablesor arrays whenever encountered.

Arguments:<varList> is a comma separated list of visible or declared PRIVATE and PUBLICmemory variables or arrays.

Scope:The scope of the MEMVAR declaration depends on the location of the declarationstatement:

•UDF wide scope: if the declaration is given within the procedure or function body,the scope is the UDF or UDP only.

•File-wide scope: if the declaration is placed prior to the first FUNCTION orPROCEDURE statement and the compiler switch -na is used, the scope is theentire .prg file (all UDFs or UDPs within these file).

Description:MEMVAR is a declaration statement that causes the compiler to resolve referencesto variables specified without an explicit alias by implicitly assuming the memoryalias MEMVAR-> . Like all declaration statements, it has no effect on referencesmade within macro expressions or variables.

The MEMVAR statement neither creates the variables nor verifies their existence.The variables may already exist (e.g. on a higher level) or will be created in theprogram body as autoPRIVATE or using the declarators PRIVATE, PARAMETERS,DECLARE or PUBLIC.

There is no fixed declaration order in FlagShip. The compiler starts the implicitaliasing from this declaration on.

In conjunction with the compiler switch -w (and e.g. also the FIELD declarator),unknown or ambiguous variable references will be printed (as warnings) at compiletime.

CMD 231

Example:With the compiler switch -w, a warning for "name" and "first" will be printed (mainmodule and "first" in test2). Note the preference of dbf fields when accessing, or thememory variables when assigning the ambiguous variable names.

PRIVATE nameSELECT 5USE addressfirst := "Peter" // autoPRIVATE? name, first // Smith JohnDO test1DO test2RETURN

PROCEDURE test1MEMVAR name, firstname := "Miller" // = assignment? name, first // Miller Peter? address->name, address->first // Smith JohnRETURN

PROCEDURE test2FIELD name? name, first // Smith Johnname := "NewMiller" // = REPLACE? name, first // NewMiller John? address->name, M->first // NewMiller PeterRETURN


Compatibility:The MEMVAR declarator is new in FS4. This statement is compatible to C5, whichhas a fixed order of declaration statements (prior to the first executable statement).

Related:FIELD, PRIVATE, DECLARE, PUBLIC, PARAMETERS, LOCAL, STATIC

CMD 232

MENU TOSyntax:

MENU TO <memvar>Purpose:

Executes a light bar menu on currently defined prompts.

Arguments:<memvar> is a memory variable where the choice will be placed after exiting fromthe menu. If the variable does not exist or is not visible, a new autoPRIVATE one iscreated.

Description:Before executing a MENU TO lightbar menu, the item texts, positions on the screenand the order in which the lightbar will navigate through them need to be specifiedusing the @...PROMPT command. Messages associated with PROMPTs, and theirpositions on the screen (SET MESSAGE) can also be defined.

Menu items and help texts are painted in the current "standard" color pair, thehighlighted menu item appears in the "enhanced" color (see SET COLOR).

If the <memvar> contains a numeric value, the light bar is set to the correspondingitem, or otherwise on the first one. MENU TO will then begin the selection process.To navigate through the PROMPTs, use the arrow keys to move the light bar to thenext or previous menu item and display the associated (@...PROMPT...)MESSAGE, if any.

With SET WRAP ON, the down-arrow key at the last prompt moves the lightbar tothe first menu choice. The same happens with the up-arrow key on the first choice.

By pressing the first menu character, the light bar is positioned on the first or nextitem, which starts with the pressed character, if any. If SET CONFIRM is OFF (thedefault) and the item is found, the choice is terminated and the current item positionis stored in <memvar>. With SET CONFIRM ON, the user has to confirm the choiceby pressing the enter key to leave the menu. You also may specify hot-key(accelerator) by prefacing the selected character by "&", "\&" or "\<", see detailsin @..PROMPT. This hotkey has then preference over the search by first character.

CMD 233

The following navigation keys can be used:

Key DescriptionLeftarrow <- (Cursor left) Up one PROMPTRightarrow -> (Cursor right) Down one PROMPTUparrow (Cursor up) Up one PROMPTDownarrow (Cursor down) Down one PROMPTHome First menu itemEnd Last menu itemEnter, Return Exit, return PROMPT positionPgUp, PgDn Exit, return PROMPT positionEsc Abort, return zeroSpace Select or search (*) (**)Hot-key Go to corresp. item (**)First menu character First/next PROMPT beginning with the same letter (**)Left-mouse double-click Select item in GUI (**)Left-mouse click Select item in GUI (**)

(*) The space key usually handles same as Enter, i.e. it selects the current item.You may change this behavior by assigning .F. to the global variable_aGlobSetting[GSET_L_PROMPTSPACESEL], it default is .T. When space selectis enabled, the search for leading space in text is disabled.

(**) By this selection, the choice is terminated and the currently selected itemposition is stored in <memvar> when SET CONFIRM is OFF (the default).Otherwise, with SET CONFIRM ON, the user has to press the enter key to leavethe menu.

Redirection: When one of the navigation key is redirected via SET KEY orON KEY or SET FUNCTION, the redirection is executed instead of the defaultbehavior. The ESC key makes an exception: if ESC is redirected, and you don'twant to terminate MENU TO, pass anything else to LastKey() buffer e.g.KEYBOARD "x" ; Inkey() within the redirected UDF; otherwise MENU TO isterminated after returning from the redirected UDF.

Nesting: The maximum number of PROMPTs per MENU TO is unlimited inFlagShip. MENU TO may be nested to any level when LOCAL or PRIVATE_oPrompt variable is declared to hold the nested PROMPTs, see details in [email protected] command description.

If you wish to clear all @..PROMPT items without invoking MENU TO, use theCLEAR MENU command or _oPrompt:Clear()

The Prompt class is used internally for @..PROMPT items and MENU TOprocessing, the object is hold in _oPrompt. See also menuclass.fh

CMD 234

Tuning: In GUI mode, you also may use Left/Middle/Right Mouse Buttonfor the selection and wheel for positioning. You may enable/disable this action byassigning

_aGlobSetting[GSET_G_L_MENUTO_LMB ] := .T. // LMB, default on_aGlobSetting[GSET_G_L_MENUTO_MMB ] := .T. // MMB, default on_aGlobSetting[GSET_G_L_MENUTO_RMB ] := .T. // RMB, default on_aGlobSetting[GSET_G_L_MENUTO_DLMB ] := .T. // dblLMB, default on_aGlobSetting[GSET_G_L_MENUTO_DMMB ] := .F. // dblMMB, default off_aGlobSetting[GSET_G_L_MENUTO_DRMB ] := .F. // dblRMB, default off_aGlobSetting[GSET_G_L_MENUTO_WHEEL] := .T. // wheel, default on

where the defaults are set in <FlagShip_dir>/system/initio.prg API

Example:LOCAL choice := 3 && light bar on "Append"SET WRAP ON@ 10,0 PROMPT "Help"@ 11,0 PROMPT "Edit"@ 12,0 PROMPT "Append"@ 13,0 PROMPT "Delete"@ 15,0 PROMPT "Quit"MENU TO choiceSET WRAP OFFIF choice = 0 && ESC pressed

RETURNENDIF

Example:see more examples in @...PROMPT


Compatibility:The SET CONFIRM choice and the positioning to the first/next item is available inFlagShip only. Clipper supports only 32 PROMPTs per MENU TO.

Translation:memvar := __MENUTO ({|par| if(PCOUNT() == 0, ;

memvar, memvar := par)}, "memvar")

Related:@...PROMPT, CLEAR MENU, SET MESSAGE, SET WRAP, ACHOICE(),DBEDIT()

CMD 235

METHODSyntax 1:

ACCESS [METHOD] <methName> [( )]CLASS <className> [AS <type>]

Syntax 2:ASSIGN [METHOD] <methName> (<par>)

CLASS <className> [AS <type>]Syntax 3:

[PROTECT] METHOD <methName> ([<paramList>])CLASS <className> [AS <type>]

Syntax 4:PROTOTYPE ACCESS [METHOD] <methName> [()]

CLASS <className> [AS <type>]PROTOTYPE ASSIGN [METHOD] <methName> (<par>)

CLASS <className> [AS <type>]PROTOTYPE [PROTECT] METHOD

<methName> [(<paramList>)]CLASS <className> [AS <type>]

Purpose:Declares an access, assign or usual method, associated to the specified class.

Arguments:<methName> is the declared name of the access, assign or usual method. Thename may be of any length; only the first 10 characters are significant for accessand assign, but significant in the full length for the usual method. Upper or lowercase makes no difference. The names can contain any combination of charactersA..Z, numbers, or underscores. The METHOD name must be unique within theclass, but does not need to be unique within the application. The ACCESS orASSIGN names may hide (or make accessible) same named instances of the sameclass, except EXPORTed ones.

<className> specifies the CLASS to which the access, assign or usual methodbelongs. The class has to be declared or prototyped already.

<par> [AS <type>] (in syntax 2, ASSIGN) specifies the value which should beassigned by the obj:methName := par syntax. It is passed to the ASSIGN methodas a local variable. Optionally, you may give the variable a usual or an object<type> according to LOCAL..AS. The typed parameter, together with prototyping,allows additional type checking at compile and run-time.

<paramList> specifies optional parameters passed to the METHOD by theobj:methName(par1,par2...) syntax, same as parameters of a user defined

CMD 236

FUNCTION. Optionally, you may give any parameter a usual or an object <type>according to LOCAL..AS by using the AS <type> syntax.

PROTECT METHOD is a usual METHOD, visible for the class entities (Access,Assign and Methods) only, but hidden from the usual application. It is used mainlyas a class internal UDF, similar to a STATIC function. The important difference is,that the class instances are visible also within the PROTECT METHOD body. Youwould otherwise have to pass all the required instances via a parameter list to ausual (or static) UDF. Additionally, the protect method is available also for methodsof the same class specified in other files.

PROTOTYPE (using syntax 4) informs the compiler about the CLASS entity,specified elsewhere later in the application. Knowing the method name, theFlagShip compiler is able to resolve the addresses during compile-time (earlybinding). Otherwise, the method address will be resolved during the run-time phase(late binding), see also chapter LNG.2.11.6. You will not need to prototype amethod declared formerly in the same source, but should prototype methods used,but specified later. See also the PROTOTYPE statement in section CMD.

Description:A METHOD is very similar to a usual user defined function (UDF). The only visibledifference is, that the name is associated to the specified class. Therefore, it mayonly be invoked together with the object name and the send operator, e.g.oMyObj:MyMethod() as opposed to invoking a usual UDF by the name (andparentheses) only. An instance of any type and/or an access/assign method of thesame name may be specified in the same class. A PROTECT METHOD is thesame, but visible within the class entities only.

The ACCESS method is a special kind of method, which receives no parameters. Itacts as a "read-only virtual export instance". Therefore, the access method isinvoked from the application in the same way as an exported instance, e.g.[resultVar :=] oMyObj:MyVar. A same named instance (of any type exceptEXPORT) may, but need not be specified in the CLASS declaration. A same namedASSIGN and usual METHOD may coexist.

The ASSIGN method is also a special kind of method, whereby the assigned valueis passed as a local parameter. The ASSIGN acts as a "write-only virtual exportinstance with optional validation". Therefore, the assign method is invoked from theapplication in the same way as an exported instance, e.g. oMyObj:MyVar :=assignedValue. A same named instance (of any type except EXPORT) may, butneed not be specified in the CLASS declaration. A same named ACCESS andusual METHOD may coexist.

Method programming:The ACCESS, ASSIGN and METHOD are programmed in the same way, as usualUDFs. The method starts with the declarator according to syntax 1, 2 or 3, which issimilar to the FUNCTION declarator of a UDF. The method body includes anynumber of valid statements and ends with the next UDF, UDP or method declaratoror by end-of- file. The ACCESS method should always return the (virtual) objectinstance value (or an empty value on error), while the ASSIGN and METHOD may

CMD 237

return any value. Usually, ASSIGN also returns the newly set (virtual) objectinstance value.

Within the ACCESS, ASSIGN and METHOD program body, you have direct accessto all class instances. Their visibility for the method is similar to "private" variables,they may therefore be hidden by same named LOCAL or STATIC variables. If so,you may explicitly access the instance by using the SELF: keyword. If a samenamed instance and PRIVATE or PUBLIC variable exists, the instance is preferred.Generally, you may always use the SELF: keyword when referring to any instancevariable of the same class.

Within the method body, the ACCESS and ASSIGN method is invoked instead ofthe instance, if such an assign or access method exists, and if it overloads a usualINSTANCE variable. All other instance types (EXPORT, PROTECT, HIDDEN) areaccessed directly. Of course, in the ACCESS and ASSIGN body, the same namedinstance variable is accessed directly, regardless of its type.

In the access, assign and method body, invoking METHODs of the same class isalways performed with the SELF: keyword. If the class is inherited from asuperclass, and a local (redefined) method exists, the SELF: keyword calls thelocally redefined method, while SUPER: invokes the original, inherited one.

Example 1:See examples in the INSTANCE description, demonstrating the declaration of theCLASS and its methods in the same, or in different source files. See also the<FlagShip_dir>/system/smallrdd/smallrdd.prg file for a practical example of theOOP programming.

Example 2:Appends a new assign method to the standard GET class for a controlledmodification of the get:BUFFER. Note: the prototypes of the GET class are includedin the "getclass.fh" or the general "stdclass.fh" file, which may be #included in yoursource (or automatically from the "std.fh" preprocessor file).

#include "getclass.fh"ASSIGN FillBuff(cValue) CLASS get AS characterif valtype(cValue) == "C"

cValue := PADR(cValue, LEN(self:buffer))self:buffer := cValue // the SELF: keyword is not

endif // required here, but makesreturn self:buffer // the code better readable

CMD 238

Example 3:Redefines some methods of the standard DBFIDX class. Note: the prototypes of theDBSERVER class are included in the "dbfidx.fh" or the general "stdclass.fh" file.The 'MyCrea' method is not visible for the rest of the application.

#include "dbfidx.fh"CLASS DbfIdxExcl INHERIT DbfIdx // my DBserver RDD

PROTECT METHOD MyCrea(p1 AS char) CLASS DbfIdxExcl AS logicif ALERT("Database "+p1+" does not exist. Create ?", ;

{"No", "Yes"}) == 2if ! MyCreateUdf (p1, self:info(DBI_FULLPATH)) // UDF

return .F.endif

endifreturn .T.

METHOD Init(p1,p2,p3,p4,p5,p5) CLASS DbfIdxExclWHILE .T.super:INIT (p1,.F.,p3,p4,p5,p6) // invoke dbfidx:init()if self:used .or. file(self:info(DBI_FULLPATH))

exitendifif self:MyCrea(p1) // protected method

exitendif

ENDDOreturn self // returns object

ACCESS Shared CLASS DbfIdxExcl // local redefinitionreturn .F.

STATIC FUNCTION MyCreateUdf (cName, cFullName)// create the dbf, e.g. by using dbcreate()return .T.

FUNCTION myApplic () // main program entryLOCAL oMyDbf := DbfIdxExcl {"myData"} AS DbfIdxExclif ! oMyDbf:Used? "cannot open myData.dbf exclusive"QUIT

Endif // process, e.g.? EOF(), oMyDbf:EOF? ALIAS(), oMyDbf:ALIAS


Compatibility:Not available in Clipper, but compatible to CA/VO. The PROTOTYPE clause isavailable in FlagShip only (managed by the repository in VO). PROTECTedMETHODs are available in FlagShip only.

Related:INSTANCE, PROTOTYPE, LOCAL..AS, (OBJ)DBSERVER, (LNG)2.11

CMD 239

NOTESyntax:

NOTE [<text>]or:

* [<text>]Purpose:

Puts a comment at the beginning of a line.

Arguments:<text> is a character string ending with a new line.

Description:The NOTE command is equivalent to the asterisk "*" comment. NOTE and * atbeginning of the source line (leading spaces and TABs are not significant) marksthe whole line as a (full-line) comment.

For more program comments, see (CMD) * Comments.

Example:************** Comment **************a = b && Inline comment,a = b + ; && usable also for

c + d && continued statementNOTE That is an comment line,NOTE same as these* or these line.


Related:* // && /*..*/

CMD 240

ON ANY KEYON KEYSyntax 1:

ON KEY [DO <udfName>]ON ANY KEY [DO <udfName>]

Syntax 2:ON KEY CLEAR

Syntax 3:ON KEY <expN1> [EVAL <expB2>]

Syntax 4:ON KEY <expN1> [DO <udfName> [WITH param]]

Purpose:ON KEY is very similar to SET KEY with some additional features.

Arguments:<expN1> is numeric key value corresponding to Inkey()

<udfName> is name of any standard or user defined function

<expB2> is a code block to be evaluated

Description:Syntax 1 set/clear action performed on any key press. It is a special case of syntax4 and equivalent to ON KEY 0 [DO ...] or the invocation of OnKey(0, {|| udfName() })

Syntax 2 clear all previously set ON KEY actions and is same as OnKey(NIL, NIL)

Syntax 3 set/clear a codeblock, evaluated on key-press of a specific key, same asSetKey(expN1, [expB2]) or to the invocation of OnKey(expN1, [expB2])

Syntax 4 is similar to syntax 3 and equivalent to SET KEY nKey [TO udf]. In fact,the DO udfName WITH ... clause is translated by FlagShip preprocessor toOnKey(expN1, {|| udfName(param1,param2,param3,...)})


Compatibility:New in FS5, compatible to FoxPro

Related:OnKey(), SET KEY, SetKey(), PUSH KEY, POP KEY

CMD 241

ON ERRORSyntax:

ON ERROR [DO]ON ERROR [DO <udfName> [WITH param]]

Purpose:ON ERROR is provided mainly for FoxPro compatibility

Description:Set/clear action executed on RTE, same as ErrorBlock(...). In fact, the command"ON ERROR [DO]" is translated by the FlagShip preprocessor to

if type("_OnError") == "B"ErrorBlock(_OnError)_OnError := NIL_OnErrObj := NIL

endif

and the command "ON ERROR [DO <udfName> [WITH param]]" creates a publicvariable with assigned ErrorBlock() to it:

PUBLIC _OnErrObj // holds the error objectPUBLIC _OnError := ErrorBlock({|_err| _OnErrObj := _err, ;

udfName(par1,par2..) } )

When compiled with the -fox switch, also FoxPro's functions Error() and Message()are available, see foxpro_api.prg

Example: compile with -fox switch for FoxPro's functions/* force RTE 501 on failure in USE... and SET INDEX...* for FoxPro compatibility*/_aGlobSetting[GSET_L_DBUSEAREA_ERR ] := .T. // default = .F._aGlobSetting[GSET_L_DBSETINDEX_ERR] := .T. // default = .F.

set font "courier"on error do errhand // activate own error handlerdo testUdfon error // de-activate own error handler?wait "now standard error will be raised..."x = yz // error, variable 'yz' n/await

procedure testUdfuse unknown index unknown // RTE 501, see above settingsx = abc // error, variable 'abc' n/areturn

CMD 242

procedure errhand // own error handler? "*** FoxPro error =", error()? " FlagShip error=", if(type("_OnErrObj") == "O", ;

_OnErrObj:GenCode, 0)? " message() =", message() // default? " message() =", strtran(message(), ";", " ") // no NL? " message(1)=", message(1)? " message(2)=", message(2) // extended, n/a in Fox? " sys(16) =", sys(16)wait "(in " + procname() + ") press any key..."/* If ON ERROR ... is active, and (in this example) other* than FoxPro error 1 occurred, display error by standard* FlagShip popup, then select this own error handler back*/if type("_OnError") == "B" .and. type("_OnErrObj") == "O"

if error() <> 1local bSaveErr := ErrorBlock(_OnError) // save_rt_error(_OnErrObj:GenCode, _OnErrObj:Description)ErrorBlock(bSaveErr) // restore

endifendifreturn



Related:OnKey(), ErrorBlock()

CMD 243

ON ESCAPESyntax:

ON ESCAPE [DO <udfName> [WITH param]]Purpose:

ON ESCAPE is provided mainly for FoxPro compatibility

Description:Set/clear a UDF, evaluated on ESC key press. It is in fact a special case of "ONKEY 27 [DO <udfName> [WITH param]]" or of "SET KEY 27 TO <udfName>" and ishence evaluated same as

OnKey (27, {|a,b,c,d| udfName (par1, par2, ...) })



Related:ON KEY, OnKey(), SetKey(), PUSH KEY, POP KEY

CMD 244

PACKSyntax:

PACKPurpose:

Removes all records marked for deletion from the current database (and theassociated .dbt) file.

Description:PACK physically removes all records marked for deletion, REINDEXes all openindices in that working area, and restores the space previously occupied byremoved records and index keys.

PACK only acts on the selected database file and its associated memo-files, thecurrently set RELATIONs and FILTERs are ignored.

PACK does not create any backup files (except during its execution); so if one isrequired, COPY TO should be invoked prior to PACK. After the command isfinished (including REINDEXing of all open indices), the record pointer is reset tothe first logical record and the original FILTER and RELATION are restored.

Performance:On large databases, PACK can be a time-consuming process, very uncomfortablein a multiuser environment. In such a case, the PACK can be easily omitted usingthe records already deleted for new ones; see example below.

Multiuser:PACK requires an exclusively opened database using SET EXCLUSIVE ON orUSE...EXCLUSIVE. See also LNG.4.8.

Example:USE employeeCOUNT FOR Hair_len > 30 .AND. Sex = "M" TO Freaks? RECCOUNT(), Freaks && 100 7DELETE FOR Hair_len > 30 .AND. Sex = "M"? RECCOUNT() && 100PACK? RECCOUNT() && 93

Example:Omitting the PACK by re-using the deleted records. All deleted records arecontained in the index at the logical top. Then, use MYDELETE() instead ofDELETE + PACK and MYAPPEND() instead of APPEND BLANK.

USE addressWHILE NETERR()

INKEY (2) // if busy,USE address // retry

END

CMD 245

SET INDEX TO name, zipSET DELETED ONGOTO TOP // first valid datachoice := my_menu()IF choice == 1

MYDELETE() // deleting requiredELSEIF choice == 2

MYAPPEND() // appending requiredREPLACE name with xName, zip with xZipUNLOCK

ENDIF:

FUNCTION MYDELETE() // repl. DELETE+PACKWHILE !RLOCK(); END // wait for lockDELETEREPLACE name with " ", zip with 0 // reset index orderUNLOCKRETURN

FUNCTION MYAPPEND() // repl. APPEND BLANKSET DELETED OFFGOTO TOPif DELETED() // deleted available?

WHILE !RLOCK(); END // yes, remove theRECALL // "delete" mark

elseAPPEND BLANK // no, append new oneWHILE NETERR(); APPEND BLANK; END

end** UNLOCK // record remains locked, simil.to APPE BLANKSET DELETED ONRETURN // RLOCK() is set


Compatibility:FlagShip also PACKs the associated memo-files (.dbt), whilst Clipper packs the .dbffile only.

Translation:__DBPACK()

Related:DELETE, RECALL, REINDEX, SET EXCLUSIVE, SET DELETED, USE, ZAP,DELETED(), FLOCK(), RLOCK, oRdd:PACK(), ISDBEXCL()

CMD 246

PARAMETERSSyntax:

PARAMETERS <paramList>Purpose:

Specifies PRIVATE memory variables as FUNCTION or PROCEDURE parameterswhich will receive the arguments of the call (passed by value or by reference).

Arguments:<paramList> is a comma separated list of receiving variables. The variables will becreated in the PRIVATE class. The number of receiving variables does not have tomatch the number of arguments passed by the calling procedure UDP or user-defined function UDF.

Description:The values or references actually passed by a call of UDP or UDF are referred to asarguments. The variables in the UDP or UDF, which receives them, are namedparameters. Receiving parameters can be created by using the PARAMETERScommand or alternatively as LOCAL variables (named formal parameters) ifspecified as a part of the PROCEDURE or FUNCTION declaration statement (i.e.included in parentheses).

When a PARAMETERS statement executes, all variables in the parameter list arecreated as PRIVATE class variables and all previous public or private variables withthe same names are hidden until the current procedure or UDF terminates. Thescope, visibility and lifetime of such variables is equivalent to those of the PRIVATEdeclaration.

In FlagShip, the number of arguments and parameters do not have to match. Ifthere are more arguments than parameters, the rest of the arguments are ignored.Conversely, when there are more parameters than arguments actually passed, therest of the parameters remain undefined (contain NIL). To find out how manyarguments were passed, use PCOUNT(). If some arguments are omitted, thecorresponding parameters become NIL.

Arguments can be passed in one of two ways: by value or by reference. To pass aparameter by value means that its value is copied to the receiving variable. When aparameter is passed by reference, the argument is just given the parameter nameand the parameter contains this variable. In the former case, the value of theargument cannot be altered in the procedure, while in the latter, all changes to theparameter also happen to the corresponding argument.

When parameters are passed to procedures using DO.. ..WITH, memory variablesand arrays are passed by reference, while array elements, expressions, fields andmemory variables enclosed in round parenthesis ( ) are passed by value. Whenparameters are passed to user defined functions (UDFs), all parameters except forarrays are passed by value. Memory variables however, can be passed by

CMD 247

reference if preceded by @. Parameters from the UNIX shell may also be passed tothe main program module (e.g.: a.out par1 par2).

For more information, see section LNG.2.3.2.

Example:* call it e.g.: a.out -or- a.out xxx yyy zzz -etc-PARAMETERS cmd1, cmd2, cmd3 && arguments from UNIXFOR i = 1 to PCOUNT()

ii = LTRIM(STR(i))? "Command-Line-Parameter " + ii + " = " + cmd&ii

NEXTDECLARE arr [2]arr[1] := 1 ; arr[2] := 1v1=1 ; v2=1DO chg WITH arr,arr[2],v1,(v2)? arr[1], arr[2], v1, v2 && 2 3 4 1RETURN

PROCEDURE chgPARAMETERS p1,p2,p3,p4 && procedure paramsp1[1] := 2 ; p1[2] := 5 // change array elem.p2 := 3 // redeclares p1[2]p3 := 4 // changes v1p4 := 9 // v2 remains unchangedRETURN


Related:DO, FUNCTION, PRIVATE, PUBLIC, LOCAL, STATIC, SET PROCEDURE TO,PCOUNT(), Param()

CMD 248

PRIVATESyntax 1:

PRIVATE <memvar> [:= <exp>] [, ... ]Syntax 2:

PRIVATE <array> [<dim>]PRIVATE <array> [<dim1>,<dim2>,<dimN>]PRIVATE <array> [<dim1>][<dim2>][<dimN>]PRIVATE <array> := {<exp>,... }

Purpose:Creates and initializes the specified memory variables or arrays in the PRIVATEclass.

Arguments:<memvar> is the list of variables or arrays to be created as PRIVATEs. In this list,arrays and other variables can be interchanged. The name may be of any length,but only the first 10 characters are significant (see more LNG.2.6). Variable namesin the FlagShip language are not case sensitive.

<array> is the name of the array to be created. The naming convention is the sameas in <memvar>. The square brackets [ ] behind the <array> name do not in thiscase specify an optional argument, but are a required part of the syntax. Thenumber of elements for each array dimension can be specified as [dim1,dim2,..,dimN] or [dim1][dim2][dimN]. The maximum number of dimensions and ofelements per dimension in FlagShip is 65535.

The PRIVATE <array> statement is equivalent to DECLARE <array>. Arrayelements can be handled like ordinary memory variables. Different elements of thesame array can be of different types. Each element may contain another sub-array(non-symmetric structure), see LNG.2.6.4.

Options, Initializing:<exp> is any valid FlagShip expression including a literal (constant) array toinitialize the variable. If the initializer (:= <exp>) is not given, the variable (or allarray elements) will be set to NIL. Initializing of a variable created by composedmacro (e.g. PRIVATE var&macro := value) is not supported but the sequencePRIVATE var&macro ; var&macro := value is ok.

The array elements can be declared and initialized with a starting value using anarray (literal) constant (see LNG.2.7) including any valid expression and the assign:= operator. Initialization is performed at the time of the variable creation, that is,when executing the PRIVATE (or DECLARE, PARAMETERS) statement.

Scope, Visibility:PRIVATE variables have dynamic scope. These variables are visible within thecurrent and all UDFs and UDPs called from within. When a private variable or arrayis created, existing and visible PRIVATE and PUBLIC variables of the same name

CMD 249

are hidden until the current procedure or user-defined function terminates. Privatevariables exist for the duration of the active procedure or until explicitly releasedwith CLEAR ALL, CLEAR MEMORY, or RELEASE. If a procedure or UDF isinvoked recursively (calls itself), each recursive activation creates a new set ofPRIVATE variables.

PRIVATE variables can be passed by value or by reference to other UDFs or UDPscalled at the same level. In code blocks, only PRIVATE variables of the modulewhere the block is executed are visible; see LNG.2.3.3.

For more information about variables, refer to the section LNG.2.6.

Description:PRIVATE is an executable statement which creates and initializes a new variable orarray in the dynamic scoping class. If the same named variable does not exist, it isequivalent to the creation of an autoPRIVATE variable using an assignment. ThePRIVATE statement is equivalent to DECLARE and similar to the PARAMETERScommand.

Short notation: if the PRIVATE declarator is placed prior to the first FUNCTION orPROCEDURE statement and the compiler switch -na is used, the declaration (andinitialization) is placed at the start of every module in the .prg file. The scope,visibility and lifetime is equivalent to explicitly placed PRIVATE declarations in eachof these entities.

Example:PRIVATE var1, arr1[5], var2, arr2[2,3]DECLARE arr3[4], arr5[2,2]PRIVATE var6 := 24, arr7 := {0, 0, {0, 0}}PRIVATE menu := {"Show", "Add", "Print", "Exit"}


Compatibility:The initialization during the declaration is new in FS4. PRIVATE variables areavailable in all xBASE languages. Only FlagShip supports an unlimited number ofvariables, 64k * 64k array element size and short notation.

Related:DECLARE, PARAMETERS, PUBLIC, LOCAL, STATIC, GLOBAL, FIELD,MEMVAR

CMD 250

PROCEDURESyntax 1:

PROCEDURE <udpName> [AS USUAL][PARAMETERS <parList>]

<statements>...RETURN

Syntax 2:PROCEDURE <udfName> ([<parList>]) [AS USUAL]

<statements>...RETURN

Syntax 3:[STATIC|INIT|EXIT] PROCEDURE

<udfName> ([<parList>]) [AS USUAL]<statements>...

RETURNPurpose:

Identifies the beginning of a user-defined procedure (UDP) or a startup/exitprocedure.

Arguments:<udpName> is the name of the procedure UDP. The name may be of any length,only the first 10 characters are significant and is not case sensitive (for more detailsrefer to section LNG.2.3). Names starting with an underscore are reserved forFlagShip.

<udfName> is the name of a function (UDF), see below.

RETURN terminates the execution of the UDP and passes control back to thecalling program. Any number of RETURNs are accepted within the UDP.

Options:STATIC PROCEDURE declares an UDP, which is visible in the current .prg fileonly. Several STATIC UDPs and UDFs (and only one public UDP/UDF) may bedefined with the same name in different .prg files.

Because the references to a STATIC function are resolved at compile-time, they willhide public UDP or UDF with the same name. STATIC procedures are not visibleand therefore cannot be used during a macro evaluation or as UDF for ACHOICE(),MEMOEDIT() etc.

When the keyword STATIC is omitted, the UDP becomes public and the name isvisible to the whole application.

PARAMETERS <parList> specifies one or more comma-separated PRIVATEvariables which receive the calling arguments. See more in the PARAMETERScommand.

CMD 251

(<parList>) is the alternative syntax to the PARAMETERS command, but thevariables in <paramList> have LOCAL type and may optionally be typed, see below.

AS USUAL (proto)types the procedure and specifies, that the compiler shouldinclude its PROTOTYPE into the repository file.

Init/Exit:INIT PROCEDURE declares an initialization procedure, which will be executed atprogram startup. An arbitrary number of INIT PROCEDUREs may be declared.They will be successively invoked prior to the first executable statement in the mainmodule, one after the other. The visibility of the INIT procedures is restricted to theFlagShip system. Each procedure receives a copy of the UNIX command linearguments given when invoking the executable, passed to the <parList>. See thenote on linking and calling below.

EXIT PROCEDURE declares an exit procedure, which will be executed at programtermination. Any number of EXIT PROCEDUREs may be declared for the wholeapplication. The EXIT procedures are successively invoked after the last executablestatement in the main module (or from the QUIT or CANCEL command) prior toreturning to the UNIX shell. The visibility of the EXIT procedure is restricted to theFlagShip system. Each EXIT procedure receives a numeric parameter, representingthe sequence order of the EXIT procedure, starting with one. The execution of anEXIT procedure cannot be guaranteed when the system encounters anunrecoverable error. See also linking and calling note.

Linking and calling the INIT/EXIT procedures: If the .prg source file consists onlyof INIT and/or EXIT procedures, the automatic compilation rule (see below) cannotapply. Instead, the source .prg or the object .o file must be specified when invokingFlagShip during the compile/link phase. Also, the ANNOUNCE/REQUESTdeclarators (or EXTERNAL <prgname> if compiled without the -na switch) must beused to specify the external. The INIT and/or EXIT procedures will be executed inthe same order as their corresponding files were specified in the FlagShipcommand line during the linking phase.

Prototyping of parameters:The local parameters specified in brackets (according to syntax 2) may optionallybe typed (with all usual <type>s according to LOCAL..AS), and/or prototyped asoptional. The syntax is equivalent to (<paramList>) of the PROTOTYPE declarator,e.g.

PROCEDURE myUdp (p1 AS CHAR, [p2 as NUMER], p3, [p4])

If the <type> is not given (e.g. parameters p3 and p4 in this example), AS USUAL isassumed. The parameter name enclosed in square brackets [ ] (visually) signals anoptional parameter, used also in (and passed to) UDP prototypes. It does notchange the behavior of parameter passing, nor the parameter order in any way.

Also the return procedure <type> may be prototyped by AS USUAL according tosyntax 2.

CMD 252

Purpose: Giving the parameters a <type> allows a compile-time check of theparameters (arguments) passed to the procedure at places where it is invoked. Thiscompile-time check will help you to avoid unexpected RTEs (run-time errors) andsimplify parameter validation in the procedure body. See also "parameter passing"below. Use the PROTOTYPE declarator (e.g. in an #include file), when the UDP isinvoked in other than the current file (prototyping); or when the UDP is specified inthe same file, but is invoked before its declaration (forward prototyping) to takeadvantage of the compile-time checking.

Note: the PROTOTYPE statement is automatically created in the repository file (forAS USUAL typed UDPs only) by using the -ru compiler switch, see FSC.1.3.

All standard FlagShip functions and procedures are prototyped in the stdfunct.fhfile.

Description:Functions and procedures increase both readability and modularity, isolate changesand standardize a block of frequently-used statements.

A user-defined procedure UDP is called with the command :

DO udpnameDO udpname WITH param1 [, param2 ...]

Procedures can also be called by using macros, e.g.:

udpname = "my_proced"myparam = "xyz"; xyz := 5DO &udpname WITH "test", &myparamDO (udpname) WITH "test", &(myparam)DO my_proced WITH "test", 5

Procedures may also be called in FlagShip using the UDF syntax. See FUNCTIONcommand.

The UDP may call itself recursively. The number of recursions is in FlagShiplimited only by the available RAM + swap disk space to store the local data of eachrecursion.

Automatic procedures:If the compiler switch -na is not given, FlagShip generates an automaticPROCEDURE carrying the name of the file without extension, for compatibilitypurposes. When starting the source file with a PROCEDURE of the same name asthe file, an (additional) automatic procedure is not generated.

Parameter passing:The calling arguments when using the DO...WITH command are passed to a user-defined procedure by reference, except constants, expressions and database fields,which are always passed by value. To pass a variable by value, the argument hasto be enclosed in parentheses, e.g. DO myproc WITH (var1), (var2), var3.

The UDP copies the passed argument values or references into predefined PUBLICor LOCAL variables in the <parList>. The number of arguments passed and

CMD 253

parameters received need not be the same. Arguments can be skipped or left offthe end of the argument list. A parameter not receiving a value or reference isinitialized to NIL. Refer to LNG.2.3.2 and (CMD) PARAMETERS for a more detaileddiscussion.

On typed parameters, only arguments of the specified parameter type are accepted.If the prototype of the UDP is known at compile time (see prototyping), an incorrectargument passing is reported by the FlagShip compiler. If the prototype or theargument type is unknown at compile time, and an incorrect argument type ispassed, a run-time error occurs. On optional parameters (i.e. enclosed in squarebrackets), only the specified type or NIL is accepted.

UDF vs. UDPIn FlagShip, the only difference between the call to a function (UDF) or procedure(UDP) is the convention of default parameter passing. Both UDF and UDP can beused interchangeably, so if an UDP is called using the function syntax, thearguments/parameters are passed by value, instead of by reference.

Automatic compilation:If the compiler switch -m is not given, every time it finds a DO statement and thename of the procedure is unknown, the compiler searches the current directory for asource file with the same name in order to compile it. Refer to the (CMD) DOstatement.

Example:Notice the main procedure calling two sub-procedures, two of them in the sameprogram file, two in a separate file:

*** Main program file test.prgDO Proc1DO Proc2 with "Main"DO Proc3 with 5RETURNPROCEDURE Proc1? "The first procedure"DO Proc2 with PROCNAME() && current procedure nameRETURNPROCEDURE Proc2PARAMETERS par1? "The second procedure, called from " + par1DO Proc4RETURN*** eof test.prg*** file proc3.prg** PROCEDURE Proc3 && omit this declarationPARAMETERS p1// any statementsRETURN

PROCEDURE proc4// any statementsRETURN*** eof proc3.prg// Compile: $ FlagShip test.prg -otest

CMD 254

Example:Usage of INIT/EXIT procedures, e.g. to measure the execution time:

*** Main program file test.prgSTATIC timecpu, timeall // .prg wide scope

PROCEDURE main (cmd1, cmd2) // main moduleUSE addressLIST name, address FOR inkey() != 27RETURN // return to OS

INIT PROCEDURE startup (cmd1, cmd2) // init proceduretimeall := SECONDS()timecpu := SECONDSCPU()RETURN

EXIT PROCEDURE exitproc () // exit procedure?? "Time elapsed : ", SECONDS() - timeall, "seconds"? "real CPU time : ", SECONDSCPU()- timecpu, "seconds"RETURN

// Compile: $ FlagShip test.prg -Mmain -na -otest


Compatibility:The STATIC clause, the usage of formal LOCAL parameters and the INIT/EXITprocedures are compatible to C5. The <parN> in the EXIT PROCEDURE isavailable in FS4 only. FlagShip accepts the interchangeable UDF/UDP callingconvention. Typed parameters and typed functions are supported by FS4 and VO.The definition of optional parameters by using square brackets is available inFlagShip only.

Related:DO, SET PROCEDURE, FUNCTION, PROTOTYPE, LOCAL, PCOUNT(), Param()

CMD 255

PROTECT INSTANCESyntax 1:







CMD 256

PROTOTYPESyntax 1:

PROTOTYPE [STATIC] CLASS <ClassName>[INHERIT <SuperClass>]

and optional:EXPORT|HIDDEN|PROTECT [INSTANCE] <Name> [AS <type>]INSTANCE <Name> [AS <type>]

Syntax 2:PROTOTYPE ACCESS [METHOD] <methName> [ () ]

CLASS <className> [AS <type>]PROTOTYPE ASSIGN [METHOD] <methName> (<par1>)

CLASS <className> [AS <type>]PROTOTYPE [PROTECT] METHOD <methName>

[(<paramList>)]CLASS <className> [AS <type>]

Syntax 3:PROTOTYPE FUNCTION <udfName> [(<paramList>)]

[AS <type>]Purpose:

Informs the compiler about the class entities or about the type of a user definedfunction in order to optimize the class access and/or perform type checking duringthe compilation phase.

Description:PROTOTYPE (according to syntax 1 and 2) informs the compiler about the CLASSstructure, it's instances and methods. If PROTOTYPEs of the class are unknown atcompile-time, the slower run-time address resolving is generated, see LNG.2.11.6.Refer also to the CLASS and METHOD description. For the FlagShip standardclasses, the prototypes are specified in the <xxx>class.fh, or the summarized"stdclass.fh" file, which may automatically be included from within "std.fh".

PROTOTYPE (according to syntax 3) informs the compiler about the UDF type (andparameters), to perform compile-time and/or run-time invocation and parameterchecking. For the FlagShip standard functions, the prototypes are specified in the"stdfunct.fh" file, and can also be automatically included from "std.fh".

Since the PROTOTYPE is non-executable compiler information only, it may beplaced anywhere in the source. The prototype becomes active for all subsequentlines in the .prg source file. You may preferably place prototypes in a separate,project specific .fh file, which will be #include'd in the required .prg sources. Themost convenient method is to #include "myproto.fh" at the end of the local copy ofthe std.fh file.

CMD 257

Automatic prototype generation: the FlagShip compiler is able to automaticallyextract all prototypes from your source into a file named "reposit.fh", when thecompiler switch -rc and/or -ru is specified (see section FSC.1.3).

Hint: In a large application, you may pre-compile all *.prg sources of the application(e.g. by using -c -rc -ru -r=myprot.fh switches), then check the produced filemyprot.fh and #include it into the local copy of the std.fh file... and your applicationmay be finally compiled. The compiler will now know all declared (typed) functions,classes etc. and may therefore issue warnings when using the -w3 and/or -w4option. Additionally, all occurrences of known classes are early bound, which willspeed up the execution significantly, see also chapter LNG.2.11.6 .

Syntax 1:

CLASS prototyping is used if the class declaration is specified in another source file(or a library module).

Note, that the instance <Name> in the class PROTOTYPE has to match the<Name> of the instance declaration (in the CLASS statement, without casesensitivity, but at least in the first 10 significant characters). The order in which theinstances are given does not matter. For additional info and arguments used, referto the CLASS description.

Syntax 2: The CLASS METHOD prototyping is used

a. together with syntax 1, if the class declaration and theirs entities are specified inanother source file (or a library module). In this case, all instances and access,assign, methods must also be declared with the same name as in the classdeclaration. Their order does not matter, but the class prototypes according tosyntax 1 must be declared first. You may also #include the, by the FlagShipcompiler automatically created, 'reposit.fh' file according to sect. FSC.1.4.2.

b. during method creation, when the method refers to a yet undeclared access,assign or usual method (forward prototyping). It is not necessary to prototype amethod, which was formerly declared in the same source file, since the FlagShipcompiler internally holds tables of the known classes (and its entities)encountered in the currently compiled source file. Otherwise, when an (yet)unknown method is invoked, the code for a run-time access is generated (latebinding), which results in slower performance.

For additional info and arguments used, refer to the METHOD description.

Syntax 3: UDF prototyping is used for compile-time and run-time checking of thearguments being passed and of the returned values.

If the UDF return type is prototyped (e.g. PROTOTYPE MyUdf() AS LOGICAL), thecompiler reports an error, if the result is assigned to a typed variable of anincompatible type, or if an invalid RETURN value was used within the UDF body.On the other hand, assigning an untyped UDF to a typed variable may result in arun- time error "attempt to assign <UDF-return-type> to fixed <vartype>". Theassignment to an untyped, or to a typed AS USUAL variable is always accepted.

CMD 258

When also the UDF parameters are prototyped, the compatibility of the passedarguments are checked both at compile-time (on known types, e.g. LOCAL.. ..AS)and at run-time. It allows an early detection of passing wrong arguments or a wrongargument count, which mostly avoids a run-time error. The run-time check simplifiesparameter validation, since only the specified <vartype> is accepted, otherwise arun-time error occurs.

Arguments:AS <type> (proto)types the return value or the parameter to be fix and of thespecified <type> only. If the AS <type> is omitted, the implicit USUAL type isassumed. The compatible types (see also LOCAL..AS) for return values andparameter prototyping are:

Prototype Accepted variable or constantC-like types not allowed for UDF prototypingARRAY ARRAYCHARACTER CHARACTER, PSZ, STRINGCODEBLOCK CODEBLOCKDATE DATEINTVAR INTVAR, NUMERIC, all C-like typesLOGICAL LOGICAL and INTVAR, NUMERIC, C-like types whereby 0 (zero) is

converted to .F., all other values to .T.NUMERIC NUMERIC, INTVAR, all C-like typesOBJECT OBJECT, <userClass>, <stdClass>PSZ CHARACTER, STRING, PSZSCREEN SCREENSTRING CHARACTER, PSZ, STRINGUSUAL any type<stdClass> <stdClass>, OBJECT<userClass> <userClass>, OBJECT

Arguments:<paramList> specifies one or more comma separated LOCALy scopedparameters, corresponding to the parameter list of the procedure, function, ormethod declaration.

Knowing the prototype of the UDF (or method), the FlagShip compiler will check thecorrespondence of the type and number of passed arguments in all subsequentoccurrences of this UDF within the .prg file.

Note, that only the order, number (and type if given) of parameters have to match inthe UDF declaration and the PROTOTYPE statement, the name of the parametervariables may differ.

Each parameter <parName> in the <paramList> of the FUNCTION, PROCEDUREor METHOD declarator and in the PROTOTYPE statement can be specified as

•<parName> : Untyped parameter, similar to a local variable. Only the parametername is given, arguments of any type are accepted.

CMD 259

•<parName AS type> : Typed parameter, similar to a LOCAL ... AS variable. Onlyarguments of the specified <type> are accepted.

•[<parName>] or [<parName AS type>] : the square brackets [ ] specify optionalparameters, which will accept arguments of the specified <type>, as well as NILvalues. All arguments of optional parameters rightmost in the <paramList> maybe omitted.

•[...] : Any number of optional, untyped parameters (accepted in the PROTOTYPEstatement only). Useful e.g. for prototyping of functions with many arguments,e.g. written in Extend C API.

•<@parName> or <@parName AS type> or [<@parName>] : Automatic (implicit)parameter/ argument passing-by-reference, instead of the default passing-by-value. This may speed-up the execution significantly, especially on large strings.The compiler will not generate a temporary copy of the argument for parametersprefaced by the at-sign @. The UFD is called as if the argument is explicitlyprefaced by the at-sign @ (see also LNG.2.3.2). Warning: all modifications ofsuch implicit referenced parameters in the function body will also modify theincoming argument, including database fields and array elements (exceptconstants).

For your convenience, the same parameter syntax may also be used in theFUNCTION, PROCEDURE or METHOD declarator. The FlagShip compiler will thenproduce the corresponding prototypes fully automatically when the compiler switch -ru is set.

Example:Valid prototypes are:

PROTO udf1 () AS usual // no args acceptedPROTO udf2 ([...]) AS usual // any no of argsPROTO udf3 (p1, p2 AS numer) AS logic // 2 args requiredPROTO udf4 (p1 AS char, ; // 1 to 3 args,

[p2 as logic], [p3]) AS nume // at least onePROTO udf5 (p1 AS char, ; // at least 1st

[p2 as logic], p3) AS numer // and 3rd req.PROTO udf6 ([@p1 AS char], ; // any number, but

[...]) AS usual // the 1st is charPROTO udf7 (@p1, @p2 AS char) AS char // 2 args, passed

// by referencePROTO CLASS myClass

EXPO var1 AS intvarEXPO name2 AS charHIDD invi3 AS usual

PROTO METH meth1 () CLASS myClass AS arrayPROTO METH meth2 (p1, [@p2 AS char]) CLASS myClass AS objectPROTO ACCE name1 () CLASS myClass AS charPROTO ASSI name2 (p2 AS usual) CLASS myClass AS char

FUNCT udf8(p1, @p2 AS char) AS usual // passed to reposit.FUNCT udf9(p1, @p2 AS char) // not passed to repos

CMD 260

Example:Refer to the CLASS and METHOD description, section LNG.2.11.5 and the<FlagShip_dir>/system/smallrdd/smallrdd.prg file for examples of the CLASSprototyping.

Example:Refer also to the "stdfunct.fh" file for prototypes of the standard FlagShip functions.

Classification:programming, compiler/linker

Compatibility:Prototyping is available in FlagShip only. VO manages it through the 'repository'.For compatibility to Clipper, you may specify

#ifndef FlagShip #command PROTOTYPE <x> => #endif

Related:INSTANCE, METHOD, LOCAL..AS, FUNCTION, PROCEDURE, LNG.2.11

CMD 261

PUBLICSyntax:

PUBLIC <memvar> [:= <exp>] [, ... ]or:

PUBLIC <array> [<dim>]PUBLIC <array> [<dim1>,<dim2>,<dimN>]PUBLIC <array> [<dim1>][<dim2>][<dimN>]PUBLIC <array> := {<exp>,... }

Purpose:Creates and initializes the specified memory variables or arrays in the PUBLICclass, i.e. to be visible for the whole application.

Arguments:<memvar> is the list of variables or arrays to be created as PUBLICs. In this list,arrays and other variables can be interchanged. The name may be of any length,but only the first 10 characters are significant (see more LNG.2.6). Variable namesin the FlagShip language are not case sensitive.

<array> is the name of the array to be created. The naming convention is the sameas with <memvar>. The square brackets [ ] behind the <array> name do not in thiscase specify an optional argument, but are a required part of the syntax. Thenumber of elements for each array dimension can be specified as [dim1,dim2,..,dimN] or [dim1][dim2][dimN]. The maximum number of dimensions and ofthe elements per dimension in FlagShip is 65535. Array elements can be handledlike ordinary memory variables. Different elements of the same array can be ofdifferent types. Each element may contain another sub-array (non-symmetricstructure), cf. LNG.2.6.4.

Options, Initializing:<exp> is any valid FlagShip expression including a literal (constant) array toinitialize the variable. If the initializer (:= <exp>) is not given, the variable is set toFALSE (.F.) (or all array elements) will be set to NIL. Initializing of a variablecreated by composed macro (e.g. PUBLIC var&macro := value ) is not supported,but the sequence PUBLIC var&macro ; var&macro := value is ok.

The array elements can be declared and initialized with a starting value using anarray (literal) constant (see LNG.2.7) including any valid expression and the assign:= operator. The initialization will be done at variable creation time, i.e. whenexecuting the PUBLIC statement.

Scope, Visibility:PUBLIC variables have dynamic scope. These variables are visible for bothhierarchically higher and lower modules starting at the time of the PUBLICdeclaration. The PUBLIC variable can be later temporarily hidden using aPRIVATE, PARAMETERS, LOCAL, STATIC or GLOBAL declaration. The PUBLIC

CMD 262

variable can be explicitly destroyed using CLEAR ALL, CLEAR MEMORY, orRELEASE.

For more information about variables, refer to the section LNG.2.6.

Description:PUBLIC is an executable statement which creates and initializes a new variable orarray in the dynamic scoping class. The PUBLIC statement is equivalent to thePRIVATE declaration on the highest program level (main).

An attempt to create a PUBLIC variable with the same name as an existing andvisible PRIVATE variable is simply ignored. If the creation of a public array isrequested, the previous PUBLIC or PRIVATE array with the same name isdestroyed and replaced by the new one; if a dynamically scoped variable having thesame name already exists, the new array declaration is ignored. Attempting tospecify a PUBLIC variable that conflicts with a previous FIELD, LOCAL, STATIC orTYPED declaration of the same name results in a compiler error.

PUBLIC variables can be passed by value or by reference to other UDFs or UDPscalled from within. In code blocks, only active PUBLIC (and PRIVATE) variables ofthe module where the block is executed are visible; see LNG.2.3.3.

Reserved Variables:The following, reserved variables will be set up by the compiler and cannot bedeleted via CLEAR MEMORY, but their contents can be redefined using anassignment.

PUBLIC FLAGSHIP : when the FlagShip compiler encounters such a declaration, itinitializes it with the logical value TRUE (.T.) instead of FALSE. On the other hand,when compiling with Clipper, the variable remains FALSE. This allows a program tocheck which platform it is running and take different actions accordingly. Anotherpossibility is to compile different blocks of code using the preprocessor directives#ifdef FlagShip ... #else ... #endif.

PUBLIC GETLIST [0] : an automatically created array to carry the GET objects forthe command @...GET. As with all other PUBLIC arrays, this default array can behidden via a PRIVATE, LOCAL or STATIC declaration (e.g. LOCAL GetList := {} ) tocreate nested GET/READs to any level.

CMD 263

Example:See also section LNG.9 for the compatibility notes.

PUBLIC FlagShip, ClipperPUBLIC var1, subdir, arr1[5], arr2[10,10]subdir = "D:\data\public\"#ifdef FlagShip# ifdef FS_WIN32

? "invoking CMD/DIR in FS/Windows"RUN ("CMD /C DIR *.*")

# elsesubdir := "/home/data/public/"? "invoking ls -l in Linux/Unix"RUN ("ls -l *")

# endif#else

? "running under DOS with Clipper"RUN ("DIR *.*")

#endifUSE &subdir.adress


Compatibility:Initialization during the declaration is new in FS4. PUBLIC variables are available inall xBASE languages. Only FlagShip supports an unlimited number of variables,and up to 64k * 64k array element size.

Related:DECLARE, PARAMETERS, PRIVATE, MEMVAR, FIELD, LOCAL, STATIC,GLOBAL

CMD 264

PROTECT PUBLICSyntax:

PROTECT PUBLIC <memvar> [:= <exp>] [, ... ]Purpose:

Creates and optionally initializes protected public variable(s), which cannot bedeleted but may be overwritten by any other value, as opposite to CONSTANTwhich cannot be overwritten later.

The scope and visibility is equivalent to PUBLIC variables.



Related:PUBLIC, CONSTANT, PRIVATE, DECLARE, STATIC

CMD 265

PUSH KEYPOP KEYSyntax 1:

PUSH KEY [CLEAR]Syntax 2:

POP KEY [ALL]Purpose:

PUSH KEY and POP KEY is provided mainly for FoxPro compatibility

Description:Syntax 1: PUSH KEY saves all ON KEY, ON KEY LABEL and SET KEY definitionson internal stack for later restoring by POP KEY. The optional clause "CLEAR"deletes all key assignments of ON KEY, ON KEY LABEL and SET KEY.

Syntax 2: POP KEY restores the last ON KEY, ON KEY LABEL and SET KEYstructure previously saved by PUSH KEY.



Related:ON KEY, OnKey(), SetKey(), SET KEY

CMD 266

QUITSyntax:

QUIT [<exitCode>]or:

CANCELPurpose:

Terminates program execution, closes all opened files, and returns control to UNIX.

Options:<exitCode> is optional numeric value returned by the application on exit. Thedefault setting is 0. You alternatively may set the exit code by ErrorLevel(num) atany time before QUIT. The RETURN(num) in main module is equivalent to QUIT<num>.

Description:CANCEL or QUIT are available from anywhere in a program to terminate executionand to return to the operating system. The same result is achieved if the RETURNcommand is used on the top level or the user aborts via the break key (^K oranother defined with FS_SET("break") ).

When the program terminates, all open files are closed and flushed to the disk.Active record/file locks are released.

When a new console window was created in X11 or Windows environment (e.g. forapplication running in terminal or basic mode without own console), a delay of 10seconds occurs before the console window is closed. You may redefine this delayby setting

_aGlobSetting[GSET_N_WAITCLOSEWIND] := 10 // this is defaultSee more details in ConsoleOpen(). This delay is disabled, when the applicationwas compiled by using -io=b switch.

The return code is normally set to 0 or to 1..9 if the process ends with a fatal or run-time error. A user return code can be set with ERRORLEVEL() or the <exitCode>parameter of QUIT. The InitIoQuit() function (or your re-defined UDF) also sets exitcode on user abort, see details in <FlagShip_dir>/system/initiomenu.prg andErrorLevel()

Classification:programming (and database)

Translation:__QUIT([exitCode])

Compatibility:QUIT <num> is available in VFS7 only.

Related:RETURN, ^K abort, FS_SET(), SETCANCEL(), ERRORLEVEL()

CMD 267

READSyntax:

READ [SAVE][ALIGN|NOALIGN][SELECT <varC|posN>][SKIPOVER|NOSKIPOVER][EXITCHECK][CLEAR|DESTROY][CYCLE]

Purpose:Activates the full-screen editing mode using a list of pending GETs (objects).

Options:The SAVE clause retains the list of current GETs to enable editing the same GETsby issuing another READ. Without it, the current GETs are cleared when READends except when ReadSave(.T.) is called during the READ.

The ALIGN or NOALIGN clause temporarily overrides the current SET GUIALIGNsetting. It specifies if the columns of @..SAY..GET should be aligned to the samevirtual column position via the GuiAlign() function. The align apply mainly for GUImode with proportional fonts. See also SET GUIALIGN and GuiAlign(), available insource in <FlagShip_dir>/system/getsys.prg.

SELECT <varC> or SELECT <posN> causes READ to start with GET itemspecified by variable name <varC>, or with item number <posN> within the GetListarray. If the GET item is disabled, next enabled item is used. If SELECT is notgiven, READ starts at the first enabled item within current @..GET list. See alsoReadSelect() function.

SKIPOVER clause allows to skip over validated fields, NOSKIPOVER forces to stayin the field which does not meet the VALID criteria. Skipping over a field can mostlyapply in GUI by mouse click on different field or widget in the GetList.

If EXITCHECK is specified, READ will check all VALID conditions at exit and stayon the unsatisfied field even if SKIPOVER was set.

The CLEAR or DESTROY clause clears GUI Get widgets on exit. If not specified,the widget remain visible same as in Terminal i/o.

With the CYCLE clause, the READ will not be terminated when moving forwardover the last GET item, or backward over the first GET. It instead cycles from thelast to first, and from first to last item. The READ CYCLE will be terminated by ESC,Ctrl-W or CLEAR GETS.

Description:The READ command enables full-screen editing using the pending list of GET fieldsstored in the GETLIST [] array since the most recent CLEAR, CLEAR GETS,CLEAR ALL or READ was executed.

CMD 268

Each GET field definition consists of an object, where the screen coordinates,formatting, color, and pre- and post validation conditions are stored. These valuesare specified by the @...GET command or assigned to the object. The user canedit, re-enter or confirm the field data. Using the navigation keys, the user can movebetween fields. The content of the field-editing buffer is stored in an associatedmemory or FIELD variable.

The execution starts with the first pending GET field in the current GETLIST arrayand is finished when all available fields are processed or a termination key ispressed. If there is a format procedure active (see SET FORMAT), READ executesthat procedure prior to entering the full-screen editing mode.

When the current GET field is finished (by filling the rightmost column and SETCONFIRM is OFF) or by pressing the GET or READ termination key, control ispassed to the optional plausibility checking specified by the RANGE and/or VALIDclause. If FALSE is returned from the VALID condition or the value is out of theRANGE boundary, the cursor remains within the current field, allowing the user tocorrect his entry. The ESC key leaves READ without storing the current field andwithout plausibility checking, if SET ESCAPE is ON.

To modify active GET field during the READ execution, use WHEN or VALID clauseof @..GET, or SET KEY function. See "Validity" chapter below and examples in<FlagShip_dir>/examples/getvalid*.prg

READ is finished when the appropriate termination key is encountered, or the lastpending GET field is terminated, or CLEAR GETS executed during the READprocess. Thereafter, the GET fields remains yet visible, except READ CLEAR wasused. To overwrite yet visible but inactive GET fields by @..SAY, ?, ?? or otherdisplay commands, clear the screen area first by @ row,col CLEAR TO row,col orthe whole screen by CLS, CLEAR SCREEN or CLEAR.

Full-screen Navigation Keys for GETs and READ:

Key ActionCursor <- ctrl-S moves cursor one position leftCursor -> ctrl-D moves cursor one posit. rightCursor Up ctrl-E previous GET fieldshift-TAB previous GET fieldCursor Down ctrl-X next GET fieldEnter ctrl-M next GET fieldTAB ctrl-I next GET fieldHome ctrl-A first character in field *End ctrl-F last character in field *ctrl-Cursor <- ctrl-Z previous word in fieldctrl-Cursor -> ctrl-B next word in fieldctrl-Home ctrl-] first GET field of READctrl-End ctrl-W last GET field of READ or exit * *Left-Mouse-Button on other field: select field ** *Mouse-Wheel previous/next GET field ** *

CMD 269

* Quick keys: the first instance of the [Home] or [End] key pressed moves thecursor to the first or last valid character; a repeated key moves the cursor to thestart or end of the field.

** ctrl-W and ctrl-End behavior depends on settings: it exits READ with CYCLEclause or _aGlobSetting[GSET_L_GET_CTRLW_EXIT] = .T. otherwise it skipsto last GET field of READ. See Tuning below.

*** GUI mode only.

Edit Keys for the GET field:

Key ActionInsert ctrl-V Insert mode on/off *Delete ctrl-G Delete character at cursorBackspace <= ctrl-H Delete previous character

ctrl-T Delete word rightctrl-Y Delete rest of the fieldctrl-U Undo, restore original field

Left-Mouse-Butt-Down Mark text for copy-and-paste **Mid-Mouse-Button Alt-C Copy marked text to clipboard **Shift+Mid-Mouse-But Alt-V Paste clipboard to curr.field **

* the insert mode continues to remain active for the next GET or READ.

** GUI mode only. See description in "cut-and-paste" below.

GET and READ Termination Keys initiate a post validation and store the GET fieldcontents into an associated memory or FIELD variable:

Key Action (S = save,V = post-valid,T = terminate READ)

Cursor up ctrl-E being in first field SV T *otherwise: prev. field SV

Cursor down ctrl-X being in last field SV T *otherwise: next field SV

Enter, Return ctrl-M being in last field SV Totherwise: next field SV

ctrl-Home ctrl-] go to first field SVctrl-End ctrl-W terminates READ or last GET SV T **PgUp ctrl-R terminates READ SV TPgDn ctrl-C terminates READ SV TEscape (Esc) terminates READ T *

* termination keys: READ termination depends on the current setting ofREADEXIT() and SET ESCAPE.

** ctrl-W and ctrl-End behavior depends on settings: it exits READ with CYCLE

CMD 270

clause or _aGlobSetting[GSET_L_GET_CTRLW_EXIT] = .T. otherwise it skipsto last GET field of READ. See Tuning below.

Terminating READ is also possible by executing the BREAK, CLEAR, CLEARGETS, or CLEAR ALL command from a SET KEY procedure or from a user definedfunction initiated by the VALID clause.

Validity, Plausibility:Each GET field can include a pre-valid and/or plausibility (post- valid) conditionchecking by using the @...GET clauses WHEN, VALID or RANGE.

Before the user can enter a GET field (object), control passes to the associatedWHEN <condition> if one is given. If the condition returns TRUE, editing is enabled;otherwise, the field is skipped. When the user presses a GET exit key, controlpasses to the associated RANGE or VALID post-condition if one has beenspecified. If either of the conditions return FALSE, or the numeric value is out of theRANGE boundary, control remains within the current GET field until a valid value isentered or the user presses the Esc key. If both clauses are specified, RANGE isperformed first.

See WHEN and VALID examples below, in @..GET and in <FlagShip_dir>/examples/getvalid*.prg

Update-Status:When any GET field is changed by the user (but not in a VALID or SET KEYfunction), the UPDATED() function will return TRUE.

Nested Reads:By executing a VALID function or SET KEY procedure (background routine) whenin READ, another set of GET..READ may be temporary initiated, if a LOCAL,STATIC or PRIVATE array GETLIST[0] is created there. All subsequent @...GETsand READ will refer to this local set of GET fields, until the procedure or functionreturns control back to the active READ.

Redirection: When one of the navigation key is redirected via SET KEY orON KEY or SET FUNCTION, the redirection is executed instead of the defaultbehavior.

User-modifiable READs and Objects:During READ execution, the current GET object may be determined by usingGETACTIVE(); the associated export variables (including the editing buffer) can berevoked or changed within a background routine. The type of the current GETvariable may not be changed without executing GETACTIVE():SETFOCUS().

For more programming control over the READ command, you may modify<FlagShip_dir>/system/getsys.prg. Other user-defined READs may also beperformed if the procedure name is assigned to the get:GETREADER exportvariable.

CMD 271

Multiuser:If one or more GETs refer to database fields, RLOCK() or FLOCK() in theassociated working area must be executed before the READ statement. Thedatabase should be UNLOCKed after READ. See also LNG.4.8 and Timerparagraph below.

Multi-byte support:To display multi-byte characters (used for east Asian languages) during the READinput, enable it by SET MULTIBYTE ON either global or latest before the READstatement.

Multi-byte characters are used e.g. in east Asian languages and are displayed withcorresponding environment setting. It usually concatenates two ascii characters >128 to one multibyte sign. Hence to be able to display 10 multibyte signs, input fieldof 20 characters is required.

Cut and Paste:Depending on the currently used i/o mode (GUI, Terminal), you may insert/overwritecharacters in the GET field by cut and paste.

In GUI mode, FlagShip supports the global X11 or Windows clipboard forexchanging/transfer keyboard data. You may copy and paste text via clipboardfrom/to other windows or applications on the screen, or from/to other/current GETfield(s).

To copy part of the GET field into clipboard, issue:

•mark the text by depressed left mouse button, then•press the Alt-C or middle mouse button (both user modifiable)

To copy text from another application on screen to clipboard, use thecorresponding key sequence of this application (like Ctrl-C, right or middle-mouse-button menu etc).

To paste clipboard at current GET field position, issue:

•press Alt-V or Shift + middle mouse button (both user modifiable)

When INSERT state is on, the pasted text from clipboard is inserted, otherwise theGET content is partially overwritten by the text from clipboard (same as you wouldtype it).

Tuning:The READ is fully tunable, since available in source code in the<FlagShip_dir>/system/getsys.prg file. You may copy it to your working directory,and compile according to the header in source file, then link with your application.

You additionally may tune the standard READ behavior by following switches:

The copy and paste buttons or keys are user modifiable by assigning correspondingINKEY() value (see inkey.fh for K_* manifests) to:

CMD 272

_aGlobSetting[GSET_G_N_GET_COPY1 ] := K_MBUTTONDOWN // copy_aGlobSetting[GSET_G_N_GET_COPY2 ] := K_ALT_C // copy_aGlobSetting[GSET_G_N_GET_PASTE1] := K_SH_MBUTTONDN // paste_aGlobSetting[GSET_G_N_GET_PASTE2] := K_ALT_V // paste

where the default settings (set in initio.prg) are shown here. Note that the commonCtrl-C and Ctrl-V keys are already assigned otherwise (PgDn and Insert), thereforeAlt-C and Alt-V are pre- defined instead. You may need to assign other keys whenthese conflicts with TopBar menu or with your SET KEY redirection. In MS-Windows, you may probably prefer K_RBUTTONDOWN for paste; it is not set bydefault to avoid unintentional copying from the clipboard. Of course, you also maymodify the behavior directly in <FlagShip_dir>/system/getsys.prg source, seeabove.

In Terminal i/o mode, similar functionality is provided (in Unix) via the "gpm" cut-and-paste console utility/daemon and FlagShip keyboard buffer by using it pre-defined keys and/or mouse buttons. To copy large strings, you probably may needto extend the buffer size by SET TYPEAHEAD.

In both GUI and Terminal i/o, you may specify the behavior of Home and End key,whether this keypress should skip to first/last valid character in field, or to the fieldbegin/end

_aGlobSetting[GSET_L_GET_HOME2CHAR ] := .T. // default = 1st_aGlobSetting[GSET_L_GET_END2CHAR ] := .T. // default = last

however a double press on the Home/End key will skip cursor to begin or end of theREAD field, and vice-versa.

In GUI, you may modify the behavior of mouse click on READ field: Should mouseclick in current field execute oGet:Home() ?

_aGlobSetting[GSET_G_L_GET_MOUSEHOME]:= .F. // default = noShould mouse click in another field activate this field and perform thereoGet:Home() ?

_aGlobSetting[GSET_G_L_GET_MOUSENEW] := .T. // default = yesShould mouse click allow position behind the last valid char ?

_aGlobSetting[GSET_G_L_GET_MOUSEOUT] := .F. // default = noThe Ctrl-W and Ctrl-End keys terminates READ by default (same as in VFS6 andClipper 5.x without setting #define CTRL_END_SPECIAL). To re-define them toskip to last GET item of READ (i.e. to behave same as Clipper'87 or FS4 or VFS5),assign

_aGlobSetting[GSET_L_GET_CTRLW_EXIT] := .F. // default = .T.which however may be overloaded by the CYCLE clause, which always causes exitfrom READ.

The SET KEY redirection forces to re-display the visible GET field. You may avoid itby assigning

_aGlobSetting[GSET_L_READ_INKEY_PLAIN] := .F. // default = .T.which then uses InkeyTrap() instead of Inkey()

Additional tuning is described in the @..GET command.

CMD 273

Timer:You may abort the READ after specified time period by issuing e.g.KeySec(K_ESC, 900) before READ and KeySec(.F.) thereafter. This simulatespress of ESC key after 15 minutes (of inactivity), e.g. to unlock the record for editingby others. You also may use KeyTime(...) for similar purposes. These Key*()functions are available in FS2 Toolbox, see section FS2:Date/Time/Triggers fordetails.

Example:Access to database fields in multiuser mode:

FIELD name, city@ 1,0 say "Name " GET name@ 2,0 say "City " GET cityDO WHILE !RLOCK() ; ENDDO // lock .dbf fieldsREADUNLOCK // unlock in multiuser

Example:Nested GET/READs to several levels:

#include "inkey.fh"SET KEY K_F2 to f2_procSET KEY K_F3 to f3_procvar1 := var2 := space(40)@ 1, 0 GET var1@ 2, 0 GET var2 VALID f3_proc(PROCNAME(), PROCLINE(), ;

READVAR() )READ

PROCEDURE f2_proc (procName, procLine, actVarName)LOCAL myvarname := READVAR()LOCAL getlist := {} // required for nestingLOCAL var3 := 0, var4 := 0output (procName, actVarName) // or myvarname@ 5, 0 GET var3@ 6, 0 GET var4READRETURN

FUNCTION f3_proc (procName, procLine, actVarName)LOCAL getlist[0] // required for nesting, same as getlist := {}LOCAL var5 := 0output (procName, actVarName)@ 9, 0 GET var5READRETURN var5 > 0

STATIC FUNCTION output (procName, actVarName)@ 23,0 SAY "Trapped procedure F2 from " + procName@ 24,0 SAY "Nested READ variable: " + actVarNameRETURN NIL

CMD 274

Example:For more examples see the section (CMD) @..SAY..GET.


Class:uses GET class, prototyped in <FlagShip_dir>/include/getclass.fh

Compatibility:The use of objects is compatible to C5. In Clipper, the GET class cannot beinherited to user defined class.

The ALIGN, NOALIGN, SKIPOVER, NOSKIPOVER, EXITCHECK, CLEAR,DESTROY clauses are new in FS5, MULTIBYTE and cut-and-paste support is newin FS6

Source:<FlagShip_dir>/system/getsys.prg

Translation:READ => READMODAL(GetList) ; GetList := {}READ SAVE => READMODAL(GetList)

Related:@...GET, CLEAR GETS, SET FORMAT, SET KEY, SET MULTIBYTE, UNLOCK,LASTKEY(), FLOCK(), RLOCK(),

CMD 275

RECALLSyntax:

RECALL [<scope>][FOR <condition>][WHILE <condition>]

Purpose:Reinstates DELETEd records in the current working area. If the record was notdeleted, no action is performed.

Options:<scope> is the part of the current database file to be undeleted. The default scopeis the current record if a condition is not specified, or ALL if a condition is specified.

<condition>: The FOR clause specifies that the set of records meeting thecondition within the given scope are to be recalled. The WHILE clause stopsrecalling when the first record not fulfilling the condition is reached.

Description:The deleted records are invisible when SET DELETED is ON and the databasepointer was moved. To reach deleted records, use GOTO or SET DELETED OFF.

Multiuser:RLOCK() is required when recalling one record, while FLOCK() when <scope> or<condition> is used. Otherwise, AUTOxLOCK() is used, when SET AUTOLOCK isenabled (the default).

Example:USE employeeDELETE ; ? DELETED() && .T.RECALL ; ? DELETED() && .F.SKIP? DELETED() && .F.RECALL ; ? DELETED() && .F.


Compatibility:The automatic lock is not available in Clipper. FlagShip's autolock is similar toFoxPro and VO.

Translation:RECALL => DBRECALL()RECALL [..] => DBEVAL ({|| DBRECALL()}, [{for}],[{while}],;

[next], [rec], [.rest.] )

Related:DELETE, PACK, SET DELETED, SET AULTOLOCK, ZAP, DELETED(),oRdd:RECALL()

CMD 276

REFRESHSyntax:

REFRESHPurpose:

Refreshes the screen contents from the last valid output buffer.

Description:In the UNIX multiuser/multitasking environment, a screen output from differentprograms can be re-routed to one physical screen, which may garbage the outputand deviate from the logical screen image buffers of the FlagShip application.

Note: To avoid long transfer time (e.g. on serial connected terminals), the curseslibrary optimizes the output, displaying the changed characters only. The requiredparts of the curses library are linked into the FlagShip compiled executable; seesection SYS.

By-passing the curses in any way (e.g. using #Cinline printf() output, activatingother virtual shell windows or sessions, rerouting the output to /dev/tty.., printingfrom a child program etc.) may cause unpredictable results of subsequent screenoutput.

In such a case, use the REFRESH command or REFRESH() function to re-displaythe current FlagShip output and reset the correct cursor coordinates. Executing thesequence SAVE SCREEN ... "odd output" ... RESTORE SCREEN will not causethe same effect as REFRESH in all cases, but in RUN only.

Example:SETPOS (10,5)?? "Now, the directory is listed:"y1 := ROW(); x1 := COL() // 10, 34RUN MESSAGE "press any key" ls -l *INKEY (0)y2 := ROW(); x2 := COL()REFRESH? "old:", y1, x1 // 10 34? "new:", y2, x2 // 10, 34

Classification:screen oriented output

Compatibility:The command is available in FlagShip only.

Translation:REFRESH()

Related:REFRESH(), SAVE/RESTORE SCREEN, RUN

CMD 277

REINDEXSyntax:

REINDEX [EVAL <expL1> [EVERY <expN2>]]Purpose:

Rebuilds all open indices in the current working area.

Options:EVAL <expL1> specifies a condition (similar to the WHILE <condition>, see thegeneral command description), that may be executed at a specific record intervalgiven by the EVERY <expN2> clause. The <expL1> must return TRUE to continuereindexing. The EVAL clause may be used, for example, to monitor the progress ofindexing, with a UDF. If <expN2> is not specified, the default value is one (eachrecord).

Description:REINDEX performs the same action as INDEX ON..., but uses the index criteriaalready stored in the index header. Therefore, if the index file is corrupted, or thedatabase structure was changed, the INDEX ON command should by used.

The REINDEX command is generally used to update indices which were notassigned to the database during its modification or appending. See also FlagShip'sintegrity checking in INDEX ON and INDEXCHECK().

REINDEX obeys the UNIQUE and ASCEND/DESCEND status as well as to theFOR <condition> as first created with INDEX ON. The current SET UNIQUEprogram status in not considered, but the stored status in the index header is usedinstead (see INDEX ON).

When REINDEX is finished, all current indices remain open, the ORDER is set to 1,and the database pointer is positioned to the first logical record.

Multiuser:Exclusive access to the required database must be acquired by USE...EXCLUSIVE.In a multiuser environment, the time-consuming REINDEX can be omitted entirely,if all relevant index files are always assigned to the open databases. To select therequired index file, use the SET ORDER command.

Example:USE employee INDEX nameREPLACE ALL salary WITH salary + 100SET INDEX TO id, birthdate, salary, nameREINDEX

CMD 278

Example:Report the percentage of the reindex process:

LOCAL count, perc := 0USE address NEW EXCLUSIVEcount := LASTREC()SET INDEX TO adrnameREINDEX EVAL mydisplay(perc++) EVERY INT(count/100)

FUNCTION mydisplay (out)@ 20,10 say "Reindexing, " + STR(out,3) + "% ready"RETURN .T.


Compatibility:The index structure depends on the used RDD. The default driver DBFIDX usesspecial index files named .idx, which are not compatible to Clipper's .NTX or dBASE.NDX files. The internal structures of the index files and the locking mechanism arenot compatible in these different dialects.

The EVAL and EVERY clause is new in FS4. Integrity checking is available with theFlagShip default driver only.

Translation:REINDEX => DBREINDEX()REINDEX [EVAL...] => ORDCONDSET (,,,, {||eval}, every)

ORDLISTREB ()

Related:INDEX, PACK, SET INDEX, SET EXCLUSIVE, SET UNIQUE, SET ORDER, USE,INDEXCHECK(), INDEXNAMES(), INDEXDBF(), ISDBEXCL(), oRdd:REINDEX()

CMD 279

RELEASESyntax 1:

RELEASE <memvarList>Syntax 2:

RELEASE ALL [LIKE | EXCEPT <skeleton>]Purpose:

Deletes specified PRIVATE and PUBLIC memory variables.

Arguments:<memvarList> is the list of variables to be deleted.

ALL deletes all visible variables in the dynamic scope.

<skeleton> is a wildcard mask (* and ? are supported) which specifies a group ofvariables to delete (ALL LIKE) or not to delete (ALL EXCEPT).

Description:The RELEASE command performs different actions, depending on how it isspecified:•On syntax 1, the most recently declared variables and arrays are deleted whether

PUBLIC or PRIVATE.•On syntax 2, the scope of deleting becomes the current procedure level, and it

can be narrowed if a wildcard is specified. Only PRIVATE and autoPRIVATEvariables created in the current procedure are affected; a NIL value is assigned tothe specified variables.

It is not necessary to RELEASE private (declared or automatic) variables beforeleaving a PROCEDURE or a FUNCTION. They will be released automatically.LOCAL, STATIC and TYPED variables are not affected by the RELEASEcommand. Local variables are released automatically when the procedure or UDFwhere the variables were declared terminates. Static variables cannot be releasedsince they exist for the duration of the program.

Example:PUBLIC v1,v2,v3,nameSTORE "John" TO v1,v2,v3,nameRELEASE ALL LIKE v*? TYPE("v1") && U? TYPE("name") && C

Compatibility:The behavior of the syntax 2 in FS and C5 differs slightly from and C87. In Flag-Ship, any number of variables is supported, so the RELEASE is not needed at all.

Related:CLEAR ALL, CLEAR MEMORY, PRIVATE, PUBLIC, RESTORE, SAVE, LOCAL,STATIC, GLOBAL

CMD 280

RENAME ... TOSyntax:

RENAME <file1> TO <file2>Purpose:

Gives a file a new name.

Arguments:<file1> is the name of the file to be renamed. Standard UNIX wildcards aresupported (see "man mv").

<file2> is the new name for the file. If only the path (except the dot . alone) isspecified, the file(s) from <file1> are moved to the path given in <file2>.

Both <file1> and <file2> can be given as parenthesed (<expC>). Both file nameshave to include the extension and can optionally be preceded by a path designator.

Description:RENAME is a file command that changes the name of a specified file to a newname, very similar to the UNIX command "mv". This command does not use SETDEFAULT and SET PATH settings.

If the <file2> exists, it is overwritten without any warning. The success or error maybe checked using DOSERROR() or FILE().

Both <file1> and <file2> (if they exist) must be closed before renaming or moving.Attempting to rename an open file will produce unpredictable results.

When a database file is RENAMEd it is also necessary to RENAME the associatedmemo file.

Example:? FILE("prices.dbf") && .T.? FILE("old.dbf") && .F.RENAME prices.dbf TO old.dbf? FILE("old.dbf") && .T.RENAME "[a-c]*.db*" TO /usr/myname && move them

The same action may be also done with:

RUN mv prices.dbf old.dbf RUN ("mv [a-c]*.db* /usr/myname 2>/dev/nul")


Compatibility:The RENAME command is equivalent to the UNIX command "mv" or the similarDOS command "REN". The usage of wildcards and the DOSERROR() checking isavailable in FlagShip only.

RENAME will be affected by the settings for the automatic path, pathnameconversion using e.g. FS_SET("pathlower") and FS_SET("lower"), the extension

CMD 281

replacement using FS_SET("translext") and the drive substitution using theenvironment variable x_FSDRIVE.

Related:COPY FILE, ERASE, RUN, DOSERROR(), FILE(), FS_SET(), UNIX: mv

CMD 282

REPLACE ... WITHSyntax:

REPLACE [<scope>][<alias> ->]<field1> WITH <exp1>[, <field2> WITH <exp2>,...][FOR <condition>] [WHILE <condition>]

Purpose:Puts the results of evaluating the given expressions into the specified databasefields.

Arguments:<field> is the name of the field to change. The field can be of any type.

<exp> is the expression to REPLACE with.

Options:<alias> has to be specified if a field belongs to a working area other than thecurrent one.

<scope> is the portion of the current database file to REPLACE. The default is thecurrent record. Specifying a <condition> changes the default to ALL.

FOR <condition> specifies the conditional set of records to REPLACE within thegiven scope.

WHILE <condition> specifies the set of records from the current record until thecondition fails.

Description:REPLACE is a database command that assigns new values to the contents of oneor more field variables in the current record in the specified working areas. Thetarget field can be character, date, logical, memo, or numeric. REPLACEautomatically updates all indices assigned to the specified working area.

REPLACE performs the same function as the assignment operator (:= or =) onaliased or as FIELD declared variables.

Note: replacing a field which is a part of the current index key expression maychange the relative position of the record within the index file. Therefore, replacing akey field within a <scope> (like REPLACE ALL or NEXT n or REST etc.) or withFOR/WHILE clause may be hazardous on such active index, because this will oftennot replace all expected records in the <scope>. The reason is the SKIP to nextrecord in <scope> according to the (permanently changed) index sequence order.The solution is the sequence n = INDEXORD() ; SET ORDER TO 0 ; REPLACE<scope> ... ; SET ORDER TO (n), or the similar but much less effective CLOSEINDEX, REPLACE <scope>... and then SET INDEX TO... plus REINDEX.

CMD 283

Sizes and Special characters:In "C" (character) fields, any string containing ASCII character values 0..255 isaccepted, also embedded zero (0x00) bytes. The size of character field is fix, themax size is 64 Kbytes. If <exp1> is longer than field size, the rest is silentlytruncated.

In "M" (memo) fields, any string containing ASCII character values 1..255 isaccepted, except the CHR(0) = 0x00 and CHR(26) = 0x1A characters, whichterminates the memo field. If these characters are used in the saved data, useMemoEncode() to store such strings in the memo field and MemoDecode() to readit from. The memo field is of variable size (in 512 bytes segments) and is per xBasespecs limited to 64 Kbytes (65536 bytes). If <exp1> is longer, RTE 301 occurs. Hint:if you need to store strings larger than 64kb, use two or more memo fields and splitthe <exp1> string via substr() to segments shorter than 64kb; on access simplyconcatenate them, see example below. An alternative is also to use the extended.dbv FlagShip memo field.

"VC*" are variable length fields, storing any text or binary data in a file of the samename as the database, with .dbv extension. The data may be stored compressed(by LZH or RLL algorithm) if the 3rd digit type is Z ("VCZ") or with settingSET(_SET_COMPRESS,.T.) Hard-CR chr(13,10) and soft-CR chr(141,10) areremoved from the string, except you set_aGlobSetting[GSET_L_REMCR_VCFIELD ] := .F. // default is .T.

In compressed storage, binary 0 and 0x1A are handled specially. If you wish toavoid this, set_aGlobSetting[GSET_L_BINARY0_VFIELD] := .F. // default is .T.

"VB*" are variable length fields, storing binary and BLOB data in a file of the samename as the database, with .dbv extension. The data may be stored compressed(by LZH or RLL algorithm) if the 3rd digit type is Z ("VBZ") or with settingSET(_SET_COMPRESS,.T.)

Multiuser:RLOCK() is required for replacing a single record, while FLOCK() or anEXCLUSIVE database when <scope> or <condition> is used. If a field of anotherworking area is replaced by specifying its alias, the corresponding record must alsobe locked with an alias->RLOCK(). If the database or record is not locked by theprogrammer, FlagShip invokes AUTORLOCK(), when SET AUTOLOCK is enabled(the default).


Example:USE employee NEW ALIAS emplUSE expenses NEW ALIAS exp INDEX exp_idSEEK empl->IdSELECT emplREPLACE name WITH exp->nameREPLACE Spent WITH Exp->Bus_fare + Exp->Dinner, ;

Text WITH Exp->Text

CMD 284

// or: FIELD->spent := Exp->Bus_fare + Exp->Dinner// empl->Text := Exp->Text

Example:Using long memo fields: String variables in FlagShip can contain up to 2 Gbytes,whilst the database Memo field is limited by the xBase specification to 64 Kbytes.To store larger data, use e.g.

DBCREATE("test", {{"IdNum","N",5,0}, {"Memo1","M",10,0}, ;{"Memo2","M",10,0},{"Memo3","M",10,0} })

USE testcLongStr := replicate("x", 163840) // 160 kbAPPEND BLANKREPLACE FIELD->Memo1 with LEFT (cLongStr, 65500) , ;

FIELD->Memo2 with SUBSTR(cLongStr, 65501, 65500) , ;FIELD->Memo3 with SUBSTR(cLongStr, 131001,65500)

...cLongStr := FIELD->Memo1 + FIELD->Memo2 + FIELD->Memo3? LEN(cLongStr) // 163840

Example:Typical example for multiuser/multitasking:

SET EXCLUSIVE OFF && set multiuser onSELECT 5USE address && see more: USE ...SET INDEX TO name

SEEK "Brown" && or user entryIF FOUND() && change data

xname = namexmid = midnamexcity = city

ELSE && new entryxname = SPACE(25)xmid = SPACE(30)xcity = SPACE(LEN(city))

ENDIF

@ 5, 0 SAY "Name " GET xname@ 5,40 SAY "Middle " GET xmid@ 6, 0 SAY "City " GET xcityREAD && lock not required

if lastkey() <> 27 && Esc key pressed ?if EOF()

APPEND BLANKWHILE NETERR(); APPEND BLANK; END

elseWHILE !RLOCK () ; END

endifREPLACE name WITH xname, midname WITH xmid, ;

city WITH xcityUNLOCK

endif

CMD 285


Compatibility:The automatic locking is not available in Clipper. FlagShip's autolock is similar toFoxPro and VO.

Translation:REPLACE exp1 WITH exp2 => _FIELD->exp1 := exp2REPLACE exp1 WITH exp2 [FOR, WHILE...] =>

DBEVAL({||_FIELD->exp1 := exp2 [_FIELD->exp...]}, ;[{for}], [{while}], [next], [rec], [.rest.] )

Related:APPEND, APPEND BLANK, JOIN, UPDATE, SET EXCLUSIVE, FIELD, MEMVAR,FLOCK(), RLOCK(), UNLOCK, COMMIT, oRdd:REplace(), oRdd:FIeldPut()

CMD 286

REPORT EDITSyntax:

REPORT EDIT <file>|(<expC>)Purpose:

Interactively creates or modifies reports for use with the REPORT FORM command.

Arguments:<file> is the file which holds the definition of the report. If the file does not exist, anew report is created, otherwise the stored one is modified. The default extension is.frm.

Description:If the <file> does not exist, a new .frm file is created, otherwise the available one ismodified. When executing the REPORT EDIT command, a full design screen for alabel appears:

myreport.frm F2:pg F3:column F4:group F5:fields F7:displ F10:save ESC:quit┌F2─────────────────────────────────────────────┐┌F3: column 1/25────────┐│ Page header line 1 : Extract from the ││ Expr: ADDRESS->IDENTN││ line 2 : for active cus ││ Head: Address ││ line 3 : ││ #2: Number ││ line 4 : ││ #3: ││ Page wide/high : 365 chars 65 lines ││ #4: ││ Margin left/right : 0 chars 0 chars ││ Wide: 8 ││ Double spacing/plain : F F ││ Deci: 0 Delete/Insert││ Eject begin/end : F T ││ Total F Add/Replace R│└───────────────────────────────────────────────┘└───────────────────────┘╔F4═════════════════════════════════════════════╗┌F5:ADDRESS.dbf─────────┐║ Group key (express.) : article ║│ IDENTNUN N 6 0 │║ header text #1 : article: &article ║│ COMPANY C 25 0 │║ #2 : ║│ CUST_NO C 10 0 │║ #3 : ║│ CUST_TYPE C 1 0 │║ #4 : ║│ ADDRESS C 25 0 │║ Summary/Eject : F / T ║│ STREET C 25 0 │║ Subgroup key (expr.) : ║│ CITY C 25 0 │║ header text #1 : ║│ ZIPCODE C 6 0 │║ #2 : ║│ TURNOV N 12 2 │╚═══════════════════════════════════════════════╝└────────────F6:next dbf┘┌F7──────────────────────────────────────────────────────────────────────┐│ ....,....1....,....2....,....3....,....4....,....5....,....6....,..││PgHd: Extract from the customer's database ││PgHd: for active custommers only ││GrHd:article: &article ││ ││Colm:[--1--] [-----------2-----------] [---3----] [4-] [-----------5----││TxtD:Address Company Custommer type Address ││TxtD:Number name Number ││Data: nnnnnn xxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxx x xxxxxxxxxxxxxxxxx││ │└────────────────────────────────────────────────────────────────────────┘(F4) enter group and sub-group data. CursUp/CursDn: move ENTER: confirm

CMD 287

The name of the report file is displayed at the top. If not available, you are promptedto "Retry", "Create", "AutoCreate" or "Quit", which lets you re-enter the correctname, create a new report or do that automatically, using the data out of thecurrently selected database.

You may choose to edit the desired REPORT part by pressing the correspondingfunction key. With F5/F6 you may select a database from the current or anotherworking area into the database window, or switch to the next database. From thiswindow you may overtake the field name and database alias over to the EXPR. fieldof the column window, when pressing RETURN.

With F7, you may view the current form of the REPORT with the whole datasummarized inside.

You may also choose to prepare the initial report automatically during creation. Thiswill overtake the first 25 fields of the currently selected database and automaticallyassign adequate column headers. The time to create a report may be reduced byusing this option

Example:Creates and prints a report

USE test2USE sales INDEX article NEWIF !FILE(salerep.frm")

REPORT EDIT salerep // create reportENDIFSEEK 1000IF FOUND()

REPORT FORM salerep TO PRINT ;FOR datesold >= DATE() -30 ;WHILE article <= 2000 NOCONS

ENDIF


Compatibility:The command is available in FlagShip only. To create/modify reports in dBASE III+,use CREATE REPORT; in Clipper the program RL.EXE can be used.

Source:available in <FlagShip_dir>/system/repoedit.prg

Translation:__REPOEDIT ("file")

Related:REPORT FORM, LABEL EDIT

CMD 288

REPORT FORMSyntax:

REPORT FORM <file1>|(<expC1>) [<scope>][FOR <condition>] [WHILE <condition>][TO PRINTER] [NOCONSOLE][TO FILE <file2>|(<expC2>) [ADDITIVE]][NOEJECT] [SUMMARY] [PLAIN][HEADING <expC3>] [MESSAGES <expA4>]

Purpose:Displays a formatted report defined in a .frm file.

Arguments:<file1> is the file which holds the definition of the report. The default extension is.frm.

Options:<scope> is the part of the current database file to report. The default scope is ALL.Either keywords or an expression can be specified.

<condition> specifies additional FOR or/and WHILE filtering; see the generalcommand description.

TO PRINTER: echoes output to a printer file. To disable the screen output, use SETCONSOLE OFF.

TO FILE <file2>: echoes output (ADDITIVE) to the specified file; see also thegeneral command description. Note that formfeed characters are not echoed to thefile. To include form feed characters to the file, execute SET PRINTER TO <file2>and use the clause TO PRINTER instead of TO FILE.

NOCONSOLE suppresses all REPORT FORM output to the console. If notspecified, output automatically displays to the console unless SET CONSOLE isOFF.

NOEJECT: Suppresses initial page eject when the TO PRINTER clause is used.

SUMMARY: In this case, REPORT FORM displays only total lines of groups,subgroups, and the grand total line. Detail lines are suppressed.

PLAIN: Suppresses the display of page headers. Moreover, the report title andcolumn headings are displayed only at the beginning of the report. If both PLAINand HEADING are specified, PLAIN takes precedence.

HEADING <expC3>: Heading is displayed at the top of each page. Note that<expC3> is evaluated only once at the beginning of the report before the recordpointer is moved. Up to three lines can be given, the semicolon ";" acts as the lineseparator.

CMD 289

MESSAGES <expA4>: User-defined messages printed during the REPORT FORMexecution. The messages are stored in an array[5], with the defaults:

array[1] := "Page Nr."array[2] := "* Subsubtotal *"array[3] := "** Subtotal **"array[4] := "*** Total ***"array[5] := "defined page has too few lines"

All messages have to be given to be accepted.

Description:The REPORT FORM executes a report the definition of which is stored in a .frm file.If a path is not specified, the file is searched in the current directory and then in theSET PATH directories. If not found, a run-time error occurs.

The current .frm is created using REPORT EDIT or RL.EXE of Clipper or CREATEREPORT of dBASEIII+.

REPORT FORM sequentially accesses records in the current working areadisplaying a tabular and optionally grouped report with page and column headings.

Multiuser:In a multiuser environment, no locking action is required. To ensure that the printeddata is not changed while REPORTing it, FLOCK() can be used.

Example:User break using the ESC key is possible.

LOCAL text := {"Page", "*", "", "TOTAL", ;"article.frm definition error"}

USE article INDEX nameREPORT FORM articles TO PRINT ;

WHILE INKEY() # 27 ;FOR YEAR(Publ_date) >= YEAR(DATE()) ;HEADING "Interesting Articles ;;" + ;

"I Read This Year ("+ STR(YEAR(DATE())) +".)" ;MESSAGES text NOCONSOLE


Compatibility:Report files .frm from Clipper or dBASEIII (binary transferred from DOS to UNIX)are supported. The clause NOCONSOLE is new in FS4, the clauses MESSAGESand ADDITIVE are available in FlagShip only.

Translation:__REPORTFORM ("file1", .print., "file2", .noconsole., ;

{for}, {while}, next, rec, .rest., .plain., ;"expC3", .noeject., .summary., expA4)

Related:REPORT EDIT, DISPLAY, LABEL FORM

CMD 290

REQUESTSyntax:

REQUEST <moduleList>Purpose:

Declare a module request list for the linker.

Arguments:<moduleList> is a list of external modules to be linked into the executable.

Description:In contrast to the similar EXTERNAL statement, which specifies a link request to anexternal procedure name, the REQUEST declarator specifies a request for amodule name, such as a .prg or a module declared by the ANNOUNCE statement.

As with EXTERNAL, the request command is used if some modules are not calleddirectly by their names (like DO...NAME or NAME()), but from within macros orINDEX key only. Also, if a .prg file contains only INIT/ EXIT PROCEDUREs, aREQUEST command elsewhere may be required to avoid a run-time error"unresolved external".

Example:*** file test.prg *** compiled by: FlagShip test*.prg -naREQUEST test5// or: EXTERNAL test2var := "test2"DO &varQUIT

*** file test1.prg ***ANNOUNCE test5 // new module namePROCEDURE test2? "being now in test2"RETURNEXIT PROCEDURE endproc // called by FlagShip only? "bye, bye"RETURN


Compatibility:Available in FS4 and C5 only.

Related:ANNOUNCE, EXTERNAL

CMD 291

RESTORE FROMSyntax:

RESTORE FROM <file>|(<expC>) [ADDITIVE]Purpose:

Retrieves PRIVATE and PUBLIC memory variables from a memory (.mem) file.

Arguments:<file> is a memory file to be read. If an extension is not specified, .mem isassumed.

Options:ADDITIVE: When specified, adds memory variables loaded from the memory file tothe existing pool of memory variables. Unless hidden via PRIVATE, memoryvariables with the same name are overwritten.

Description:The RESTORE command recreates the names and values of PUBLIC andPRIVATE variables previously saved to the <file> using the SAVE..TO command.Because the class and scope of the variables is not saved, the class of the restoredvariables depends on the ADDITIVE clause:

•If ADDITIVE is not given, all PUBLIC and PRIVATE variables are released(equivalent to the CLEAR MEMORY command) before the restored variables arecreated in the PRIVATE class.

•When the clause ADDITIVE is specified and the PUBLIC or PRIVATE variable ofthe same name is visible, the former value will be overwritten, but the classremains unchanged. Other, or the currently invisible variables will be created asPRIVATEs.

FlagShip also stores and restores PRIVATE and PUBLIC arrays and screenvariables, except when FS_SET ("memcompat", .T.) is specified.

LOCAL, STATIC and TYPED variables are unaffected by SAVE and RESTORE.Since the visibility of these variables has precedence, the restored variables of thesame name are invisible within the UDF or the STATIC scope, unless they arepreceded by the MEMVAR-> or M-> alias.

Example:Usage of variables, created in previous session:

PUBLIC test, colorsIF FILE("restvar.mem")

RESTORE FROM restvar ADDITIVEELSE

test := 25colors := {"W+/B", "R/N"}

ENDIF

CMD 292

IF FILE("screens.mem")RESTORE FROM screens ADDITIVERESTORE SCREEN FROM scr1

ENDIFSETCOLOR (colors[1])//SAVE SCREEN TO scr1SAVE ALL LIKE scr* TO screensSAVE ALL EXCEPT scr* TO restvarQUIT


Compatibility:Clipper's screen contents, stored in variables of type "C" cannot be directly used inFlagShip, which stores it in "S" variable types. Use the transfer functionsSCRDOS2UNIX() for such purposes. Note that a screen from one terminal can becorrectly re-displayed on the same terminal type only.

The content of the screen variables in Terminal i/o and GUI is not compatible toeach other. Screen variables in GUI mode cannot be converted via ScrDos2Unix()or ScrUnix2Dos().

Unlike Clipper, FlagShip also STOREs and RESTOREs the contents of arrays andscreen variables. Normally, the saved arrays and screens can also be read by theDOS dialects, since they simply ignore them. To avoid saving and restoring arraysand screens variables, set the compatibility switch FS_SET ("memcompat", .T.).

To transfer .mem files from/to DOS, a binary protocol must be used, see sectionSYS.

Translation:__MRESTORE ("file", .add.)

Related:SAVE, PRIVATE, PUBLIC, LOCAL, STATIC, GLOBAL, CLEAR MEMORY, SAVESCREEN, FS_SET()

CMD 293

RESTORE SCREENSyntax:

RESTORE SCREEN [FROM <memvar>]Purpose:

Displays a screen that has been saved to a memory variable.

Options:<memvar> is a screen variable to which the screen display was saved using theSAVE SCREEN command. This variable is of the type "S" and cannot be used forstring or arithmetic operations. It may however, be translated to a character typeand back, using SCREEN2CHR(), CHR2SCREEN() respectively. For manipulatingthe screen variable, see (EXT) _retscw().

If <memvar> is not specified, the screen display is saved and restored to/from aninternal variable which is overwritten each time a new screen is saved.

Description:RESTORE SCREEN is used for redrawing the whole screen that was saved withSAVE SCREEN. Normally, it is used to change a screen temporarily and return to itlater. Otherwise, the screen would have to be repainted. To STORE and RESTOREa part of the screen, the functions SAVESCREEN() and RESTSCREEN() should beused instead. Saving/restoring only the required part of screen will speed up theapplication visibly.

Example:USE authorsSAVE SCREEN TO myscreenREPORT FORM authorsRESTORE SCREEN FROM myscreen


Compatibility:To save the contents of a screen, FlagShip uses a variable of type "S" in contrast tothe Clipper's type "C", which is not binary compatible. Use the transfer functionsSCRDOS2UNIX() or SCRUNIX2DOS() when you need to save/restore the DOSstored screen contents. See _retscw() in chapter EXT if you need to manipulate thecontents of the screen variable. See also compatibility notes in RESTORE FROMcommand.

Translation:__XRESTSCREEN()

Related:SAVE SCREEN, SAVESCREEN(), RESTSCREEN(), SCREEN2CHR()CHR2SCREEN(), SCRUNIX2DOS(), SCRDOS2UNIX()

CMD 294

RETURNSyntax:

RETURN [<exp>]Purpose:

Terminates a procedure (UDP), function (UDF) or the entire program returningcontrol to either the calling procedure or the UNIX operating system.

Arguments:<exp> is an expression of any type that evaluates to the return value for a user-defined function. If not specified, the UDF returns NIL.

Description:In a procedure (UDP) or function (UDF), FlagShip releases all PRIVATE,autoPRIVATE and LOCAL variables created there and returns to the callingprocedure. When RETURN is executed at the highest level, control is passed toUNIX.

There can be more than one RETURN in a UDP or UDF. RETURN (NIL) is alsoassumed when reaching another PROCEDURE or FUNCTION command, or theend-of-file.

The RETURN statement passes control only one level up, to the calling procedure.However, using the BREAK command it is possible to jump more than one level ata time, into the next BEGIN SEQUENCE...END structure. This is similar toRETURN TO MASTER of dBASE, but more flexible.

Example:FUNCTION myudf (par1, name, par3)? nameRETURN par1 + par2

PROCEDURE myudpPARAMETERS par1, name, par3, retpar? nameretpar = par1 + par2 // passes back by paramRETURN


Compatibility:In an UDF, FlagShip accepts a RETURN without an <exp>, returning NIL. Clipperrequires a given return value.

Related:CANCEL, QUIT, BEGIN SEQUENCE, FUNCTION, PROCEDURE

CMD 295

RUNSyntax:

RUN [WAIT|NOWAIT] [MESSAGE <expC1>]<UNIX command|Windows command>|(<expC2>)

or:! [WAIT|NOWAIT] [MESSAGE <expC1>]

<UNIX command|Windows command>|(<expC2>)Purpose:

Executes UNIX or Windows command, program or script within the currentapplication. This allows the use of the power of UNIX and Windows commands andshell. In MS-Windows, RUN executes internal CMD commands and .exe, .com or.bat files.

Arguments:<UNIX|Windows command> may be any executable program or script within thepath. Any character expression has to be enclosed in parentheses. Macroexpressions can also be used and will be expanded before submitting the commandto the shell. In Windows, you may execute internal CMD commands (like VOL, DIR,COPY etc.) via RUN "CMD /C command.." but FlagShip will precede the commandstring by "CMD /C " automatically (for internal shell commands only), if not disabled,see section "Tuning" below. You should use parenthesed expression (expC2)instead of command constant, when the command/expression contain backslashesor spaces.

Options:WAIT or NOWAIT: optional modifier. With WAIT (default), the application will waituntil the command will finish. NOWAIT will trigger the command to background andcontinue execution of the application. NOWAIT is similar to Unix command"shell_call &". Do not use WAIT/NOWAIT clause together with the "&" postfix.

MESSAGE <expC1> is an optional, user defined message to be printed on thescreen, when the executed UNIX command is finished. Note, no FlagShip outputmapping is active when the MESSAGE is printed; it works as does the "echo<expC1>" from the UNIX shell would. Before <expC1> is printed, a NEW LINE isexecuted (similar to the WAIT command).

Note that both options, if any given, needs to precede the command.

Return code:The return code may be checked via DosError() function. Note: this return code issystem dependant and correspond to the return value of system function system()or of errno if system() returns -1. On some oper. systems, you will get the true exitcode by calculating nRet := int(DosError() / 256)

CMD 296

Description:At RUN command, FlagShip invokes a new shell and passes it the UNIX orWindows command to be executed. The required command must be available inthe current path or else given with an absolute path.

When the <Unix/Windows command> ends (or when the background process isstarted by "&" postfix or by NOWAIT clause), the control returns back to theapplication, executing the next FlagShip statement.

In MS-Windows, the RUN accepts Windows-Commands and EXE files by the sameway as in Unix, using the CMD shell. When the path or file name contain spaces,you need to enclose the corresponding parameters in quotas, see example below.You need to specify fully qualified name including drive and path, when the path ofthe given executable is not included in the current Windows PATH environmentvariable.

To allow the output from the program called to be inspected, print a prompt (usinge.g. the MESSAGE clause or the equivalent "; echo..." statement) and stop furtherexecution with INKEY(0) after the RUN command; see example.

Shell access: You may run a shell by specifying the argument "sh" (or "csh", "ksh"respectively) to the RUN command. To exit the shell, type "exit". In MS-Windows,invoke CMD or COMMAND for that reason.

Background processing: the executable or script called may run in background, ifthe RUN command specification ends with an ampersand (&) character or by usingthe NOWAIT clause. The current application will not wait for the called executableto finish, but will carry on with its own execution immediately. The program calledbecomes a child of the calling executable and will terminate latest when the currentapplication terminates. Applicable in Unix/Linux only. Note that any input to, oroutput from the background program may cause the called application to hang.

User break: when the program called is a FlagShip application, both programs willreceive the break and debug signals (^K and ^O).

Environment variables: cannot be set from a RUN command, since they are localto the executing subprocess and do not affect the calling application. UseFS_SET("setenv") instead. The current PATH environment variable is used tosearch for the executable, when the command does not include path.

Screen output: in Terminal i/o mode, the output goes to the screen and is handledby the curses library, as described in section SYS. This library optimizes the currentoutput stream. If the by RUN called programs produce any screen output, it will bethereafter "invisible" for the curses buffer from the calling FlagShip application. Also,the new cursor position is not conveyed to the calling application; the screen outputbecomes undefined (for the curses library). To synchronize the physical screen withthe current application, execute any of the REFRESH, [@..]CLEAR..,RESTSCREEN() or SCROLL() functions after RUN.

In Basic i/o mode, the output from the by RUN called programs goes to stdout orstderr.

CMD 297

In GUI mode, the output from the called program goes to stdout or stderr, which isusually assigned to the console (or console window) and hence does not affect thecurrent screen.

Compatibility note: since the Unix and MS-Windows commands usually differsfrom each other, you may use#ifdef FS_WIN32

RUN Windows-Command...#else

RUN Unix-Command...#endif

Tuning:If an error occurs, it is displayed as run-time-error. You may disable this byassigning_aGlobSetting[GSET_L_RUNRTERROR] := .F. // default = .T.

You may display the full RUN command & time on console by assigning_aGlobSetting[GSET_L_RUNDISPLAY] := .T. // default = .F.

To disable the detection of internal CMD commands (in FlagShip for MS-Windows)and avoid it automatic prefacing by "CMD /C ", set_aGlobSetting[GSET_L_WINCMDDETECT] := .F. // default = .T.

Example:Execute a simple UNIX or DOS/Windows program:

SAVE SCREEN#ifdef FS_WIN32

RUN ("CMD /C dir *.prg | more") // MS-WindowsWAIT

#elseRUN MESSAGE "press any key..." ls -l *.prg | pg // Unix// or: RUN ("ls -l *.prg | pg ; echo press any key...")INKEY (0)

#endifRESTORE SCREEN

Example:To pass the output into file and omit restoring the screen, you may alternatively usee.g.:

#ifdef FS_WIN32RUN ("dir *.prg >temp.txt 2>&1")

#elseRUN ("ls -l *.prg >temp.txt 2>&1")

#endifTYPE temp.txt

CMD 298

Example:Execute another FlagShip program "prg2.out" in the background, which creates afile prg2.txt containing return values on exit:

IF FILE("prg2.txt")ERASE FILE prg2.txt

ENDIFRUN ("prg2.out par1 par2 &") // execute prg2 with param

WHILE .not. FILE("prg2.txt")INKEY(3)? "waiting for prg2 to be finished"

ENDDOvalues = MEMOREAD ("prg2.txt") // get results

Example:Invoke MS-Word with available document in the Windows version of FlagShip. Notethat the command and/or parameters must be enclosed in quotas when the path orfile name include spaces (which would be otherwise interpreted byCMD/COMMAND as parameter delimiter). Hint: handle RUN in the same way aswhen you invoke an executable at command line level.

#ifndef FS_WIN32? "use OpenOffice, StarOffice or Koffice instead of MS-Winword"

#elseRUN "C:\Program Files\Microsoft Office\Office\WinWord.EXE " ;"D:\Documents and Settings\Default User\My Documents\Letter.doc"? "Word executed with return code", ltrim( doserror() )

#endifwait

// or alternatively:

cFile := "My Letter.doc"// cExe:= "Notepad" // CMD.EXE searches for .EXE|.COM|.BAT via PATHcExe := '"C:\Program Files\Microsoft Office\Office\WinWord.EXE"'cParam := '"D:\Documents and Settings\Default User\' + ;

'My Documents\' + cFile + '"'cCmd := cExe + " " + cParam

? "Executing CMD/COMMAND:"? "X:>", cCmd

RUN (cCmd)

wait "... with success/err " + ltrim(doserror()) + ", any key..."

CMD 299

Example:Start MS-Word (Winword) in Windows as sub-process, continue processing of theapplication. Note the notification of path and/or file name including spaces: theexecutable (with path) and/or the file name needs to be passed to Windowsenclosed in double quotas. When the command uses variables, enclose it inparentheses.

? "Invoking MS-Word as separate process..."RUN NOWAIT ;

'"C:\Program Files\Microsoft Office\Office\Winword.exe" /w'if doserror() != 0

? "could not invoke Word, CMD return code =", ltrim(doserror())? " =", doserror2str()

else? "Word is active, exit it separately (before exit application)"

endif

// or alternatively:cCommand := '"C:\Program Files\Microsoft Office\' + ;

'Office\Winword.exe"'cDocFile := '"D:\Documens and Settings\Default User\' + ;

'My Documents\letter.doc"'RUN NOWAIT (cCommand + " " + cDocFile)

Example:Execute a time consuming UNIX command in background, omit error output, obtainits data later:

LOCAL ii := 0, textFERASE("find.ready")

// trigger Unix find command in backgroundRUN "(find / -name '[k-m]*.prg' -print > find.data " + ;

" 2>/dev/null ; touch find.ready)&"

// now, continue the program execution,// e.g. allow an user input// or display the system is working:@ 5, 0 SAY "Searching"DO WHILE .NOT. FILE("find.ready") .and. INKEY() != 27

@ 5, 10 SAY substr("\|/-", (ii++ % 4) +1, 1)ENDDO// display data from the background job:

IF LASTKEY() != 27* @ 5, 10 SAY "READY"* TYPE find.data// --- or use the more comfortable: ---

@ 5, 0 SAY "Scroll by PgDn,PgUp. Continue with ESC"text := MEMOREAD("find.data")IF LEN(text) < 10

text := "***** No data for [k-m]*.prg found *****"ENDIFMEMOEDIT (text, 7,0, MAXROW() -1, MAXCOL(), .F.)

ENDIFFERASE("find.ready")

CMD 300

Example:For true inter-process communication, see also the example in the section EXT.

Classification:system call

Compatibility:As opposed to the equivalent DOS execution, there are practically no limits to usingRUN on UNIX and in MS-Windows/32. If the available RAM space is insufficient,the additional swap disk area will be used automatically.

Keep in mind the differences in system command names on DOS and UNIX (lsinstead of DIR etc.) and the different DOS vs. UNIX screen handling. For portability,#ifdef FlagShip.. ..#else...#endif or the PUBLIC FLAGSHIP variable can be used.

The MESSAGE clause is new in FS4, WAIT/NOWAIT in FS6 and both are notavailable in Clipper.

Translation:__RUN ("expC2" [, "expC1"] )

Related:REFRESH, REFRESH(), CLEAR SCREEN, SAVE/RESTORE SCREEN

CMD 301

SAVE TOSyntax:

SAVE TO <file>|(<expC>)[ALL [ LIKE | EXCEPT <skeleton>]]

Purpose:Saves PRIVATE and PUBLIC memory variables to a memory (.mem) file.

Arguments:<file> is the name of the file where the specified memory variables are saved. If noextension is specified, the file is created with a .mem extension.

Options:ALL saves all visible dynamic (PRIVATE and PUBLIC) variables. This is the defaultsetting, if no other clause is specified.

ALL LIKE <skeleton> defines a set of visible PRIVATE and/or PUBLIC variables tobe saved.

ALL EXCEPT <skeleton> defines a set of visible PRIVATE and/or PUBLICvariables not matching the <skeleton> to be saved.

<skeleton> is a wildcard mask (* and ? are supported) which specifies a group ofvariables for the ALL LIKE or EXCEPT clause. The wildcard character "*" matchesany group of adjacent characters. The wildcard character "?" matches any singlecharacter and can be specified anywhere within the <skeleton>.

Description:The specified memory variables are copied to the memory file without regard totheir scope (PUBLIC or PRIVATE).

FlagShip also stores and restores PRIVATE and PUBLIC arrays and screenvariables, unless the FS_SET("memcompat", .T.) was specified.

LOCAL, STATIC and TYPED variables are unaffected by SAVE and RESTORE.

Example:PRIVATE var1 := 1, var2 := "two"PUBLIC var3 := .T., var4 := date()LOCAL var5 := "test"abc := "autoprivate"

DO myPROC WITH var5

PROCEDURE myPROCPARAMETERS var_parLOCAL var1, var4 // does not affect SAVE TOSAVE TO testsav1 ALL LIKE var* // var1..5, var_parSAVE TO testsav2 // abc, var1..5, var_parRETURN

CMD 302


Compatibility:FlagShip stores the screen contents in "S" variable types, which is not compatible toClipper's variables of type "C". Use the transfer functions SCRDOS2UNIX() orSCRUNIX2DOS() for such purposes. Note that the screen from one terminal canonly be correctly re-displayed on a terminal of the same type having the same valuein the TERM environment variable.

The content of the screen variables in Terminal i/o and GUI is not compatible toeach other. Screen variables in GUI mode cannot be converted via ScrDos2Unix()or ScrUnix2Dos().

Unlike Clipper, FlagShip also STOREs and RESTOREs the contents of arrays andscreen variables. Normally, the saved arrays and screens can also be read by theDOS dialects, since they simply ignore them. To omit saving and restoring arrayand screen variables, set the compatibility switch FS_SET ("memcompat", .T.).

To transfer .mem files from/to DOS, a binary protocol must be used, see sectionSYS.

Translation:__MSAVE ( "file", "skeleton", .like. )

Related:RESTORE FROM, PRIVATE, PUBLIC, LOCAL, STATIC, GLOBAL, FS_SET(),CHR2SCREEN(), SCREEN2CHR(), SCRDOS2UNIX(), SCRUNIX2DOS()

CMD 303

SAVE SCREENSyntax:

SAVE SCREEN [TO <memvar>]Purpose:

Saves the current screen contents to a screen variable.

Options:TO <memvar> specifies a variable to which the display screen was saved, andfrom which it will be RESTOREd. This variable is of the type "S" and cannot beused for string or arithmetic operations. The variable can be of any storage classincluding LOCAL, STATIC, or an array element. To store it to a character or memoFIELD and back, use the translation SCREEN2CHR() or CHR2SCREEN()respectively. On how to manipulate the screen variable, see (EXT) _retscw().

If this clause is not specified, the screen display is saved to an internal variablewhich is overwritten each time a new screen is saved.

The content of the screen variables in Terminal i/o and GUI is not compatible toeach other. Screen variables in GUI mode cannot be converted via Screen2chr()nor Chr2screen() but will be stored to memory variable by the same way as inTerminal i/o mode. See additional description about screen variables in theSaveScreen() function.

Description:SAVE SCREEN is used in conjunction with RESTORE SCREEN to avoid repaintingan original screen that has been temporarily replaced. The command is a synonymfor the SAVESCREEN(0, 0, MAXROW(), MAXCOL()) function.

To STORE and RESTORE a part of the screen, the functions SAVESCREEN() andRESTSCREEN() should be used instead.

All the current visible characters, colors, attributes and the cursor position is savedand will be faithfully redisplayed. For "odd output" from RUN programs or othersessions etc., see the (CMD) REFRESH command.

In GUI mode, you may compress the resulting image size by setting SETSCRCOMPRESS ON. However, the compressed image may loose some precisionat RESTORE, similarly to compressing of jpeg files.

Example:USE authorsSAVE SCREEN TO Scr1CLEARREPORT FORM authorsWAITRESTORE SCREEN FROM Scr1USE

CMD 304


Compatibility:For saving a screen contents, FlagShip uses the variable of type "S" as opposed tothe Clipper's type "C", which is not binary- compatible. Use the transfer functionsSCRDOS2UNIX() or SCRUNIX2DOS() for such purposes. See also compatibilitynotes in the RESTORE FROM command.

Translation:__XSAVESCREEN()

Related:RESTORE SCREEN, CHR2SCREEN(), RESTSCREEN(), SAVESCREEN(),SCREEN2CHR(), SCRDOS2UNIX(), SCRUNIX2DOS()

CMD 305

SEEKSyntax:

SEEK <exp> [SOFTSEEK]Purpose:

Seeks through an index file until the first key matching the given expression isfound.

Options:SOFTSEEK overrides the current SET SOFTSEEK state, and executes the SEEKas if SOFTSEEK were ON.

Arguments:<exp> is an expression to be matched with the index key of the currently activeindex file (controlling index). The scope is ALL (the search starts with the first logicalrecord).

If SET ANSI is set ON, or SET DBREAD is set to ANSI, the <exp> is translatedautomatically by Ansi2oem(). See also examples/setansi.prg with additional hints.

Description:Searching of the controlling index starts from the first key. If a match is found, therecord pointer is positioned to the record number found in the index and FOUND()returns TRUE, EOF() returns FALSE.

When the searched value is not found, the current state of SET SOFTSEEK affectsthe returned from FOUND(), EOF() and the position of the record pointer:

•If SOFTSEEK is OFF (the default), FOUND() returns FALSE, EOF() returnsTRUE, and the database is positioned at eof = LASTREC() +1.

•If SOFTSEEK is ON, and there are keys with a value greater than the searchedargument, the database pointer is positioned to the first record with a greater keyvalue, FOUND() returns FALSE and EOF() returns FALSE.

•If SOFTSEEK is ON, and there is no key with a value greater than the searchedargument, the database is positioned at eof = LASTREC() +1, FOUND() returnsFALSE and EOF() returns TRUE.

The SET DELETED and SET FILTER switch/condition is considered. The currentstate of SET EXACT does not affect the search; the comparison is the same as withSET EXACT OFF.

SEEK is identical to FIND, but has a slightly different syntax: FIND &<var> isidentical to SEEK <var> or FIND (<var>) is identical to SEEK <var>.

For a more complex SEEK search, the SEEK EVAL command may be used.

CMD 306

Example:To list all employees whose last name is "Clifton"

USE employee INDEX name, zipSEEK "Clifton"IF FOUND()

LIST REST Firstname, Lastname, Birthdate;WHILE Lastname = "Clifton" .and. ;

INKEY() != 27ENDIF

SET SOFTSEEK ONSET ORDER TO 2 // index: zipSEEK 12345 // 12345 and aboveSET SOFTSEEK OFFIF FOUND()

? "zip code 12345:", cityELSEIF .NOT. EOF()

? "next zip code to 12345 =", zip, ":", cityELSE

? "address for zip code 12345 and up not available"ENDIF


Translation:DBSEEK (exp)

Related:FIND, SEEK EVAL, INDEX, LOCATE, REINDEX, SET DELETED, SET EXACT,SET INDEX, SET SOFTSEEK, USE, EOF(), FOUND(), RECNO(), oRdd:Seek()

CMD 307

SEEK EVALSyntax:

SEEK EVAL <expB>Purpose:

Seeks through an index file until the evaluated code block returns TRUE.

Arguments:EVAL <expB> is a code block, which performs some comparisons with the indexkey of the controlling index. The scope is REST (the search starts with the currentrecord).

Description:By using SEEK EVAL, a complex search (like substring etc.) in the index file can beperformed. It is similar to the LOCATE command, but significantly faster, since thedatabase record is read during the search process on request only (e.g. when afield name is specified in the code block body). Of course, the database pointer ispositioned correctly latest at the end of the search.

The search of the controlling index starts with the current record and continues untilthe <expB> code block returns TRUE or until end-of-file.

The code block receives the current index key, and the corresponding recordnumber as parameters in that order, and must return logical FALSE to continue thesearch or TRUE to stop.

If a match is found, the record pointer is positioned to the record number found inthe index and FOUND() returns TRUE, EOF() returns FALSE.

When the searched value is not found, FOUND() returns FALSE, EOF() returnsTRUE, and the database is positioned at eof = LASTREC() +1.

The current SET SOFTSEEK state does not affect the SEEK EVAL command. TheSET DELETED and SET FILTER switch/condition is considered. The current SETEXACT state affects string comparisons within the code block.

Note, the scope is REST (i.e. starting from the current record). For the firstcomplete search, the record pointer has to be positioned to the first logical recordusing GOTO TOP. To continue the search, use SKIP prior to issuing the SEEKEVAL command.

The sequence GOTO TOP; SEEK EVAL {|key| key=exp} is equivalent to SEEK exp, but the latter is executed faster.

The database record pointer (LASTREC()), if used in the code block, delivers therecord number before SEEK EVAL was started. Use the second code blockparameter to determine the correct record number.

CMD 308

Example:To find a name entered in any order

LOCAL seekname := "Smith", maxrec := lastrec()LOCAL seekblock := {|key, recno| ;

UPPER(seekname) $ key .AND. ;!deleted() .AND. recno < maxrec}

USE address NEWINDEX ON UPPER(name) TO adrnameLIST name FOR UPPER(seekname) $ UPPER(name) // slow* 5 John Smith* 9 Peter Smith* 12 Peter & Paul Smith Corp.* 36 Smith and Partner Ltd.

GOTO TOPSEEK EVAL seekblock // 5 John SmithWHILE ! EOF()

? RECNO(), nameSKIPSEEK EVAL seekblock // 9 Peter Smith (etc.)

ENDDO


Compatibility:Available in FlagShip (with the default DBFIDX driver) only

Translation:_SEEKEVAL (expB)

Related:SEEK, FIND, INDEX, LOCATE, CONTINUE, SKIP, oRdd:SEEKEVAL()

CMD 309

SELECTSyntax:

SELECT <workArea>|(<expN>)or:

SELECT <alias>|(<expC>)Purpose:

Changes the current working area.

Arguments:<workArea> is a number between zero and 65534. If zero is specified, the lowestavailable working area without an open database is selected. The argument can bespecified as a numeric expression (<expN>) enclosed in parentheses (not to beconfused with the equivalent SELECT() function syntax).

<alias> is the ALIAS name of the working area containing the opened database filewith the same name or alias. The alias can be specified as a character expression(<expC>) enclosed in parentheses.

Description:In FlagShip, 65534 working areas are available for simultaneously open databases.The ALIAS of a working area is automatically assigned when a database file isopened by the USE command.

A zero argument selects the first unused working area, similar to the USE...NEWclause.

FlagShip supports the direct usage of the <alias>-> selector in assignments,expressions and function calls, which is equivalent to SELECTing the requiredworking area, see also section LNG.2.9 and LNG.2.3.2:

USE address ALIAS addr NEW ; act := SELECT()SELECT 15USE other

* ---- aliased ------- * ---- is equivalent to ---------addr->name := xyz SELECT addr

FIELD->name := xyzSELECT other

? adress->(EOF()) SELECT addr; ? EOF() ; SELEother("ad"+"dr")->(MyUdf(1)) SELECT addr; MyUdf(1); SELE other15->(MyUdf(2)) SELECT 15 ; MyUdf(2); SELE other

CMD 310

Each working area has the following attributes:

Attribute/Action Retrieving Command/FunctionOpen/close work area USE, CLOSE DATAIndices USE..INDEX, SET INDEXRelations SET/CLOSE RELATIONFiltering SET FILTER, SET DELETEDSearching SEEK, LOCATE, FINDMoving GOTO, SKIP

Alias name ALIAS()Database file DBF(), INDEXDBF()Working area no. SELECT()Index file ext, names INDEXEXT(), INDEXNAMES()Index key, contrl.no. INDEXKEY(), INDEXORD()Index integrity INDEXCHECK()Record number RECNO()Record count LASTREC(), RECCOUNT()Field count FCOUNT()Field name FIELD()Field description AFIELDS()Beginning-of-file flag BOF()End-of-file flag EOF()Filter condition DBFILTER(), DELETED()Locate/Seek result FOUND()Relation DBRELATION(), DBRSELECT()Header size HEADER()Network cmd result NETERR()Locking RLOCK(), FLOCK(), UNLOCK, AUTOxLOCK(), SET AUTOLOCK

Multiuser:When performing operations on the SAME physical database (used con- currentlyin different working areas), see chapter LNG.4.8.7. When SET AUTOCOMMIT isON (default is OFF), every SELECT will also commit (flush) the current work areaphysically to hard disk, same as COMMIT.

Example:old_area = SELECT()SELECT 0USE magazine ALIAS mag && or: USE...NEW// other statementsmag_select = SELECT()SELECT (old_area)// other statementsSELECT (mag_select) && or: SELECT mag


CMD 311

Compatibility:FlagShip supports 65534 working areas simultaneously, Clipper and VO up to 250,dBASE up to 10 or 40.

Translation:DBSELECTAREA (expN | expC)

Related:USE, SET INDEX, ALIAS(), SELECT()

CMD 312

SET ALTERNATESyntax 1:

SET ALTERNATE TO [<file>|(<expC>) [ADDITIVE] ]Syntax 2:

SET ALTERNATE on|OFF|(<expL>)Purpose:

Echoes console output (e.g. of the ?/?? commands) to an ASCII text file.

Arguments:TO <file> is the name of an ASCII text file to which the output will be redirected andcan include a path and an extension. If the file extension is not specified, .txt isassumed. When the TO... clause is not given, the currently open alternate file (ifany) will be closed.

Option:ADDITIVE causes the specified alternate file to be appended to instead ofoverwritten. If not specified, the specified <file> is truncated.

Arguments:ON/OFF activates or deactivates the output to the current open alternate file. Thetoggle will not be switched to ON if the alternate file is not opened. Alternatively, theparenthesized <expL> may be used, whereby logical TRUE is the same as ON.

Description:FlagShip allows to redirect console command output (such as ?, LIST, REPORTFORM, LABEL FORM) to four different devices/files at a time: the SCREEN device,and the ALTERNATE, PRINTER and EXTRA files or devices.

In commands, which support the TO FILE <file> clause (like LIST, REPORT FORMetc.), these clauses perform a similar function as SET ALTERNATE. In othercommands (like ?, ??, QOUT() etc.), an additional redirection to a text file (ordevice) using the SET EXTRA command is possible.

Full-screen commands such as @...SAY cannot be echoed to by the SETALTERNATE or EXTRA command; use SET DEVICE instead.

By setting the output OFF, the alternate file remains open. Closing the alternate fileusing SET ALTERNATE TO or CLOSE ALTERNATE will reset the toggle to OFF.Only one alternate file may be opened at the same time.

Tuning:You may set the new-line character by 8th element in FS_SET("prset") e.g.

#ifdef FS_WIN32 /* here: should apply for Windows only */FS_SET("prset", {NIL,NIL,NIL,NIL,NIL,NIL,NIL,chr(13,10) } )

#endifbefore printing to ALTERNATE file via ? or QOUT(). The default setting is line-feed= chr(10).

CMD 313

Example:SET ALTERNATE TO protocol.doc && or: TO /dev/lp1SET ALTERNATE ONUSE publishDO WHILE .NOT. EOF() .AND. INKEY() # 27

? Name, Address, Zip, TownSKIP

ENDDOSET ALTERNATE TO


Compatibility:The ADDITIVE clause is new in FS4.

Translation:SET ( _SET_ALTERNATE, .on.)SET ( _SET_ALTFILE, "file", .additive.)

Related:?, ??, DISPLAY, LIST, LABEL FORM, REPORT FORM, TEXT, TYPE, QOUT(),QQOUT(), SET EXTRA, SET PRINTER, SET()

CMD 314

SET ANSISyntax:

SET ANSI on|OFF|(<expL>)Purpose:

Change the behavior how to read from and store data into database.

Arguments:ON/OFF activates or deactivates the automatic translation of ANSI <-> PC8character set. The logical value .T. correspond to ON, .F. is the same as OFF.Default value is OFF.

Description:With SET ANSI ON or SetAnsi(.T.), a database access of character or memotranslates the PC8/ASCII/OEM charset via Oem2Ansi() into ANSI/ISO charset(used for display in GUI mode or in X11 terminal without a corresponding mapping).On replacing a char or memo fields in the database, the reverse Ansi2oem()translation is taken.

This means, special characters like a-umlaut, stored in the database as chr(132) inPC8/ASCII/OEM charset are translated during a read access to chr(228) inANSI/ISO charset, to be displayed on the screen as a-umlaut in GUI environment oron X terminal. Reverse, with SET ANSI ON or SetAnsi(.T.), the a-umlaut chr(228)available in a variable or given in input, is stored in the dbf as chr(132) during thereplace stage.

Note: both the FS4 and Clipper always use PC8/ASCII charset in the database, i.e.chr(132) for a-umlaut.

Example:See examples/setansi.prg for a complete example with description



Related:SET SOURCE, SetAnsi(), SET DBREAD, SET DBWRITE, Ansi2oem(),Oem2Ansi(), SET KEYTRANSL|CHARSET,

CMD 315

SET AUTOCOMMITSyntax:

SET AUTOCOMMIT on|OFF|(<expL>)Purpose:

Sets or disables an automatic COMMIT on UNLOCK and SELECT commands andcorresponding DbUnlock() and DbSelect() functions.

Arguments:When specified ON, an automatic COMMIT will be enabled, which then flushes thedatabase (and indices) changes physically to hard disk at every UNLOCK andSELECT command or at DbUnlock() and DbSelect() function.

OFF (the default) disables the automatic commit.

<expL> is optional parenthesized logical value or expression, where .T. isequivalent to ON, and .F. to OFF

Description:In multi-user mode, the changes in the database and indices are usually hold inoperating system buffer and written physically to the hard disk by the COMMITcommand or DbCommit() function.

FlagShip can perform this action automatically when SET AUTOCOMMIT is ON.But since this may slow-down the performance significantly, the default setting isOFF.


Compatibility:Available in FlagShip only.

Translation:SET ( _SET_AUTOCOMMIT, <expL> )

Related:SET(), COMMIT, SELECT, UNLOCK

CMD 316

SET AUTOLOCKSyntax 1:

SET AUTOLOCK [TO] <expN>Syntax 2:

SET AUTOLOCK ON|off|(<expL>)Purpose:

Sets or disables the placement of an automatic record or file lock during a databasewrite access in shared mode.

Arguments:<expN> sets the period (in seconds), for which to attempt to successfully executethe automatic Rlock or Flock. Attempts are done in one second intervals. Thedefault <expN> period is 10 (seconds). Possible values for <expN> are:

0 auto locking is enabled, the AUTOxLOCK() function tries to lock the databaseforever, until it succeeds.

>= 1 auto locking is enabled, the AUTOxLOCK() function tries to lock the databasesuccessfully for <expN> seconds. If not successful within this period, the usermay choose the action to follow in a communication window, i.e. to try again,break, ignore (mostly resulting in a subsequent run-time error), or to exit.

- 1 is equivalent to 0, for FoxPro compatibility.

- 2 is equivalent to 0, for FoxPro compatibility.

- 3 and all values < -3: the auto locking is disabled.

ON/OFF is a shortcut of the syntax 1, while ON is equivalent to ...TO 10 (or the lastpositive value previously set), while OFF is equivalent to ...TO -3. The default is ON.When using the alternative parenthesized <expL>, TRUE is the same as ON.

Description:When a database is open in SHARED (multiuser) mode, any writing accessrequires a record or file lock. Usually, the programmer controls these locks himself,by using the RLOCK() and FLOCK() functions and the UNLOCK command.

For your convenience, FlagShip RDD drivers can manage these locks themselves,if the lock was not already issued by the programmer and SET AUTOLOCK switchis active (the default).

In this case, the database driver calls the function AUTORLOCK() orAUTOFLOCK() respectively before the database write access, andAUTOUNLOCK() thereafter to release this lock and COMMIT the database. Youmay modify these functions, available in source code in the <FlagShip_dir>/system/autolock.prg file, e.g. to display waiting messages, manage the defaultBREAK, protocol the "unexpected" locks etc. If a modification is required, copy this

CMD 317

file to your local directory; then compile and link it according to the instructionsgiven in the source - or simply set a global switch in your application, see Tuningbelow.

Note, that SET AUTOLOCK is a global switch, valid for all databases, as opposedto the local oRdd:CONCURRENCYCONTROL instance of the DataServer class.

Performance hints, transactions:Of course, this autolock mechanism is not so effective, as when the programmercontrols the flow by RLOCK()...UNLOCK, FLOCK() ... UNLOCK or by explicitlyinvoking the AUTOxLOCK() ... AUTOUNLOCK() functions. This is because theprogrammer usually invokes only one lock attempt for multiple field replacementson the same record. On the other hand, the AutoLock functions have to perform(the same) lock and unlock (including Commit) for every field replacement.Therefore, your application may be faster when your program controls the locksitself, the Auto*Lock feature can be viewed as the "emergency break" to avoid run-time errors. Also, transactions can only be controlled by the programmerhim/herself, through locking all required databases before the updates start.

Of course, if the AUTOLOCK is active, you may manually invoke the AUTO-RLOCK() instead of RLOCK() and AUTOFLOCK() instead of FLOCK(), to controlthe program flow in the same way, while taking advantage of the wait-until-successfeature.

Tuning:You may log AutoRlock(), AutoFlock(), AutoAppend() and AutoUnlock() and theirfailure by assigning any valid file name (optionally with path) to

_aGlobSetting[GSET_C_AUTOLOCK_PROT] := fileName // def = ""When this protocol file already exist, messages will be appended.

If the lock fails, the process sleeps for a small time period and then retry the lockanew. The sleep period is defined by

_aGlobSetting[GSET_N_AUTOLOCK_SLEEP] := milliSec // def = 150When these retries exceeds info-time-out period, a pop-up window informs userabout waiting for lock. This info period is set by

_aGlobSetting[GSET_N_AUTOLOCK_INFO] := seconds // def = 5The pop-up info message (e.g. "Waiting for Lock") is displayed for

_aGlobSetting[GSET_N_AUTOLOCK_INFOWT] := seconds // def = 2and then disappears, continuing with retry. When the total time-out of SETAUTOLOCK TO (e.g. 10 seconds) expires too, user can decide to continue withretry, ignore this lock, jump per BREAK to recover of next BEGIN SEQUENCE orexit the application.

For background or Web/CGI applications, where user info and actions are notdesired, set long (or forever) AUTOLOCK period, e.g. SET AUTOLOCK TO 3600(or SET AUTOLOCK TO 0) and disable pop-up info by _aGlobSetting[GSET_N_AUTOLOCK_INFO] := 0

CMD 318

Example:BEGIN SEQUENCE

USE mydata SHARED // open mutiuserSET AUTOLOCK -99 // disable AUTOLOCKreplace name with "Miller" // run-time error !SET AUTOLOCK 0 // enable AUTOLOCKreplace name with "Miller" // o.k. or --> RECOVERreturn

RECOVER using cText? "sorry, could not ", cText, " the database " + DBF()

END SEQUENCE

Example:SET EXCLUSIVE OFF // enable multiuser* SET AUTOLOCK TO 10 // the default settingUSE article INDEX articleSEEK 12345if !found() ; return ; endif

DELETE // one AUTORLOCKREPLACE amount with 0, price with 0 // two AUTORLOCKs

while !RLOCK() ; enddo // one LOCK only* or: AUTORLOCK() // "smart" RLOCK()DELETEREPLACE amount with 0, price with 0COMMIT ; UNLOCK* or: AUTOUNLOCK() // "smart" UNLOCK


Compatibility:SET AUTOLOCK is a superset and combination of FoxPro's SET LOCK and SETREPROCESS. This feature is not available in C5 and only partially available in VO.

Source code:The functions are available in <FlagShip_dir>/system/autolock.prg

Translation:SET ( _SET_AUTOLOCK, <expN>|<expL> )

Related:AUTOxLOCK(), SET(), SET MULTILOCKS, RLOCK(), FLOCK(),oRdd:ConcurrencyControl

CMD 319

SET BELLSyntax:

SET BELL on|OFF|(<expL>)Purpose:

Toggles the sounding of the bell in READ.

Description:When ON, the bell sounds if a character is being entered into a GET field whichdoes not conform to the PICTURE clause or if the entry is out of the RANGE limit. Italso sounds when a character is entered at the last position of a GET. When usingthe alternative parenthesized <expL>, TRUE is the same as ON.

To sound the bell explicitly, you can use either CHR(7) or the TONE() function. Thisbell does not depend on the state of SET BELL.

Example:SET BELL ON // enable bellSET FORMAT TO articlesREADSET FORMAT TOSET BELL OFF // disable bell

IF LASTKEY() = K_ESC?? CHR(7) // sound a bell@ MAXROW(),0 SAY "Abort - are you sure (y/n) ?"IF UPPER(CHR(INKEY(0))) == "Y"

QUITENDIF

ENDIF


Compatibility:The ability to sound a bell depends on the terminfo definition and/or the terminalemulation software, if used. Some terminals use an "optical bell" which flashes thescreen output instead of sounding an acoustic bell.

Translation:SET ( _SET_BELL, .on. )

Related:SET CONFIRM, CHR(), TONE()

CMD 320

SET CENTURYSyntax:

SET CENTURY on|OFF|(<expL>)Purpose:

Toggles the display and input of century digits for date values.

Arguments:ON/OFF activates or suppresses the output of century digits. Alternatively, theparenthesized <expL> may be used, whereby logical TRUE is the same as ON.

Description:The stored date values always contain the complete year information, including thecentury. The information is stored as a LONG value (or 8 bytes ASCII in .dbf fields)representing the number of days since January 1, 0001. The supported date rangein FlagShip is therefore from 01/01/0001 up to 12/31/9999.

When CENTURY is OFF, only the two last digits of the year are displayed or can beentered. Setting CENTURY to ON changes the date format displayed to containfour digits for the year.

Example:? DATE() && 07/22/93SET CENTURY ON? DATE() && 07/22/1993SET DATE GERMANSET CENTURY (.F.)? DATE() && 22.07.93


Compatibility:Clipper supports date values from 01/01/0100 to 12/31/2999.

Translation:__SETCENTURY ( .on. )

Related:SET DATE, SET EPOCH, CTOD(), DATE(), DTOC(), DTOS(), DAY(), MONTH(),YEAR(), SET()

CMD 322

SET COLOR TOSyntax:

SET COLOR|COLOUR TO[<standard>[,<enhanced>[,<border>[,<background>[,<unselected>[,<extra>[,<disabled>[,<unselWindow>]]]]]]]] | (<expC>)

Purpose:Changes the screen color setting.

Arguments:Each argument of the list specifies a list of color settings for the five types of screenpainting activity. Each argument contains a color pair containing the foreground andbackground color, separated by a slash (/).

Output Pos Color pair Usage i.e.standard 1 foreground/background SAY, ?, enhanced 2 foreground/background GET, MENU, ACHOICE, border 3 foreground/background boxes etc., background 4 foreground/background hot-key, accelerator, unselected 5 foreground/background READ, extra 6 foreground/background reserved, disabled 7 foreground/background disabled GET, PROMPT, unselWidow 8 foreground/background GETs in unsel.window

If no argument is given, the default color setting is reset to "W/N,N/W,,,N/W".Skipping a foreground or background color within a setting sets the color to black.

Options:<standard> is the color pair (foreground/background) used to paint with all consoleand full-screen commands' and functions' output, such as ?, ??, @..SAY, @..BOX,@..PROMPT, @..CLEAR, CLEAR SCREEN, ACHOICE(), DBEDIT(), MEMOEDIT()etc. It can be set explicitly using the SETSTANDARD command.

<enhanced> specifies a color pair, which is used for painting highlighted displays,like the active GET field in READ, the light bar in MENU TO, DBEDIT(), andACHOICE(). It can be set explicitly using the SETENHANCED command.

<border> is not supported in FlagShip (nor in Clipper). It specify the color to paintthe area around screen or the background color for some other xBASE dialects.This color pair is used in FlagShip for other purposes, like the border in Popup's orin ACHOICE().

CMD 323

<background> is originally used by some other xBASE dialects for CGA cards andnot supported as such in FlagShip nor Clipper. In FlagShip, it is used for otherpurposes, like the hot-key color in Terminal i/o mode.

<unselected> is a color pair used to display currently inactive GET fields and un-selectable array members in ACHOICE(). Can be set explicitly using theSETUNSELECTED command.

<extra> is a color pair reserved for future use.

<disabled> is a color pair used to display disabled GET fields. Apply in GUI modeonly, ignored otherwise. Used also for un-selectable PROMPT items, even inTerminal i/o mode.

<unselWindow> is a color pair used to display GET fields when the focus is takenaway from the application window. If not specified, the GET color remainunchanged. Apply in GUI mode only, ignored otherwise.

(<expC>) is a character string enclosed in parentheses containing the colorsettings. This allows the color settings to be specified as an expression in place of aliteral string or a macro variable. Instead of character string, you may alternativelyuse an array of RGB triplets, or a Color or ColorPair object variable.

Description:SET COLOR is a synonym for the SETCOLOR() function that defines colors forsubsequent screen painting activities. Each argument can specify foreground (thedisplayed text) and background (the color underlying the text). Spaces aredisplayed as background only.

Note: In the case of color settings, a list containing commas in a macro variable canbe used.

Attributes: The foreground color setting also supports blinking (*) and high intensity(+) attributes. In Terminal i/o mode, these attributes affect only the foreground color,even if mentioned with the background color of the pair. In GUI mode, the highintensity attribute can also be used for background color, the blinking attrib isignored. High intensity enhances brightness of painted text on a monochromedisplay or changes the hue of the specified color on color monitors. The blinkingattribute causes the foreground text to flash on and off at a set hardware interval.

Colors in FlagShip may be specified by a string containing letters, numbers or RGBstring, or optionally by an RGB array.

•The letters and numbers are fix and specify 16 different colors, available on anyVGA screen. Compatible to other xBase dialects.

•A RGB string triplet is similar to the common HTML notation. The color is definedas a string "#RRGGBB" starting with "#" followed by 6 hexadecimal characters(each 0..9,A..F). The first two hex chars ("00" to "FF") specify the amount of redportion in the resulting color, the second two characters the portion of green, thelast two hex characters the portion of blue color.

•Instead of a string, optionally an array of RGB triplets can be used, e.g. when

CMD 324

calculating colors. This array is either: - one-dimensional array with three numericelements (ea 0..255), specifying the red, green and blue color portion offoreground color, e.g. aColor := {128,128,0} ; @..SAY.. COLOR (aColor) - or a 2-dimensional array containing two color pair triplets for foreground and backgroundof the standard color, e.g. aColor := {{0,0,0},{0,0,128}} ; SET COLOR TO (aColor)- or 3-dimensional array specifying each corresponding color pair, e.g. a2 :={{0,0,0},{0,0,128}}; a5 := {{RGBCOLOR_WHITE},{0,0,128}} aColor := {NIL, a2,NIL, NIL, a5} ; @..GET.. COLOR (aColor) which set the enhanced andunselected color pairs only. - For some standard color triplets (the sub-array of 3elements), there are pre-defined constants RGBCOLOR_* in #include "color.fh".

You may use letters, numbers and RGB strings interchangeably in a singlespecification, e.g. "B/N, 1/R, #00FF00/W, 12/#C0C0C0" etc.

The RGB notation allows a combination of 16 million colors and is fully supported inGUI mode, provided your GUI environment is set to 16 mio (or more) colors. If yourenvironment support 256 colors only, you should preferably use hex values00,33,66,99,CC,FF in a triplets combination, or the standard RGB triplets as givenin the table below. In Terminal i/o mode, the Symbol/Letter notation is commonlyused. If given in RGB notation, the closest color letter is calculated from the RGBtriplet. Conversion failure is displayed when the developer's mode is set byFS_SET("devel",.T.)

The standard colors are:

Color * Symbol/Letter Num.Code RGB String RGB ArrayBlack N 0 #000000 { 0, 0, 0}Blue B 1 #000080 { 0, 0,128}Green G 2 #008000 { 0,128, 0}Cyan BG or GB 3 #008080 { 0,128,128}Red R 4 #800000 {128, 0, 0}Magenta RB or BR 5 #800080 {128, 0,128}Brown (dark yellow) GR or RG 6 #808000 {128,128, 0}White (light gray) W or RGB 7 #DCDCDC {220,220,220}Gray (dark) N+ 8 #808080 {128,128,128}Bright blue B+ 9 #0000FF { 0, 0,255}Bright green G+ 10 #00FF00 {255,255, 0}Bright cyan BG+ 11 #00FFFF { 0,255,255}Bright red R+ 12 #FF0000 {255, 0, 0}Bright magenta RB+ or BR+ 13 #FF00FF {255, 0,255}Bright yellow GR+ or RG+ 14 #FFFF00 {255,255, 0}Bright white W+ or RGB+ 15 #FFFFFF {255,255,255}Mid gray W- #C0C0C0 {192,192,192}Blank XUnderline (mono) UReverse Video IStandard background ? RGBSTRING_BG {RGBCOLOR_BG}

CMD 325

*Note: in Terminal i/o mode for Unix/Linux, the proper output depends on thecorrect setting of the terminfo variables setf (set foreground), setb (set backgroundcolor), bold (set high intensity), blink (set blinking), invis (invisible), rev (reverse),smul (underline) and sgr0 (disable setting) for the current terminal TERM. See alsosection SYS.

The "?" symbol is replaced by standard background color, taken fromm->oApplic:ColorBackground property. It corresponds to main window color in GUImode, or "N" (= #000000) in other i/o modes, but may be re-defined by any validvalue upon request.

The current color setting is always active for Terminal i/o mode. In GUI mode, it isconsidered only if SET GUICOLOR is ON or when the GUI color is explicitlyspecified, e.g. in @..GET..GUICOLOR... This is because GUI design rulesrecommend not to use colors at all, except when explicitly required.

Example:STATIC colors [3]IF ISCOLOR()

colors[1] := "W+/B,R+/GR,,,B/W" // standardcolors[2] := "W/B,N/W,,,N/BG" // other colorcolors[3] := "GR+/B,R+/B" // messages

ELSEcolors[1] := "W+,/W,,N" // standardcolors[2] := "W/N,N/W,,,N/W" // other colorcolors[3] := "U,W*" // messages

ENDIFSET COLOR TO (colors[1])CLEAR SCREEN@ 1,1 SAY "name " GET FIELD->name@ 2,1 SAY "address " GET ADR->address VALID check()READIF LASTKEY() = K_ESC

SET COLOR TO (colors[3])@ MAXROW(),0 SAY "Are you sure to quit (y/n) ? "IF (UPPER(CHR(INKEY(0))) == "Y"

QUITENDIFSET COLOR TO (colors[1])

ENDIF

FUNCTION checkLOCAL actcolor := SETCOLOR()IF EMPTY(ADR->address)

SET COLOR TO (colors[3])SETENHANCED // enhanced color?? CHR(7) // bell@ MAXROW(),0 SAY "Address must be given!"SETSTANDARDSET COLOR TO &actcolor // or TO (actcolor)INKEY(5) // wait 5 seconds@ MAXROW(),0 // clear msgRETURN .F.

ENDIFRETURN .T.

CMD 326

Example:#include "color.fh"@ 5,2 SAY "hello light blue on std. GUI background" ;COLOR "B+/N" ; // Terminal modeGUICOLOR {{0,0,255},{RGBCOLOR_BG}} // GUI mode

? "hello dark red on std. GUI background" ;GUICOLOR ("R/" + RGBSTRING_BG) COLOR ("R/N")

Example:See also example in SETCOLOR() which allows user to choose the preferred colorsetting.

Example:Display all standard and some RGB colors as background

#include "color.fh"aStd1 := {"N","N+","W-","N-","W","W+","R","R+","G","G+", ;

"B","B+","BG","BG+","RB","RB+","GR","GR+"}aStd2 := {"#000000","#808080","#C0C0C0","#A0A0A0","#DCDCDC", ;

"#FFFFFF","#800000","#FF0000","#008000","#00FF00", ;"#000080","#0000FF","#008080","#00FFFF","#800080", ;"#FF00FF","#808000","#FFFF00" }

aCol3 := {"00", "10", "20", "33", "40", "50", "66", "70", "80", ;"90", "99", "B0", "C0", "CC", "E0", "F0", "FF"}

SET FONT "courier",10for ii := 1 to len(aStd1) // using std.symbols

fg := "N/"@ ii,1 SAY " " + fg + aStd1[ii] + " " ;

COLOR (fg+aStd1[ii]) GUICOLOR (fg+aStd1[ii])fg := "W/"@ ii,10 SAY " " + fg + aStd1[ii] + " " ;

COLOR (fg+aStd1[ii]) GUICOLOR (fg+aStd1[ii])nextfor ii := 1 to len(aStd2) // using std.symbols + RGB string

fg := if(ii < 3 .or. ii == 11 .or. ii == 12, "W", "N")bg := "/" + aStd2[ii]@ ii,20 SAY " " + fg + bg + " " COLOR (fg+bg) GUICOLOR (fg+bg)

next

SET GUICOLOR ONfor ii := 1 to len(aCol3) // using user defined RGB string

fg := "W/"bg := "#0000" + aCol3[ii]@ ii,40 SAY " " + fg + bg + space(10) COLOR (fg+bg)

next

iRow := 1for ii := 0 to 256 step 16 // using array of calcul. RGB colors

aColor := {{RGBCOLOR_YELLOW},{ 0,0,min(ii,255) }}@ iRow++,62 SAY " GR+/Rgb(0,0," + ltrim(aColor[2,3]) + ")" + ;

space(10) COLOR (aColor)nextSET GUICOLOR OFFsetpos(20,0)wait

CMD 327


Compatibility:In Terminal i/o mode, colors are available only if both parameters "colors" and"pairs" are set in the terminfo (or FStinfo.src); refer to section SYS. You maydetermine the color capability using the function ISCOLOR(). The UNIX cursesdoes not support the black on black setting ("N/N" or "N+/N") since this is used asthe default terminal color. To hide the output, use e.g. "N/X", "W/N" etc. or the "X"color setting.

In GUI mode, colors are considered only if SET GUICOLOR is ON, or when thespecial GUICOLOR clause (available in many commands) was specified. See alsotext.

The ability to display all colors specified or the additional attributes depends also onthe hardware capabilities of the current terminal, the OS dependent curses libraryand/or the software setting of the used terminal emulation.

Color pairs 6..8 (extra, disabled and unselWindow) as well as the use of RGBtriplets are available in FS5 only.

Translation:SETCOLOR (expC)

Related:SETCOLOR(), COLORSELECT(), SETSTANDARD, SETENHANCED,SETUNSELECTED, ISCOLOR()

CMD 328

SET COORDSyntax 1:

SET COORD [UNIT] TO ROWCOL | PIXEL | MM | CM | INCHSyntax 2:

SET COORD [UNIT] TOPurpose:

Set required coordinate units for screen and printer output row and columncoordinates (for printer only with SET GUIPRINTER ON). Apply in GUI mode only,ignored otherwise. The default is ROWCOL, which is also set by syntax 2.

Arguments:TO ROWCOL all subsequently given output coordinates are calculated as rows andcolumns according to the used font. Default setting.

TO PIXEL all subsequently given output coordinates are calculated in pixels or re-calculated for printer resolution.

TO MM all subsequently given output coordinates are re-calculated from mm (1 mm= 0.0397") to current screen or printer resolution.

TO CM all subsequently given output coordinates are re-calculated from cm (1 cm =0.397 inch) to current screen or printer resolution.

TO INCH all subsequently given output coordinates are re-calculated from inch (1"= 2.54 cm) to current screen or printer resolution.

TO reset defaults to ROWCOL

Description:SET COORD controls the behavior of given coordinate units. Apply in GUI modeonly, ignored otherwise. These units are considered in all subsequent commandsand functions with coordinate input, like @..SAY, @..GET, @..PROMPT,SETPOS(), DEVPOS(), MemoEdit() etc. and for returned values from COL() andROW() functions. With the most commands you may override the current SETCOORD setting by the PIXEL clause, or by the similar parameter of correspondingfunction.

Using TO ROWCOL (the default) is convenient in the most cases. With proportionalfonts (see SET FONT and LNG.5.3.1-2) the character size may vary. To control theoutput exactly, you may use SET COORD TO PIXEL or SET PIXEL ON orcorresponding PIXEL clause, whereby the coordinates are pixel oriented (pixel is a"dot on the screen", i.e. smallest single component of a digital image). Alternatively,you may force the output in mm, cm or inch by corresponding SET COORD TO...

The re-calculation from mm, cm or inch to pixel on screen (or dpi for printer)depends on the system API, which may be imprecise in some cases. For the screenoutput, FlagShip determines the desktop size in mm by oApplic:DesktopXmm andoApplic:DesktopYmm at program start (in initio.prg) and stores it in global array

CMD 329

elements _aGlobSetting [GSET_G_N_DESKTOP_X_MM] and _aGlobSetting[GSET_G_N_DESKTOP_Y_MM]. When you detect significant differences, you mayset these array elements manually before using SET COORD TO MM|CM|INCHand displaying data. The physical size of printer sheet is determined at print-timefrom the printer API; these data are available after the user selects correspondingprinter driver by oPrinter:Setup().

Example:* _aGlobSetting[GSET_G_N_DESKTOP_X_MM] := 520 // optional* _aGlobSetting[GSET_G_N_DESKTOP_Y_MM] := 324 // optional

@ 10,3 say "text1" // output at line 10, column 3SET COORD TO MM@ row(), col() + 55 SAY "text2" // output at same line +5.5cm right@ 25.4, 76.2 SAY "text3" // output 1" from top, 3" from leftSET COORD TO@ 10,15 say "text4" // output at line 10, column 15setpos(20,0)wait

Classification:programming, screen and printer output

Compatibility:Available in VFS7 and newer only.

Translation:SET ( _SET_COORD_UNIT, _SET_COORD_ROWCOL or _SET_COORD_DEF or 0 )SET ( _SET_COORD_UNIT, _SET_COORD_PIXEL or 1 )SET ( _SET_COORD_UNIT, _SET_COORD_MM or 2 )SET ( _SET_COORD_UNIT, _SET_COORD_CM or 3 )SET ( _SET_COORD_UNIT, _SET_COORD_INCH or 4 )

Related:@...SAY, @..GET, SET PIXEL, SET GUIPRINTER, OBJ.Applic, OBJ.Printer

CMD 330

SET CONFIRMSyntax:

SET CONFIRM on|OFF|(<expL>)Purpose:

Determines if moving to the next field in GET/READ when the field is filled, orselecting an item in MENU TO by the first letter should be confirmed or doneautomatically.

Arguments:ON/OFF activates or deactivates the requirement to press the ENTER <┘key toleave a GET entry or the item selected in MENU TO. Alternatively, theparenthesized <expL> may be used, whereby TRUE is the same as ON.

Description:SET CONFIRM controls the behavior of leaving the current GET and MENU TOchoice:

•When SET CONFIRM is OFF (the default), the user can type past the end of aGET and the cursor will move to the next GET if there is one; otherwise thecurrent READ terminates. In MENU TO, pressing the first menu character selectsthe item found and terminates the choice.

•When ON is set, an exit key (e.g. ENTER, PgDn, PgUp etc.) must be pressed toleave the current GET. In MENU TO, pressing the first menu character selectsthe item found and positions the light bar on it. The user must press an ENTER<┘key to confirm the choice.

Example:LOCAL answer := "N"SET CONFIRM ON@ 10,10 SAY "Erase the temp*.txt files?" GET answerREADSET CONFIRM OFFIF LASTKEY() = 13 .AND. upper(answer) $ "YJO"

CLOSE ALLRUN rm temp*.txt

ENDIF


Compatibility:The support of MENU TO is available in FlagShip only.

Translation:SET ( _SET_CONFIRM, .T.|.F. )

Related:@...GET, READ, MENU TO, SET BELL

CMD 331

SET CONSOLESyntax:

SET CONSOLE ON|off|(<expL>)Purpose:

Activates or deactivates console display to the screen.

Arguments:ON/OFF activates or suppresses the output of console commands and functions tothe screen. Alternatively, the parenthesized <expL> may be used, whereby TRUE isthe same as ON.

Description:SET CONSOLE affects the screen display of all console commands (seeLNG.5.1.1). Setting it to OFF and using the SET ALTERNATE, SET EXTRA, orSET PRINTER commands or TO.. clause suppresses the screen output and sendsit to the printer or file only. Some console commands have a NOCONSOLE option,which has the same effect as temporarily setting SET CONSOLE OFF.

For console commands that accept input (like ACCEPT, INPUT, and WAIT), SETCONSOLE affects the display of the prompts as well as the input echo.

The full screen commands (like @..SAY, @..BOX, @..TO etc., see LNG.5.1.2) arenot affected by SET CONSOLE but may be re-routed to printer or file using the SETDEVICE command.

Example:SET CONSOLE OFFUSE stockLIST item, volume FOR volume > 100 TO PRINTUSESET CONSOLE ON


Translation:SET ( _SET_CONSOLE, .T.|.F. )

Related:SET DEVICE, SET ALTERNATE, SET EXTRA, SET PRINTER

CMD 332

SET COORDINATE UNITSyntax:

SET COORDINATE [UNIT] [TO]SET COORDINATE [UNIT] [TO] PIXEL | MM | CM | INCH |

( <expN> )Purpose:

Sets the unit for subsequently given screen (and printer with active PrintGui()output) coordinates. Applicable in GUI mode only.

Arguments:ROWCOL : all subsequent coordinates are in common rows andor none: columns.PIXEL : all subsequent coordinates are in pixelsMM : all subsequent coordinates are millimeterCM : all subsequent coordinates are centimeter (ea 10 mm)INCH : all subsequent coordinates are in inch (ea 25.4 mm)<expN> : parenthesized numeric value, e.g. UNIT_ROWCOL, UNIT_MM,

UNIT_CM, UNIT_INCH, UNIT_PIXEL, UNIT_DOTS (specifiedin the set.fh include file)

Description:SET COORDINATE is equivalent to SET UNIT command, see description there.SET COORD TO PIXEL is equivalent to SET PIXEL ON, SET COORD TOROWCOL is equivalent to SET PIXEL OFF

Compatibility:Available in VFS7 and later only.

Translation:SET ( _SET_COORD_UNIT, expN)

Related:SET PIXEL, SET()

CMD 333

SET CURSORSyntax:

SET CURSOR ON|off|(<expL>)Purpose:

Sets cursor to be visible or invisible.

Arguments:ON/OFF activates or deactivates cursor visibility. Alternatively, the parenthesized<expL> may be used, whereby TRUE is the same as ON.

Description:SET CURSOR OFF hides the cursor, although it still exists, which means thatediting can be done with the cursor being invisible.

SET CURSOR can be used to suppress displaying the cursor, except when editingtext. Some commands and functions (like MENU TO, ACHOICE(), DBEDIT() etc.)will disable the cursor automatically by default.

Because in practice controlling cursor visibility depends on the terminal hardwareand the terminfo description, FlagShip will set the invisible cursor to MAXROW(),MAXCOL(). The current COL() and ROW() values are not affected by the cursorON/OFF state.

SET CURSOR ON/OFF is considered in Terminal i/o mode. For GUI mode, useSET GUICURSOR instead, where you can also set the text cursor at specificposition or shape by SetGuiCursor(), or set the mouse cursor shape byMsetCursor().

Example:SET CURSOR OFFCLS@ 1,1 TO 20,60 DOUBLESET CURSOR ONName = SPACE(15)@ 10,10 SAY "Enter name: " GET NameREADSET CURSOR OFF


Compatibility:Most UNIX terminals (curses libraries) cannot disable the cursor, so the cursorstays visible at the bottom rightmost position of the screen. For GUI mode, use SETGUICURSOR instead.

Translation:SETCURSOR (1 | 0)

Related:SET CONSOLE, SETCURSOR(), SETPOS(), SET GUICURSOR, SetGuiCursor()

CMD 334

SET DATESyntax 1:

SET DATE [TO] AMERICAN | ansi | british | french |german | italian | japan | usa

Syntax 2:SET DATE FORMAT [TO] <expC>

Purpose:Sets the format for displaying and inputting date values.

Arguments:SET DATE TO AMERICAN, ANSI, GERMAN etc. specifies the format of input andoutput date values:

SET DATE Output SET CENTURY ONAMERICAN mm/dd/yy mm/dd/yyyyANSI yy.mm.dd yyyy.mm.ddBRITISH dd/mm/yy dd/mm/yyyyFRENCH dd/mm/yy dd/mm/yyyyGERMAN dd.mm.yy dd.mm.yyyyITALIAN dd-mm-yy dd-mm-yyyyJAPAN yy/mm/dd yyyy/mm/ddUSA mm-dd-yy mm-dd-yyyy

Arguments:SET DATE FORMAT TO <expC> defines a character expression that directlyspecifies the date format. <expC> must be a string of 12 or fewer characters.Upper/lower letters D, M and Y specify the position of day, month, and year digitsdisplayed. Other characters in the string are copied into date values displayed andare used as delimiters.

The FlagShip run-time system analyzes for proper formats and reports errors indeveloper mode.

Description:Using SET DATE allows the control of date formatting in programs ported indifferent countries.

CMD 335

Example:? DATE() && 07/26/93SET DATE ANSI? DATE() && 93.07.26SET DATE BRITISH? DATE() && 26/07/93SET DATE FRENCH? DATE() && 26/07/93SET DATE ITALIAN? DATE() && 26-07-93SET DATE GERMAN? DATE() && 26.07.93SET CENTURY ON? DATE() && 26.07.1993

Example:Get the date format from a shell environment variable:

LOCAL lang := UPPER(GETENV("LANG"))DO CASECASE SUBSTR(lang,1,4) = "BRIT"

SET DATE BRITISHCASE SUBSTR(lang,1,4) = "GERM"

SET DATE GERMANOTHERWISE

SET DATE USAENDCASE


Compatibility:The JAPAN and USA clauses and syntax 2 are new in FS4. FlagShip supports datevalues from 01/01/0001 to 12/31/ 9999.

Translation:SET DATE TO AMERICAN => _DFSET("mm/dd/yyyy", "mm/dd/yy")SET DATE TO GERMAN => _DFSET("dd.mm.yyyy", "dd.mm.yy")SET DATE TO USA => _DFSET("mm-dd-yyyy", "mm-dd-yy")SET DATE FORMAT TO (expC) => SET(_SET_DATEFORMAT, expC)

Related:SET CENTURY, SET EPOCH, CTOD(), DATE(), DTOC(), DTOS(),@...SAY..PICTURE, @...GET, READ, TRANSFORM()

CMD 336

SET DBREADSET DBWRITESyntax 1:

SET DBREAD ANSI|ISOSET DBREAD PC8|ASCII|OEM

Syntax 2:SET DBWRITE ANSI|ISOSET DBWRITE PC8|ASCII|OEM

Purpose:Change the behavior how to read from or store data into database. This is a specialcase of SET ANSI ON/OFF.

Arguments:ANSI|ISO activates the automatic translation for reading or writing data from/todatabase.

PC8|ASCII|OEM deactivates the automatic translation for reading or writing datafrom/to database. This is the default setting.

Description:SET DBREAD and SET DBWRITE is a splitted behavior of SET ANSI to performeither read or write translation if both are not desired.

SET DBREAD ANSI + SET DBWRITE ANSI is equivalent to SET ANSI ON, SETDBREAD PC8 + SET DBWRITE OEM is equivalent to SET ANSI OFF which is thedefault.

With SET DBREAD ANSI, a database access of character or memo translates thePC8/ASCII/OEM charset via Oem2Ansi() into ANSI/ISO charset (used for display inGUI mode or in X11 terminal without a corresponding mapping).

With SET DBWRITE ANSI, the replaced a char or memo field in the database willbe first translated by Ansi2oem() from ANSI to PC8.

This means, special characters like a-umlaut, stored in the database as chr(132) inPC8/ASCII/OEM charset are translated during a read access to chr(228) inANSI/ISO charset, to be displayed on the screen as a-umlaut in GUI environment oron X terminal. Reverse, with SET ANSI ON or SetAnsi(.T.), the a-umlaut chr(228)available in a variable or given in input, is stored in the dbf as chr(132) during thereplace stage.

Note: both the FS4 and Clipper always use PC8/ASCII charset in the database, i.e.chr(132) for a-umlaut.

CMD 337

Example:See examples/setansi.prg for a complete example with description



Related:SetAnsi(), SET ANSI, Ansi2oem(), Oem2Ansi(), SET SOURCE, SETKEYTRANSL|CHARSET,

CMD 338

SET DECIMALS TOSyntax:

SET DECIMALS TO [<expN>]Purpose:

Sets the number of decimal places for displaying the results of numericexpressions.

Options:<expN> is the number of decimal places to display. The default value on start-up istwo. If <expN> is not given, SET DECIMALS is set to 0.

Description:SET DECIMALS and the number of displayed decimals depend on the state of SETFIXED:

When FIXED is OFF (the default),

•SET DECIMALS affects the minimum number of decimal digits displayed by theEXP(), LOG(), SQRT() functions, the division operations (/, %, /= or %= ) andexponentiation (**, ^ or **=).

•On assignment (:= or =), the number of decimal digits of the variable or constantis stored in the receiving variable structure.

•On addition and subtraction (+, -, ++, --, += or -= ), the number of decimal placesof the operand with a greater number of decimal places is stored.

•On multiplication (* or *=), the sum of decimal places of both operands is stored.

By setting FIXED ON, the results of all numeric expressions are displayedaccording to SET DECIMALS.

SET DECIMALS and SET FIXED only affect the way numbers are displayed (orstrings created by STR*(), PAD*(), TRANSFORM() etc.) and have no effect on theprecision of numeric calculations.

Example:LOCAL a := 2, b := 3.456? SQRT(2), a, b && 1.41 2 3.456SET DECIMALS TO 6? 10/3, a, b && 3.333333 2 3.456SET FIXED ON? a, b && 2.000000 3.456000


Translation:SET ( _SET_DECIMALS, expN )

Related:SET FIXED, @..SAY..PICTURE, @..GET..PICTURE, TRANSFORM()

CMD 339

SET DEFAULT TOSyntax:

SET DEFAULT TO <path>|(<expC>)Purpose:

Sets the directory where files are saved and created.

Arguments:<path> specifies the directory. The "\" signs are automatically translated to "/". Forlower/upper path translation, use FS_SET("pathlower"|"pathupper"); for thesubstitution of a DOS drive letter, the environment variable x_FSDRIVE can beused.

If the <path> argument is not given, the current UNIX directory becomes the default.

Description:The default directory, at the beginning of a FlagShip program is the current UNIXdirectory. This default directory can be changed with SET DEFAULT.

When accessing files, the DEFAULT directory is searched first. To specifyadditional directories to search, the SET PATH command may be used. The RUNcommand is not affected by SET DEFAULT nor by SET PATH

SET DEFAULT is meant primarily to specify the location where files are created andsaved. SET DEFAULT does not change the current UNIX directory.

Example:PUBLIC FlagShip? FILE("article.dbf") && .F.SET DEFAULT TO (IF (FlagShip, "/usr/users/smith/am", ;

"D:\smith\am"))? FILE("article.dbf"), FILE("Article.Dbf") && .T. .F.FS_SET ("lower", .T.)FS_SET ("pathlower", .T.)? FILE("Article.Dbf") && .T.


CompatibilityFlagShip supports the automatic conversion of the otherwise case sensitive UNIXpath names and the substitution of DOS drive letters, see FS_SET() and LNG.9.5.

Translation:SET ( _SET_DEFAULT, expC )

Related:SET PATH, CURDIR(), FS_SET(), PUBLIC FlagShip. #ifdef FlagShip

CMD 340

SET DELETEDSyntax:

SET DELETED on|OFF|(<expL>)Purpose:

Toggles the filtering of deleted records.

Arguments:ON/OFF ignores or processes deleted records. Alternatively, the parenthesized<expL> may be used, whereby TRUE is the same as ON.

Description:SET DELETED ON causes most commands to ignore the deleted records; thedatabase seems to include only undeleted records. The SET DELETED ONcommand is equivalent to SET FILTER TO .NOT. DELETED().

SET DELETED ON has no effect on indexing operations using INDEX ON orREINDEX. The RECALL ALL command recalls all records which have beenDELETED().

If a record is referenced by its record number (e.g. the GOTO command or theRECORD in <scope> clause), the record is available even when SET DELETED isset ON.

Example:SET DELETED ONUSE articleDELETE RECORD 34COUNT TO undel? undel, LASTREC() && 99 100SET DELETED (.F.) && or: DELETED OFFCOUNT TO all? all, RECCOUNT() && 100 100


Translation:SET ( _SET_DELETED, .T.|.F. )

Related:DELETE, INDEX, RECALL, SET FILTER, SET INDEX, USE, DELETED(), SET(),oRdd:Deleted

CMD 341

SET DELIMITERSSyntax 1:

SET DELIMITERS on|OFF|(<expL>)Syntax 2:

SET DELIMITERS TO [<expC>|DEFAULT]Purpose:

Sets/enables delimiter characters for the display of GET entries in terminal i/omode.

Arguments:ON/OFF displays delimiters or suppresses the display. Alternatively, theparenthesized <expL> may be used, whereby TRUE is the same as ON.

Options:TO <expC> is a character expression containing one or two characters. If there isonly one character, it is used as both the beginning and the ending delimiter. Ifthere are two, the first one becomes the beginning, and the other the endingdelimiter. If there are more than two characters in the string, the first two areconsidered and the rest is ignored.

TO DEFAULT: Resets the delimiters to the default colons (::) value. SETDELIMITERS TO without parameters has the same effect.

Description:The @...GET command can display delimiters that surround the GET edit fielddisplay. If DELIMITERS is ON, the delimiters add two characters to the length of theGET object display.

To suppress the visibility of the left, right, or both delimiters, spaces can be used aspart of the character expression.

Normally, DELIMITERS are not necessary because FlagShip programs use theoptically more attractive reverse video or enhanced color setting if INTENSITY isON.

In GUI mode, the delimiters are not displayed (but the GET column is corrected, i.e.shifted one column right), since the GET itself use own GUI widgets (controls).

CMD 342

Example:SET DELIMITERS ONSET DELIMITERS TO "||" && chr(128), pipeName = "John "@ 10,10 SAY "Name" GET Name && Result: Name |John |READ

SET DELIMITERS TO "><"Name = "John "@ 10,10 SAY "Name" GET Name && Result: Name >John <READ


Translation:Set ( _SET_DELIMCHARS, expC )Set ( _SET_DELIMITERS, .T.|.F. )

Related:@...GET, READ, SET()

CMD 343

SET DEVICE TOSyntax:

SET DEVICE TO SCREEN | printer [NEW]Purpose:

Redirects the output of full-screen commands, like @..SAY to the screen or printer.

Arguments:TO SCREEN: The screen is the default device. If SCREEN is specified as thedevice, all output from @...SAY goes to the screen.

TO PRINTER: redirects all @...SAY output to the device or file specified with SETPRINTER TO, and is not echoed to the screen. The SET MARGIN is [email protected] are ignored.

TO PRINTER NEW causes the current printer file contents to be deleted , instead ofappended to.

Description:When @...SAY is sent to the printer, a formfeed character (the EJECT command) issent each time when the printing row becomes less than in the previous command.EJECT resets the printing row and column (PCOL() and PROW() values) to zeroalso causing a formfeed. SETPRC() can be used to set the printing row and columnto the desired value.

You may tune the printer device driver by FS_SET("prset") which may beadvantageous when using proportional character set etc.

To redirect the @...SAY output to a text file, SET PRINTER TO <file> and SETDEVICE TO PRINTER may be used.

Example:IF ISPRINTER() && UNIX: always .T.

SET DEVICE TO PRINTER@ 1,5 SAY "Time to go home!"EJECT

ENDIF

Classification:programming, file access

Compatibility:Note the default spooled printer output of FlagShip; for more information refer toSET PRINTER and LNG.5.1.6. The NEW clause is available in FS4 only.

Translation:SET ( _SET_DEVICE, "SCREEN"|"PRINTER")

Related:@...SAY, EJECT, SET PRINTER TO, ISPRINTER(), PROW(), PCOL(), SETPRC(),SET(), FS_SET("prset")

CMD 344

SET DIRECTORY TOSyntax:

SET DIRECTORY [TO] [<expC>]Purpose:

Changes the current working directory.

Option:<expC> specifies the path (and optional DOS drive) of the new current workingdirectory.

When <expC> is not specified or is an empty string, the previous directory isselected.

Description:On UNIX, you cannot use RUN cd <expC> since the directory change applies to thecurrent shell only and has therefore no influence on the application when the RUNcommand terminates. Use the SET DIRECTORY instead, which has the sameeffect as #Cinline / chdir (<expC>); / #endCinline.

Automatic path conversion to lowercase or uppercase withFS_SET("pathlow"|"pathupp") and drive substitution from x_FSDRIVE environmentvariables is supported.

Issuing SET DIRECTORY without arguments changes to the last directory beforethe previous SET DIRECTORY was executed.

Example:? CURDIR() && /usr/peter/tempSET DIRECTORY TO ../dataCURDIR() && /usr/peter/dataSET DIRECTORY TO? CURDIR() && /usr/peter/temp

SET DIRECTORY TO /tmp? CURDIR() && /tmpSET DIRECTORY TO /usr/john? CURDIR() && /usr/johnSET DIRECTORY TO? CURDIR() && /tmp

Example: checks if given directory is availablecDir1 := "..\a\b"ok := IsDirAvail(cDir1)? "Directory", cDir1, "available:", okcDir2 := "c:\tmp"ok := IsDirAvail(cDir2)? "Directory", cDir2, "available:", ok? "current dir =", curdir()wait

CMD 345

// ----------------------------------------------------// checks if directory <cDirName> is available,// returns .T. or .F., does not change current dirFUNCTION IsDirAvail(cDirName)

local ok, cCurDircCurDir := curdir()ok := _setdir(cDirName) // SET DIRECTORY ...if ok

_setdir(cCurDir) // back to currentendif

return ok


Compatibility:Compatible to DB4, not available in C5.

Translation:_SETDIR (expc)

Related:CURDIR(), SET DEFAULT, SET PATH

CMD 346

SET EJECTSyntax:

SET EJECT on|OFF|(<expL>)

Purpose:Performs automatic EJECT on full printer page in GUI mode

Arguments:ON/OFF enables/disables the automatic EJECT. Alternatively, the parenthesized<expL> may be used, whereby TRUE is the same as ON. The default setting isOFF.

Description:With PrintGUI() or SET PRINTER GUI turned on, this SET EJECT performsautomatic FormFeed (new page) when the line number exceeds printer's page limit.You may alternatively perform FormFeed manually by the EJECT command.

Example:SET FONT “courier”, 8SET CONSOLE OFF // disable screen outputSET PRINTER ON // activate printer outputPrintGui(.T.) // creates spooler file for GDI printerSET MARGIN TO 5 // margin left = 5 chars

SET EJECT ON // autom. EJECT on full page

USE addressLIST Name, Address, Age // print to spoolerPrintGui() // select & start print to GDI printerSET CONSOLE ON // enable screen outputSET FONT “courier”, 10

Classification:GUI printer output

Translation:SET ( _SET_EJECT, expL)


Related:EJECT, SET PRINTER, SET GUIPRINTER, PRINTGUI()

CMD 347

SET EOFAPPENDSyntax:

SET EOFAPPEND on|OFF|(<expL>)Purpose:

Enables/disables automatic APPEND BLANK before replacing record at EOF().

Arguments:ON/OFF enables/disables the automatic APPEND BLANK. Alternatively, theparenthesized <expL> may be used, whereby TRUE is the same as ON. Thedefault setting is OFF.

Description:In some xBase dialects, REPLACEing a record in empty database, or when therecord pointer is behind the last record (i.e. when EOF() reports .T.) willautomatically invoke APPEND BLANK before REPLACE to avoid RTE (run-time-error) message.

You also may use this feature in your application by setting SET EOFAPPEND ONor the equivalent function SET(_SET_EOFAPPEND, .T.).

Example:USE mydataGO TOP // go to last recordSKIP // skip one behind? EOF(), RecNo(), RecCount() // .T. 121 120? SET(_SET_EOFAPPEND) // .F.

* REPLACE name with "My Name" // this will cause RTE 334

SET EOFAPPEND ON // anywhere before REPLACE? SET(_SET_EOFAPPEND) // .T.REPLACE name with "My Name" // this invokes APPEND BLANK? EOF(), RecNo(), RecCount() // .F. 121 121



Related:APPEND BLANK, Eof(), Set()

CMD 348

SET EPOCHSyntax:

SET EPOCH TO <expN>Purpose:

Controls the interpretation of dates which have no century digits.

Arguments:<expN> specifies the base year of a 100-year period in which all dates containingonly two year-digits are assumed to fall.

Description:SET EPOCH allows the correct interpretation of date strings containing only twoyear digits, even for dates outside of the 1900..1999 range. When such a string isconverted to a date value, its year digits are compared with the year digits of<expN>. If the year digits in the date are greater than or equal to the year of<expN>, the date is assumed to fall within the same century as given in <expN>;otherwise, the date is assumed to fall in the following century.

The default value for SET EPOCH is 1900, causing dates with no century digits tobe interpreted as falling within the 20th century.

Staring with the release 4.42.448, the default EPOCH value is set to 1951to meet all the "Year 2000 Conformity Requirements", see below. This means,when you need compatibility to Clipper or older FlagShip releases, you should set

SET EPOCH TO 1900at program start.

Year 2000: The BSI committee has specified rules for Y2K conformance (seedetails and the full text on http://www.fship.com/y2k.html ). In short: FlagShipfully meets all the requirements. But, since the inference rule (3.2.b) says here:"two-digit years with value > 50 imply 19xx, those with a value <= 50 imply 20xx",the default EPOCH value is now set to 1951. This means, the date entered as e.g.52 imply the year 1952, whilst the entry 49 imply the year 2049. If you want toenable this rule at the begin of year 2000, use

IF YEAR(DATE()) >= 2000SET EPOCH TO 1951

ENDIFinstead. This is valid also for FlagShip which imply an immediate availabilityof the Y2000 Conformance.

CMD 349

Example:? VERSION(), SET(_SET_EPOCH) && ...4.42.0448... 1951SET CENTURY OFF? DATE(), CTOD("12/31/55") && 05/20/98 12/31/55SET CENTURY ON? DATE(), CTOD("12/31/55") && 05/20/1998 12/31/1955? DATE()+730, CTOD("12/31/45") && 05/19/2000 12/31/2045 !

SET EPOCH TO 2000? DATE(), CTOD("12/31/55") && 05/20/1998 12/31/2055SET EPOCH TO 1990? DATE(), CTOD("12/31/55") && 05/20/1998 12/31/2055SET EPOCH TO 1900? DATE(), CTOD("12/31/55") && 05/20/1998 12/31/1955

SET EPOCH TO 1951? CTOD("01/01/00"), CTOD("02/29/00") && 01/01/2000 02/29/2000? CTOD("01/01/50"), CTOD("01/01/51") && 01/01/2050 01/01/1951? CTOD("01/01/1950"), CTOD("01/01/2051") && 01/01/1950 01/01/2051


Compatibility:This command is available in FS4 and C5. FlagShip supports date values from01/01/0001 to 12/31/9999. Warning: starting with FS4.42.448, the default EPOCHvalue changed to 1951 and is not equivalent to Clipper's default of 1900. To meetthe backward compatibility, use SET EPOCH TO 1900 at program begin.

Translation:SET (_SET_EPOCH, expN)

Related:SET CENTURY, SET DATE, CTOD(), DATE(), DTOC(), SET(), VERSION()

CMD 350

SET ESCAPESyntax:

SET ESCAPE ON|off|(<expL>)Purpose:

Toggles the possibility of terminating a READ with the Esc key.

Arguments:ON/OFF enables/disables the ESC as a READ exit key. Alternatively, theparenthesized <expL> may be used, whereby TRUE is the same as ON.

Description:SET ESCAPE OFF causes READ to ignore the Esc key.

By default SET ESCAPE is ON, allowing Esc to abort READ commands discardingthe changes and by-passing the validation of RANGE and VALID.

The redirection of the Esc key using SET KEY TO is not affected by SET ESCAPE.

Example:SET ESCAPE OFFSET FORMAT TO authorsUSE authorSET KEY 27 TO Esc_react && procedure for ESC keyREADSET KEY 27 TOSET ESCAPE ONPROCEDURE Esc_react (p1,p2,p3)LOCAL getlist := {}, answer := "N"@ 24,0 && clear line 24@ 24,0 SAY "Do you really want to terminate input (y/n)?" ;

GET answer PICTURE "!"READif answer = "Y"

KEYBOARD chr(3) && simulate PgDn keyendif@ 24,0 && clear line 24RETURN


Translation:SET ( _SET_ESCAPE, .T.|.F. )

Related:READ, SET KEY, SETCANCEL(), SET()

CMD 351

SET EVENTMASKSyntax:

SET EVENTMASK [TO] <expN>Purpose:

Set event mask for Inkey().

Arguments:<expN> is a INKEY_* constant specified in the inkey.fh file. Default at start-up isINKEY_ALL_BUT_MOVE

Description:The SET EVENTMASK command specifies which events should be considered andstored in the ahead buffer to be returned by the INKEY() function. All events notmatching the event mask are silently ignored. Using this mask you can haveINKEY() return only the events in which you are interested.

Also the Inkey() function has it own, optional event mask. The SET EVENTMASKdecides which keys or events are generally considered and stored, whilst theInkey()s event mask is an additional filter to receive specific, already stored events.



Related:Inkey(), InkeyTrap()

CMD 352

SET EXACTSyntax:

SET EXACT on|OFF|(<expL>)Purpose:

Toggles the way character strings are compared.

Arguments:ON/OFF enables/disables exact string comparison regarding the length.Alternatively, the parenthesized <expL> may be used, whereby TRUE sis the sameas ON.

Description:SET EXACT specifies how two strings are to be compared by the relationaloperators ( =, >, <, >=, <=, <>, #, != ). When EXACT OFF is set (the default), thefollowing rules for the comparison of <expC1> ? <expC2> apply:

•When <expC2> is a null string "", the result is always TRUE on =, >=, <=comparison and FALSE otherwise.

•When <expC1> is a null string "", the result is always TRUE on <, <=, <>, #, !=comparison and FALSE otherwise.

•If LEN(<expC2>) is greater then LEN(<expC1>), the result is FALSE.

•Otherwise, all characters in <expC2> will be compared to <expC1>. It returnsTRUE if all characters are equal or only trailing blanks remain in <expC1>;otherwise FALSE.

Note: when SET EXACT is OFF, the comparison results (intentionally) depends onthe operands sequence, empty strings and the trailing blanks in the secondoperand, which is the xBase standard.

When EXACT is ON, the two strings must match exactly, except for the trailingblanks in <expC1> or <expC2>.

A comparison using the double equal == operator is not affected by SET EXACTand returns TRUE only, if all characters and both lengths are exactly the same.

For a true string equality comparison, use a == b or !(a == b) respectively, sinceboth are independent of the SET EXACT status. Note that the !(a == b) syntax isnot the same as a != b and therefore the results may differ. The !=, # and <>operators are fully equivalent.

CMD 353

Example:// SET EXACT OFF SET EXACT ON? "123" = "12345" // .F. .F.? "12345" = "123" // .T. .F.? "123" = "" // .T. .F.? "" = "123" // .F. .F.? "123" = "123" // .T. .T.? "123" = "123 " // .F. .T.? "123 " = "123" // .T. .T.

? "123" == "123 " // .F. .F.? "123 " == "123" // .F. .F.

Example:Search exact matching, including string length:

USE custom INDEX nameIF SeekExact("Smith ")

? custno, nameELSE

? "Customer 'Smith ' is not available"ENDIFRETURN

FUNCTION SeekExact (expC)SEEK PADR (expC, LEN(&(INDEXKEY(0))))RETURN (FOUND())


Compatibility:In FlagShip (and Clipper 5.x), SET EXACT has no effect on operations other thanrelational operators. This includes the SEEK and FIND commands. If exact SEEK isrequired in other dialects, use the example above.

Translation:SET (_SET_EXACT, .T.|.F.)

Related:DISPLAY, FIND, LIST, LOCATE, SEEK, SET()

CMD 354

SET EXCLUSIVESyntax:

SET EXCLUSIVE ON|off|(<expL>)Purpose:

Switches the access status for all subsequently opened databases (.dbf) and theirassociated memo files (.dbt) and indices (.idx) to EXCLUSIVE (only one user at atime) or SHARABLE (multiuser).

Arguments:ON/OFF disables/enables the multiuser mode. Alternatively, the parenthesized<expL> may be used, whereby TRUE is the same as ON.

Description:If SET EXCLUSIVE is ON, the newly opened databases (with memo files andindices) will be accessible only from this user or program, until the database isclosed again. This switch is identical to the option USE <dbfname> EXCLUSIVE.SET EXCLUSIVE, however, is a general switch, USE...EXCLUSIVE is associatedwith the specified dbf only. On the other side, USE...SHARED will open thedatabase in multiuser mode, regardless of the SET EXCLUSIVE status.

If SET EXCLUSIVE is OFF, the newly opened databases (including memo files andindices) will share the access with other users or programs. Using the commandUSE...EXCLUSIVE will override the SET EXCLUSIVE state and open the databasein non-shareable mode.

Multiuser:The multiuser/multitasking mode is active after SET EXCLUSIVE OFF or theconsequent use of USE...SHARED. The AutoLock feature is effective only in thismode.

Before each write access in multiuser mode, the record or the whole file must belocked using RLOCK() or FLOCK(). The commands REINDEX, PACK and ZAPrequire an EXCLUSIVEly opened database. The command INDEX ON requiresFLOCK() or EXCLUSIVE usage. If the lock is not set by the programmer and SETAUTOLOCK is ON, FlagShip locks the record or file automatically by using theAUTOxLOCK() function.

Check the open success using the function NETERR() or USED(). Opening adatabase EXCLUSIVEly will succeed only if it is not already in use by some otheruser.

CMD 355

Example:SET EXCLUSIVE OFF && set multiuser modeUSE address ALIAS adr && open: shareableDO WHILE NETERR()

USE address ALIAS adr && see also USE examplesENDDOSET INDEX TO name, idno


Compatibility:In FlagShip, the EXCLUSIVE or SHARED mode applies also for the same databaseconcurrently, opened in different working areas, see the USE command. Theinternal locking mechanism of FlagShip conforms to the UNIX standard. The lockingmechanism of nearly all other xBASE derivates is mutually incompatible. TheAutoLock feature is available in FlagShip only.

Translation:SET ( _SET_EXCLUSIVE, .T.|.F. )

Related:USE, COMMIT, FLOCK(), RLOCK(), NETERR(), SET(), SET AUTOLOCK

CMD 356

SET EXTRASyntax 1:

SET EXTRA TO [<file>|(<expC>) [ADDITIVE]]Syntax 2:

SET EXTRA on|OFF|(<expL>) [NEW]Purpose:

Echoes the console output (e.g. of the ?, ?? commands) to an ASCII text file.

Arguments:TO <file> is the name of an ASCII text file to which the output will be redirected andcan include a path and an extension. If the file extension is not specified, .txt isassumed. When the TO... clause is not given, the opened extra file (if any) will beclosed.

Option:ADDITIVE causes the specified extra file to be appended to instead of overwritten.If not specified, the specified <file> is truncated.

Arguments:ON/OFF activates or deactivates the output to the current open extra file. Thetoggle will not be switched to ON if the extra file is not opened. Alternatively, theparenthesized <expL> may be used, whereby TRUE is the same as ON.

NEW causes the current file contents to be deleted, instead of appended to.

Description:FlagShip allows the redirection of console commands (such as ?, LIST, REPORTFORM, LABEL FORM) to four different devices/files at a time: the SCREEN device,and the ALTERNATE, PRINTER and EXTRA files or devices.

In commands, which support the TO FILE <file> clause (like LIST, REPORT FORMetc.), this clause is a synonym for SET EXTRA TO <file> ADDITIVE and SETEXTRA ON. When such a command is finished, the previous EXTRA status isrestored.

In other commands (like ?, ??, QOUT() etc.), an additional redirection to a text file(or device) using the SET EXTRA command is possible. Full-screen commands'output such as @...SAY cannot be echoed by the SET EXTRA command; use SETDEVICE instead.

When setting the output OFF, the extra file remains open. Closing the extra file withSET EXTRA TO will reset the toggle to OFF. Only one extra file may be opened ata time (in addition to the alternate and printer file).

CMD 357

Tuning:You may set the new-line character by 9th element in FS_SET("prset") e.g.

#ifdef FS_WIN32 /* here: should apply for Windows only */FS_SET("prset", {NIL,NIL,NIL,NIL,NIL,NIL,NIL,NIL,chr(13,10) } )

#endifbefore printing to EXTRA file via ? or QOUT(). The default setting is line-feed =chr(10).

Example:SET PRINTER TO all.doc && or: TO /dev/lp0SET ALTERNATE TO old.doc && or: TO /dev/tty15SET EXTRA TO new.doc && or: TO /dev/tty24SET PRINTER ONUSE address? "All customers:"DO WHILE .NOT. EOF() .AND. INKEY() # 27

IF lastdate < DATE() - 60SET ALTERNATE ON

ENDIFIF lastdate >= DATE() - 60

SET EXTRA ONENDIF? Name, Address, Zip, Town, lastdateSET ALTERNATE OFFSET EXTRA OFFSKIP

ENDDOSET PRINTER OFF? "Old customers (last access older than 2 months):"TYPE old.docWAIT? "New customers (last access within 2 months):"TYPE new.docWAIT


Compatibility:The command is available in FlagShip only, but is compatible with the Clipper 5behavior.

Translation:SET ( _SET_EXTRA, .on.)SET ( _SET_EXTRA, "file", .additive.)

Related:?, ??, DISPLAY, LIST, LABEL FORM, REPORT FORM, TEXT, TYPE, QOUT(),QQOUT(), SET ALTERNATE, SET PRINTER, SET()

CMD 358

SET FILTER TOSyntax:

SET FILTER TO [<condition>]Purpose:

Makes a database appear as if it only contains the records meeting the specifiedcondition.

Arguments:<condition> is a logical expression identifying a specific set of records. SETFILTER TO without an argument deactivates the filter.

Description:Each working area can have an active filter. When set, a filter becomes active onthe first movement of the record pointer in the corresponding working area, e.g.using the GOTO TOP command. The current filtering condition can be returned asa character string using the DBFILTER() function.

Most commands and functions that move the record pointer honor the current filtersetting. Filters have no effect on indexing. A filtered record can always be accessedwith GOTO, or any command specifying the RECORD scope.

Although SET FILTER makes the current working area appear as if it contains asubset of records, it in fact processes all records in the database sequentially.Therefore, setting FILTER and GOTO TOP needs the same time as the LOCATEcommand. For a large database, the usage of index, SEEK and subsequent DOWHILE <condition> is the much faster alternative.

Example:USE salesmenSET FILTER TO parts_sold >= 10 .and. parts_sold < 1000GO TOP // locate first match? "sales for: " + DBFILTER()DO WHILE !EOF()

? name, parts_soldSKIP

ENDDO

CMD 359

Example:Same example as above (now in multiuser mode), but much faster on a large dbf

IF !FILE("partsold" + INDEXEXT()) // if no indexUSE salesmen EXCLUSIVE NEW // exists,WHILE NETERR() // create it

USE salesmen EXCLUSIVEENDINDEX ON parts_sold TO partsoldUSE

ENDIFUSE salesmen SHARED NEW // open database inWHILE NETERR() // multiuser mode

USE salesmen SHAREDENDDOSET INDEX TO partsold // and assign index

// SEEK and "filter" applied records

SET SOFTSEEK ONSEEK 10 // first match +DO WHILE !EOF() .and. parts_sold < 1000 // filter condition

? name, parts_soldSKIP

ENDDOSET SOFTSEEK OFF


Translation:DBCLEARFILTER ()DBSETFILTER ({||condition}, "condition" )

Related:SET DELETED, DBFILTER(), LOCATE, SEEK, DBSETFILTER(), oRdd:Filter

CMD 360

SET FIXEDSyntax:

SET FIXED on|OFF|(<expL>)Purpose:

Defines whether the SET DECIMALS will control the display of numeric values, ornot.

Arguments:ON/OFF enables/disables the fixed decimal places display specified by SETDECIMALS. Alternatively, the parenthesized <expL> may be used, whereby TRUEis the same as ON.

Description:After a SET FIXED ON, all numeric values are displayed according to the last SETDECIMALS setting (the default is two decimal digits).

When SET FIXED is OFF, the standard display of numeric values depends on themathematical operation:

•On assignment (:= or =), the number of decimal digits of the variable or constantis stored in the receiving variable structure.

•On addition and subtraction (+, -, ++, --, += or -= ), the number of decimal placesof the operand with the greater number of decimal places is stored.

•On multiplication (* or *=), the sum of decimal places of both operands is stored.•On division (/, %, /= or %= ) and exponentiation (**, ^ or **=) operations, SET

DECIMALS value determines the number of decimal places to display. The samealso applies for the functions EXP(), LOG() and SQRT().

SET DECIMALS and SET FIXED only affect the way numbers are displayed (orstrings created by STR*(), PAD*(), TRANSFORM() etc.) and have no effect on theprecision of numeric calculations.

To display the numbers in another format, use the PICTURE clause of @..SAY [email protected]; the STR() or TRANSFORM() function can be used respectively.

Example:LOCAL numSET FIXED OFFSET DECIMALS TO 1? 1.23456 + 1 && 2.23456? 2.2 * 2.2 && 4.84? EXP(1) && 2.7? num := 10/3 && 3.3SET DECIMALS TO 0SET FIXED ON? num && 3? STR(num, 5, 3) && 3.333? TRANSFORM (num, "9.99999") && 3.33333

CMD 361


Translation:SET ( _SET_FIXED, .T.|.F. )

Related:SET DECIMALS, EXP(), LOG(), SQRT(), @..SAY..PICTURE, TRANSFORM(),STR(), SET()

CMD 362

SET FONTSyntax:

SET FONT [TO] [FACE] <family> [, <sizePt>][SIZE[<sizePt>]]

[BOLD] [UNDERLINE][UPRIGHT|ITALIC] [NORMAL]

Purpose:Sets new default font name and/or size and/or attribute, used for all consecutiveconsole output like QOut(), QQOUT(), @..SAY, @..GET etc. Apply also for printeroutput with SET GUIPRINT ON. Applicable for GUI mode, ignored otherwise.

Default is oAppWindow:Font, if not set

Arguments:<family> is the used font family. The available family depends on the installedfonts. Usually, at least "Helvetica", "Times" and "Courier" fonts are available.

<sizePt> is the font size in points. The common size is 10 (points), larger size is 10,smaller is 8 points.

UNDERLINE is a underlined face

BOLD is thicker boldface than NORMAL

ITALIC is a cursive face.

UPRIGHT is the usual character face and disables ITALIC

NORMAL disables BOLD, ITALIC and UNDERLINE settings

Description:In GUI, the default font is set at application begin corresponding to the screenmanager setting. You may change the font at any time later.

The fixed font is e.g. "Courier" where all characters have the same width and hencethe application behaves very similarly to terminal based i/o. The "Helvetica", "Arial"or "Times" are proportional fonts, where each character has different width. Itmostly looks more pretty, but the handling is slightly aggravated. FlagShip providesseveral functions to alleviate the handling with proportional fonts, e.g. StrLen2Col(),StrLen2pix(), SET GUIALIGN etc.

In GUI mode, SET FONT access/assign the m->oApplic:Font object. You thereforemay retrieve or set additional font properties by using the Font class, documented insection OBJ.

The low-level font selection is not performed directly by FlagShip, but is handled bythe underlying Qt and X11 or MS-Windows font manager. If the requested font andit characteristics is not found exactly "as is", a heuristic (and sometimes costly)search is used:

CMD 363

•a table of comparable typefaces is searched for similar font family,

•if even the replacement family is not found, "helvetica" or "arial" is searched for,

•if that too is not found, as a last resort a specific font to match to, ignoring theattribute settings, is searched through a built-in list of very common fonts

•if nothing apply, an error message displays.

The following attributes are then matched, in order of priority: character set,fixed/variable pitch, point size, weight, italic. If, for example, a font with the correctcharacter set is found, but with all other attributes in the list unmatched, it will bechosen before a font with the wrong character set but with all other attributescorrect. The point size is defined to match if it is within 20% of the requested pointsize. Of course, when several fonts match and only point size differs the closestpoint size to the one requested will be chosen.

For additional information about font handling, see also chapters LNG.5.3.1 (fonts),LNG.5.3 (difference between terminal and GUI i/o), LNG.5.4 (national characters),OBJ.FONT (the font class), SET PIXEL, Col(), Row(), Col2pixel(), Row2pixel(), SETGUITRANSL (using semi-graphic PC8 character set), SET GUIALIGN, SETROWALIGN, SET ROWADAPT, StrLen2Col(), StrLen2pix()

Hint: when changing the font, you may need to adapt the application window size tofit max. required rows and columns by invoking

oAplic:Resize(rows, columns, , .T.)to avoid automatic horizontal and/or vertical scroll bars, see also Resize()description in section OBJ.Application class

Example:? "Hello world, printed by"?? Set(_SET_FONTNAME) // Helvetica?? Set(_SET_FONTSIZE) // 10

SET FONT TO SIZE 14 ITALIC BOLD? "Hello larger world"if AppIoMode() == "G" // font change apply for GUI mode? "Font attributes: requested name=", m->oApplic:Font:FontName, ;"assigned/real name=", m->oApplic:Font:FontFamily, ;"size=", ltrim(m->oApplic:Font:Size) + "pt", ;"=", ltrim(m->oApplic:Font:SizePixel()) + "px", ;if(m->oApplic:Font:Normal, "NormalWeight ", "") + ;if(m->oApplic:Font:Pitch, "FixedPitch ", "") + ;if(m->oApplic:Font:Bold, "Bold ", "") + ;if(m->oApplic:Font:Italic, "Italic ", "") + ;if(m->oApplic:Font:Underline, "Underline ", "") + ;if(m->oApplic:Font:StrikeThru, "StrikeThru", "")

endif

CMD 364

SET FONT "Courier", 12m->oApplic:Resize(25, 80,, .T.) // resize to 80x25 accord.to font? "Hello with fix sized font" // output by courier 12 italic boldwait



Translation:_SetDefFont(family, sizePt, lUpright, lItalic, lNormal, ;

lBold, NIL, lUnderline)

Related:Set(_SET_FONTNAME), Set(_SET_FONTSIZE), Set(_SET_FONTITALIC),Set(_SET_FONTBOLD), Font class, SET FONT BASELINE

CMD 365

SET FONT ALIGNSET FONT BASELINESyntax:

SET FONT [ALIGN] BASELINE on|OFF|(<expL>)Purpose:

Enable/disable font alignment to base line. Apply for GUI mode, and for creatingprinter template via SET PRINTER GUI ON with subsequent printing by PrintGui(),ignored otherwise.

Arguments:ON/OFF enables/disables the automatic font alignment. Alternatively, theparenthesized <expL> expression may be used, whereby TRUE is the same as ON.The default setting is OFF.

Description:The default x/y alignment in GUI mode is on the top left character frame (markedwith + in the picture below), to allow start the output at 0,0 coordinates. Thecharacters "O-umlaut","h","p" are displayed as

--+---------------------------- ----- <- top character frame| * * | | | ^| ### | # | | || # # | # | | | oFont:Ascent| # # | ### | #### | || # # | # # | # # | || ### -| # # -| #### -| ---X- <- base line| | | # | || | | # | | oFont:Descent| | | # | |----------------------------- ---V- <- bottom character frame

------------------------------- ----- <- line spacing

where the size of (bottom - top) is returned by oFont:Height() - or in pixel byoFont:SizePixel() which corresponds to oFont:Ascend plus oFont:Descend. The linespacing is user definable by global variable _aGlobSetting[GSET_G_N_ROW_SPACING].

When you change the FONT size, the start position remain unchanged, i.e. largerfont has it base line located below the former font (or at higher Y position in view oftop/down coordinates):

BBBB 11 BBBBB 2222B B * 1 1 B B 2 2BBBBB i ggg 1 B B * ggggg 2B B i g g 1 BBBBB i g g 2

_ BBBB i ggg 111 _ B B i g g 2 __ base line 1g B B i g g 2

gg BBBBB i ggggg 222222 __ base line 2gg

ggg

CMD 366

Sometimes you may wish to align characters on it base line, eg. when using theFONT clause to display different fonts in the same output line (similarly to wordprocessor output), e.g.

SET FONT "Arial",12 // set standard font? "Big1" // output by standard fontSET FONT BASELINE ONoFont2 := Font{"Arial",20} ; oFont2:Bold := .T.?? "Big2" FONT oFont2 // output by temporary font

where the SET FONT BASELINE ON statement causes the second output to beshifted up so that it base line matches the base line of standard font:

BBBBB 2222B B * 2 2

BBBB 11 B B ggggg 2B B * 1 1 BBBBB i g g 2BBBBB i ggg 1 B B i g g 2B B i g g 1 B B i g g 2

_ BBBB i ggg 111 _ BBBBB i ggggg 222222 __ base lineg g

gg gggg

The same apply also for printing with enabled SET PRINTER GUI ON. Note thatSET FONT BASELINE takes effect only on the temporary font, assigned by theFONT clause of ?, ??, Qout(), QQout() and @...SAY; the output by default font(assigned by SET FONT) remain unchanged.

The SET FONT BASELINE does not change ROW() or COL() output, nor thedefault line spacing. Because of the output shift, this behaves with larger fontcorrectly only if you have enough space above, i.e. when the current ROW() is > 0.



Example:See <FlagShip_dir>/examples/printergui.prg

Translation:Set(_SET_FONT_BASELINE, [.T.|.F.] )

Related:SET FONT TO, ?, ??, @..SAY, Qout(), Qqout(), Font class, SET PRINTER,PrintGui()

CMD 367

SET FORMAT TOSyntax:

SET FORMAT TO <procname>Purpose:

Specifies a format procedure to be executed before every READ command.

Arguments:<procname> can be a user-defined procedure (UDP) or a file with the .fmt or .prgextension. If <procname> is not specified, the current FORMAT is deactivated.

Description:The only difference between format procedures and other procedures is the waythey are invoked. The format procedures are executed when a READ isencountered after a SET FORMAT.

SET FORMAT is a global setting, which means that there can only be one activeformat at a time. An other SET FORMAT statement in the format procedure willbecome active when the current format procedure terminates and will be executedby subsequent READs.

In the FORMAT procedure, all FlagShip commands and functions in addition [email protected] and @...GET, can be used.

Unlike the interpreted xBASE dialects, format files are not opened at runtime butcompiled and linked into the application. When the FlagShip compiler encounters aSET FORMAT command and the name of the procedure is unknown, it searchesthe current directory for a source file with the same name (and the .frm or .prgextension) in order to compile it. If not found, the object file has to be specified atlink time; otherwise an error "unresolved external _bb_<procname>" occurs.

Therefore, the name of the format procedure must be unique in the wholeapplication. It must differ from all the function, procedure and other format names,as well as from all the file names comprising the application when their extension isdiscarded. This means that, for example "test.fmt" and "test.prg" may not be partsof the same application.

Note that SET FORMAT TO is an obsolete command and is supported forcompatibility purposes only.

CMD 368

Example:SET FORMAT TO get_nameUSE authorsDO WHILE .NOT. EOF()

READSKIP

ENDDOUSESET FORMAT TO test // compiles test.frmREADRETURN

PROCEDURE get_name@ 10,0 CLEAR TO 10,79@ 10,10 SAY "First name: " GET first_name@ 10,50 SAY "Last name: " GET last_nameRETURN

Classification:programming, compiler

Compatibility:Unlike the interpreted xBASE dialects, the screen is not cleared before executingthe format procedure. Multiple-page formats are not supported. Note also thecompiler notes above.

Translation:_PROCREQ_ ("procname") ; __SETFORMAT ({|| procname() })

Related:@...SAY, @...GET, READ, PROCEDURE, DO...WITH

CMD 369

SET FUNCTION ... TOSyntax:

SET FUNCTION <expN1> TO <expC2>Purpose:

Defines a string that will be pushed into the keyboard buffer when the specifiedfunction key is pressed.

Arguments:<expN1> is the function key number (1..48), e.g. 8 for the F8 key.

<expC2> is the character string to assign to the function key. If <expC2> is notspecified, the current string assignment to a FN key is disabled.

Description:When the specified function key is pressed, the keyboard buffer is stuffed with thecharacter string which may contain any characters including control characters. Thefollowing keys can be assigned with SET FUNCTION (see also section SYS andthe FStinfo.src file):

expN1 Function Key terminfo1 - 10 F1 - F10 kf1...kf1011 - 20 shift F1 - F10 kf13...kf2221 - 30 ctrl F1 - F10 kf25...kf3431 - 40 alt F1 - F10 * kf37...kf4641 - 42 F11 - F12 ** kf11...kf1243 - 44 shift F11 - F12 ** kf23...kf2445 - 46 ctrl F11 - F12 ** kf35...kf3647 - 48 alt F11 - F12 * ** kf47...kf48

* The "Alt-FN" keys are seldom available on the UNIX terminals and systems, butare often supported by Ctrl+Shift+FN, see terminfo (e.g. FStinfo.src).

** The F11 and F12 key combinations are not supported by all of the DOSderivates. On UNIX, the usage is dependent on the terminal capability (seeFStinfo.src).

A key redirection to a UDF using SET KEY has precedence over SET FUNCTION.Initially when a program is started, the F1 key is redirected to the HELP procedure,if any. To SET FUNCTION for any key that has been redirected with SET KEY, firstthe SET KEY redirection must be disabled prior to the SET FUNCTION setting.

To determine the current FUNCTION setting of the specified FN key, the functionexpC := __GETFUNCTION (<expN1>) can be used; see also getsys.prg.

CMD 370

Example:// Each time F9 is pressed, the cursor jumps 4 GETs ahead

four_gets = REPLICATE(CHR(13),4)SET FUNCTION 9 TO four_getsSET FORMAT TO ArticlesUSE ArticleREADSET KEY F9 TOSET FORMAT TOUSERETURN


CompatibilityUnlike C5, SET KEY does not disable the current SET FUNCTION setting, buthides it only, similar to C87.

The ability of function keys depends on the current setting of the environmentvariable TERM, the respective terminfo description and the hardware capability.Refer to sections SYS and REF for available function keys according to yourterminal.

Translation:__SETFUNCTION (expN1, "expC2")

Related:SET KEY, KEYBOARD, <FlagShip_dir>/system/getsys.prg

CMD 371

SET GOTOPSyntax:

SET GOTOP on|OFF|(<expL>)Purpose:

Enable/disable automatic movement to database top

Arguments:ON/OFF enables/disables automatic database movement to the first logical recordafter USE... or USE..INDEX.. or SET INDEX.. command. Alternatively, theparenthesized <expL> may be used, whereby TRUE is the same as ON. Thedefault is OFF which enables programmable index integrity check and it silentrecovery by using INDEXCHECK() function.

Description:FlagShip automatically checks the database and index integrity, see chapterLNG.4.5. However, this index integrity checking disables the automatic movementto the database top, so when you are using SET FILTER or SET DELETED ON,you may need to issue GO TOP or DbGoTop() after open the database or assigningnew indices. You may force the GO TOP movement automatically by SET GOTOPON or Set(_SET_GOTOP,.T.) which will then handle same as Clipper, but disablesthe possibility of index check and it silent recovery.

Note: the SET GOTOP is considered only with the USE.. and SET INDEXcommands. Hence if you are using the DbUseArea() or OrdListAdd() functionsinstead of the commands, you will need to invoke DbGoTop() function (or GO TOPcommand) thereafter to move to the first logical database record.



Related:USE, SET INDEX, INDEXCHECK(), SET(_SET_GOTOP), GO TOP, DbGoTop()

CMD 372

SET GUIALIGNSyntax:

SET GUIALIGN ON|off|(<expL>)Purpose:

Align all @..GET columns in a GetList{} array according to the length of ..SAY.. textduring a READ or via GetAlign([GetList]) call. Apply only in GUI when @..SAY..GETis specified.

Arguments:ON/OFF enables/disables the aligning. Alternatively, the parenthesized <expL>may be used, whereby TRUE is the same as ON. The default setting is ON.

Description:In terminal based i/o or in GUI with fixed fonts, these lines

@ 10,1 say "first line " GET var1@ 12,1 say "other text " GET var2@ 13,1 say "anything else" GET var3READ

produces get/read fields all aligned at column 15. In GUI with proportional fonts, thecolumn of these GET fields will vary, since every of this commands says "displaythe @..SAY text in the specified row/column and start the GET input fields onecharacter behind the text end" which is done correctly. But it does not look as youwanted, since the width of these texts is different, where you want to get all thefields among one another. To do so, you may advise the READ (which has theinformation about the final layout from the objects in GetList array) by SET GUIALIGN ON to reformat/align these fields at the same column.

You also may invoke the GetAlign() function manually, outside of READ, withoutconsidering of the current SET GUIALIGN setting.



Source:The GetAlign() function is available in .../system/getsys.prg

Related:GetAlign(), Set(_SET_GUIALIGN), READ, @..SAY..GET

CMD 373

SET GUICOLORSSyntax:

SET GUICOLORS on|OFF|(<expL>)Purpose:

Enable colors also in GUI application

Arguments:ON/OFF enables/disables color support in GUI mode. Alternatively, theparenthesized <expL> may be used, whereby TRUE is the same as ON. Thedefault setting is OFF.

Description:Colors and lines drawing are disabled per default in GUI mode to get proper GUIlook & feel. You may enable the color support in GUI mode via SET GUICOLORON or Set(_SET_GUICOLORS,.T.).

The SET GUICOLORS influences the ?, ??, qout(), qqout(), @..SAY, @..GET,@..DRAW etc. console output.



Related:SET COLOR, Set(_SET_GUICOLORS)

CMD 374

SET GUICURSORSyntax 1:

SET GUICURSOR on|OFF|(<expL>)Syntax 2:

SET GUICURSOR TO <expN>Syntax 3:

SET GUICURSOR TOPurpose:

Enable/disable text cursor in GUI mode or specify the GUI cursor shape.

Arguments:ON/OFF enables/disables the display of text cursor in GUI mode. Alternatively, theparenthesized <expL> may be used, whereby TRUE is the same as ON. Thedefault setting is OFF. The corresponding function is SET(_SET_GUICURSOR,[<expL>]).

TO <expN> according to syntax 2 re-defines the default shapeCURSOR_UNDERSCORE, same as invoking SET(_SET_GUICURSORTYPE, val).The new shape is then displayed on subsequent screen output when SETGUICURSOR is ON. Valid shape values are:

mouse.fh constant value DescriptionCURSOR_ARROW -1 standard arrow cursorCURSOR_UPARROW -12 upwards arrowCURSOR_CROSS -8 crosshairCURSOR_WAIT -9 hourglass/watchCURSOR_IBEAM -11 i-beam (I)CURSOR_SIZE_VER -2 vertical resizeCURSOR_SIZE_HOR -3 horizontal resizeCURSOR_SIZE_RDIAG -5 diagonal resize (/)CURSOR_SIZE_LDIAG -4 diagonal resize (\)CURSOR_SIZE_ALL -13 all directions resizeCURSOR_INVISIBLE -17 blank/invisible cursorCURSOR_SPLITVER -14 vertical splittingCURSOR_SPLITHOR -3 horizontal splittingCURSOR_HAND -6 a pointing handCURSOR_FORBIDDEN -16 forbidden action cursorCURSOR_UNDERSCORE -21 underscoreCURSOR_BOX -22 box in size of one characterCURSOR_DEFAULT_TEXT -21 default = CURSOR_UNDERSCORE

TO according to syntax 3 sets the text cursor shape to it default state, i.e. toCURSOR_UNDERSCORE or the value assigned to the global variable_aGlobSetting[GSET_G_N_TEXTSHAPE].

CMD 375

Description:The behavior of an application in GUI mode with SET GUICURSOR ON is verysimilar to running it in textual mode. If set, the default (or user set) cursor shape isdisplayed behind the current screen output, i.e. at the Row(), Col() position,independent on the mouse cursor.

The SET GUICURSOR is considered in ?, ??, qout(), qqout(), @..SAY, SetPos()etc. console output. The text cursor is not displayed in special add-on widgets(controls) like READ, MemoEdit(), Tbrowse(), InfoBox() etc.

If you want to set text cursor shape anywhere on the user screen, independent onthe current output, use SetGuiCursor() and best to disable SET GUICURSOR usingthe OFF clause.

Note: The WAIT command use own shape to signal user's entry. If the SETGUICURSOR display is enabled, your cursor shape will be restored automatically atthe return from WAIT.

To set the shape of mouse cursor, use MsetCursor().

The SET GUICURSOR command is accepted also for other than GUI i/o modes,but no action is taken there.

Example:complete example is available in .../examples/guicursor.prg

Classification:screen oriented output in GUI mode

Translation:SET(_SET_GUICURSOR [, <expL> ])SET(_SET_GUICURSORTYPE [, <expN> ])


Related:SET CURSOR, SetGuiCursor(), SetPos(), MsetCursor(), WAIT

CMD 376

SET GUIPRINTERSyntax:

SET GUIPRINTER on|OFF|(<expL>)Purpose:

Enable or disable GUI alike printing via selected system driver. Applicable only inGUI mode, ignored otherwise.

Arguments:ON/OFF activates or deactivates the rendering for printer output.

Description:With enabled SET GUIPRINTER, the output is (additionally) rendered for selectedprinter, and subsequently printed by PrintGui() or by _oPrinter:ExecGui().

SET GUIPRINTER ON is equivalent to PrintGui(.T.), SET GUIPRINTER OFF isequivalent to PrintGui(.F.)

For further details, see function PrintGui()



Translation:SET ( _SET_GUIPRINTER, .T.|.F.)

Related:PrintGui(), SET PRINTER, SET CONSOLE, SET DEVICE, SET GUI*

CMD 377

SET GUITRANSLSyntax:

SET GUITRANSL ASCII on|OFF|(<expL>)SET GUITRANSL TEXTDRAW on|OFF|(<expL>)SET GUITRANSL BOX on|OFF|(<expL>)SET GUITRANSL LINES on|OFF|(<expL>)

Purpose:Enable support of semi-graphic characters also in GUI application and/orautomatically translate ANSI to ISO code

Arguments:ON/OFF enables/disables support of semi-graphic characters in GUI mode.Alternatively, the parenthesized <expL> may be used, whereby TRUE is the sameas ON. The default setting is OFF.

Description:In GUI mode, colors, boxes and semi-graphic characters are handled uponprogrammer's request only, since if would (in the most cases) break the look-and-feel of GUI, and the source cross-compatibility to terminal i/o mode.

Character set conversion, national and semi-graphic charactersIn GUI mode, the screen-output, and the output to GDI printer (via SET GUIPRINTON) is in ISO/ANSI mode (internally in Unicode). This ISO/ANSI character set haveno semi-graphics, and the byte representation of national characters ( i.e.CHR(128..255) ) differs to PC8/ASCII/OEM charset, refer to LNG.5.4 for differencesand to the ASCII-ISO comparison table in <FlagShip_dir>/manual/charset.pdf file.

The consequence is, that strings with national characters coded in editor supportingASCII/OEM/PC8 charset differs from strings coded in ISO/ANSI alike editor. Forexample, the output of ? "München" may or may not be displayed properly, sinceyour code contains different byte-representation of the u-umlaut. Or, the CHR(196)is horiz.line in ASCII/OEM, but A-umlaut in ISO/ANSI mode.

FlagShip however provides automatic conversion between these codes by usingSET SOURCE ASCII (default) or SET SOURCE ISO, see details there. For GUImode, you may additionally/differently control this translation by SET GUITRANSLASCII ON or OFF.

For text coded in PC8/ASCII/OEM character set (assumed by default), an automaticASCII -> ISO conversion is available via SET SOURCE ASCII and/or SETGUITRANSL ASCII ON. This setting converts automatically ASCII strings passed toi/o commands and functions to ISO character set, same as doing it manually viaOem2Ansi(string). If you wish to draw semi-graphic characters passed in ASCIImode, use additionally SET GUITRANSL TEXTDRAW ON.

For text passed in ISO/ANSI mode, SET GUITRANSL ASCII OFF should be used.In this mode, you cannot display semi-graphic characters (by SET GUITRANSL

CMD 378

TEXT ON) simultaneously with umlauts (or other special characters), since e.g. theCHR(196) = horiz.line in ASCII is equivalent to A-umlaut in ISO/ANSI mode (seethe comparison table). You however may draw semi-graphics by CHR(..) as well,see example below.

The SET GUITRANSL ASCII ON is equivalent to SET CHARSET ASCII, and SETGUITRANSL ASCII OFF is equivalent to SET CHARSET ISO.

The SET GUITRANSL ASCII ON is similar to SET SOURCE ASCII, but theseconds translates also output for terminal i/o and std. printer, whilst SETGUITRANSL affects screen (and SET GUIPRINT) translation only. Equivalently,SET GUITRANSL ASCII OFF is similar to SET SOURCE ISO, but w/o terminal andstd.printer influence.

To draw semi-graphic ASCII characters 179..218 in GUI mode, use SETGUITRANSL TEXT ON or Set(_SET_GUIDRAWTEXT,.T.) for an automatictranslation of text strings to graphic ASCII characters. If both GUITRANSLTEXTDRAW and GUITRANSL ASCII are ON, semi-graphic chars are not translatedto the ISO equivalence, but drawn as graphic in the ?, ??, @..SAY commands andQout(), Qqout() functions.

SET GUITRANSLASCII ON

translates ASCII source to ISO, this is set also by SETSOURCE ASCII or by SET CHARSET ASCII

SET GUITRANSLASCII OFF

(default) the source is in ISO charset, this is set also by SETSOURCE ISO or by SET CHARSET ISO

SET GUITRANSLTEXTDRAW ON

draws semi-graphic passed in ASCII code, when SETGUITRANSL ASCII is ON

SET GUITRANSLTEXTDRAW OFF

(default) disables semi-graphic drawing to be able printnational characters chr(128..255) passed in ISO mode andto ensure GUI look & feel

Boxes, linesBoxes and lines drawing are disabled per default in GUI mode, since standardwidgets/controls usually have own frames. To enable drawing lines and boxes [email protected].. and @..BOX in GUI mode too, use SET GUITRANSL LINES ON and/orSET GUITRANSL BOX ON, or the corresponding Set(_SET_GUIDRAWLINE, .T.)and Set(_SET_GUIDRAWBOX, .T.) function. You may draw lines also directly bythe @..DRAW.. command.

ColorsColors are disabled per default in GUI mode to get proper GUI look & feel. You mayenable the color support in GUI mode via SET GUICOLOR ON orSet(_SET_GUICOLORS, .T.). This will use the global SET COLOR setting, or theexplicit COLOR clause of many commands. Alternatively, you may use theGUICOLOR command clause for specific color setting, also without SETGUICOLOR ON.

CMD 379

All these commands and functions may remain global in the source code for ahybrid executables, they will be ignored when the application run in Terminal orBasic mode.


Example 1:* Display semi-graphics using ANSI/ISO program editorSET GUITRANSL ASCII OFF // input is ISO? "Text with embedded umlauts, e.g. München"saveStatus := set(_SET_GUIASCII)SET GUITRANSL ASCII ON // use ASCII charset? chr(218) + repli(chr(196),10) + chr(191)? chr(179) + space(10) + chr(179)? chr(192) + repli(chr(196),10) + chr(217)set(_SET_GUIASCII, saveStatus) // restore status? "continuing output in national charset"

Example 2:* Text is created with PC8/ASCII/OEM/DOS program editor* See full source in <FlagShip_dir>/examples/setsource.prg

SET GUITRANSL ASCII ON // or: SET SOURCE ASCIIstr1 := "This is text with embedded umlauts, e.g. München"str2 := "Continuing output with umlauts and accents, e.g. ÄäÖöÜü"

? str1 // display: This is text with embedded umlauts ...?? "Drawing semi-graphic characters"rr := row()SET GUITRANSL TEXT ON // To draw semi-graphic characterssaveFont := set(_SET_FONTNAME, "courier") // fixed font for spacing? space(3) + chr(218) + repli(chr(196),10) + chr(191)? space(3) + chr(179) + space(10) + chr(179)? space(3) + chr(192) + repli(chr(196),10) + chr(217)set(_SET_FONTNAME, saveFont) // restore font

@ rr, 36 say "Drawing box"SET GUITRANSL BOX ON // for GUI mode@ rr+1, 35, rr+3, 48 box color "B+" guicolor "B+"@ rr, 60 say "Drawing lines"SET GUITRANSL LINES ON // for GUI mode@ rr+1, 60 to rr+1, 70@ rr+2, 60 to rr+2, 70 double@ rr+3, 60 to rr+3, 70 double color "R+" guicolor "R+"setpos(rr+4,0)? str2 // display: Continuing output ...wait "done ..."

Example 3:* Text is created with ISO/ANSI program editor* See full source in <FlagShip_dir>/examples/setsource.prg

CMD 380

SET SOURCE ISO // implies SET GUITRANSL ASCII OFFstr1 := "This is text with embedded umlauts, e.g. München"str2 := "Continuing output with umlauts, e.g. ÄäÜüÖö"? str1 // display: This is text with embedded umlauts ...

/* To draw semi-graphic characters (=ASCII) with ISO char settings,* use SET GUITRANSL ASCII ON and SET GUITRANSL TEXT ON, or:*/saveStatus := set(_SET_GUIASCII, .T.) // SET GUITRANSL ASCII ONsaveAscii := set(_SET_SOURCEASCII, .T.) // SET SOURCE ASCIIsaveText := set(_SET_GUIDRAWTEXT, .T.) // SET GUITRANSL TEXT ON?? "Drawing semi-graphic characters"rr := row()saveFont := set(_SET_FONTNAME, "courier") // fixed font for spacing? space(3) + chr(218) + repli(chr(196),10) + chr(191)? space(3) + chr(179) + space(10) + chr(179)? space(3) + chr(192) + repli(chr(196),10) + chr(217)set(_SET_FONTNAME, saveFont) // restore font

@ rr, 36 say "Drawing box"SET GUITRANSL BOX ON // for GUI mode@ rr+1, 35, rr+3, 48 box color "B+" guicolor "B+"@ rr, 60 say "Drawing lines"SET GUITRANSL LINES ON // for GUI mode@ rr+1, 60 to rr+1, 70@ rr+2, 60 to rr+2, 70 double@ rr+3, 60 to rr+3, 70 double color "R+" guicolor "R+"

/* Note: to display national characters (umlauts etc.) coded in* ISO charset, the SET GUITRANSL TEXT ON must be disabled*/set(_SET_GUIASCII, saveStatus) // restore prev.statusset(_SET_SOURCEASCII, saveAscii)set(_SET_GUIDRAWTEXT, saveText)setpos(rr+4,0)? str2 // display: Continuing output ...wait "done ..."

Example 4:see <FlagShip_dir>/examples/umlauts.prg and pc8lines.prg for complete examples

Translation:SET GUITRANSL ASCII Set(_SET_GUIASCII [, <expL>])SET GUITRANSL BOX Set(_SET_GUIDRAWBOX [, <expL>])SET GUITRANSL LINES Set(_SET_GUIDRAWLINE [, <expL>])SET GUITRANSL TEXTDRAW Set(_SET_GUIDRAWTEXT [, <expL>])


Related:SET CHARSET TO..., Set(_SET_GUIDRAWTEXT), Set(_SET_GUIDRAWBOX),Set(_SET_GUIDRAWLINE), Set(_SET_GUITRANSASC), SET SOURCE

CMD 381

SET HTMLTEXTSyntax:

SET HTMLTEXT on|OFF|(<expL>)Purpose:

Enables or disables embedded HTML tags within the output text.

Arguments:ON/OFF enables/disables the support of embedded HTML tags within the consoleinput. Alternatively, the parenthesized <expL> may be used, whereby TRUE is thesame as ON. The default setting is OFF.

Description:In GUI mode, FlagShip supports RichText (using a subset of HTML and XML tags)in the standard output via ?, ??, Qout(), Qqout() and @..SAY.

You have two options to interpret HTML tags:

•As long as SET HTMLTEXT is ON, any console text is interpreted in RichTextformat, considering HTML tags.

•Even when SET HTMLTEXT is OFF, you may preface the text string by"<HTML>" which will force this specific output to be interpreted asHTML/RichText.

Supported HTML tags are:

HTML string Description... = print text part "xxx" in bold

... = print text part "..." in italic

... = print text part "..." underlined

<TT>...</TT> = print text part "..." in fixed font

<CENTER>...</CENTER> = print text part "..." centered

<PRE>...</PRE> = preserve white spaces in the "..." text

... 

= print text part "..." in color, where rr=red, gg=green,bb=blue RGB fraction given in hex notation (00, 80,FF), e.g.:hello

prints black "hello" text

hello

CMD 382

prints white "hello" text

helloprints gray "hello" text

helloprints red "hello" text

helloprints blue "hello" text

and so on. You also may use HTML color names like"yellow", "aqua" etc.

... 

= print text part "..." in another font size, nn is thelogical size (1 to 7) of the font. The value may either beabsolute, for example size=3, or relative like size=-2 orsize=+1.

... 

= print text part "..." in another font family of the font,for example face=times.

<HR> = draw horizontal line

 = new line

 or ... = new paragraph

<IMG src=file> = draw image file

<TABLE><TR><TD>colText</TD><TD>colText</TD></TR> ...etc...</TABLE>

= tables are also supported. You may use following<table > tags: bgcolor, width, border, cellspacing,cellpadding. The <TR> tags are: bgcolor. The <TD>tags are: bgcolor, width, colspan, rowspan, align.

Same as in HTML documents, the tags are case insensitive, i.e. "" and ""are equivalent. You also may combine the tags, e.g.@ 2,0 say 'underlined’ + ;

'redbold'If you wish to display the "<" character, you need to use "&LT;" instead. To displaythe ">" character, use the "&GT;" tag instead. Note that the passed string isscanned for RichText tags. You therefore may also split the output into two or moreparts, e.g.

? "displaying <" ; ?? "b> as is, uninterpreted"to reach the same effect. In some cases, you will need to add the "<html>" at thebegin of your string to force the interpretation and/or use

<tt>"<pre> text </pre>"</tt>to preserve spaces.

CMD 383

The Col() is adapted automatically to a larger/smaller font size but the Row() onlywhen SET ROWADAPT is ON (default is OFF). You also may force the adaptionmanually by invoking RowAdapt(). Both will also consider and line breaktags.

In addition to the RichText console output controlled by SET HTMLTEXT, theRichText is also supported by the MessageBox class and it subclassed functionsInfoBox(), TextBox{}, Alert() etc.

Note that the RichText is interpreted in GUI mode only. Regardless the SETHTMLTEXT setting, the HTML tags are printed "as is" in the Terminal and Basic i/omode or in the output sent to printer/file.

Example:? "<html>This text is displayed in bold and italic"? "This is text w/o HTML attributes, is a part of the text"

SET HTMLTEXT ONif AppIoMode() != "G"

? "Note: HTML formatting is supported for GUI mode only"endif? "This text is displayed in bold and bold italic"? "but the angle brackets < > requires corresponding tags,"SET HTMLTEXT OFF? "as opposite to the standard output which display < > fine."

Classification:programming, console oriented output

Translation:Set( _SET_HTMLTEXT [, <expL>] )


Related:?, ??, @..SAY, Qout(), Qqout(), InfoBox(), OBJ.MessageBox{}

CMD 384

SET INDEX TOSyntax:

SET INDEX TO [<fileList> [EXCLUSIVE]]Purpose:

Opens the specified index files in the current working area in the given order.

Arguments:<fileList> is a comma separated list of up to 15 index file names (.idx) to be openedin the current working area. Each index file can be specified as a literal filename oras a character expression enclosed in parentheses. A file name resulting in eitherspaces ("") or NIL is ignored. If an extension is not specified, .idx is assumed.

SET INDEX TO without an argument closes all indexes open in the current workingarea; so behaving as CLOSE INDEXES.

Options:EXCLUSIVE clause opens all indices specified in the <filelist> exclusively for thecurrent application, regardless of the SHARED status of the database. This is verysimilar to the status of the index file after performing the INDEX ON command. Anattempt to SET INDEX for the same index file from another user, will be denied andNETERR() set to TRUE. To reset the EXCLUSIVE status to SHARED mode,reopen the index file(s) using SET INDEX TO <filelist>.

Description:When more than one index is opened, the first specified index becomes thecontrolling index and the database is positioned to the first logical record in thatindex. SET ORDER changes the order of the controlling index. When assigning anempty index (created by INDEX.. ..FOR), both BOF() and EOF() return TRUE andthe record pointer is set beyond the end-of-file.

All open indices are properly updated according to the changes made to thedatabase. To stop the database pointer being repositioned while updating multiplerecords, issue SET ORDER TO 0.

Index file names may be specified by means of macro variables or parenthesizedexpressions. Each file name, however, must be in a separate variable.

When the open fails, NetErr() will report .T. When SET OPENERROR is ON (thedefault), an open failure will raise run-time error. For a full backward compatibility toFS 4.4, or to avoid RTE, use SET OPENERROR OFF and check the NetErr() statusthereafter. Multiple assignment of the same index file into the same work area is notallowed and will be ignored, this will also raise developer warning whenFS_SET("devel",.T.) is set.

During index assignments, the integrity of the index file compared to the database ischecked. If the check fails, the first database movement results in a warning if inFS_SET("developer") mode. For more details, see INDEX ON, INDEXCHECK() andLNG.4.5.

CMD 385

Multiuser:Instead of USE..INDEX.. it is better practice to open the database, check successby USED(), then assign index/indices by SET INDEX TO.. and check success byNETERR() which should be .F.

Tuning:As noted above, FlagShip do not raise run-time error on failure, so check byNETERR() reports failure or success. You however may force RTE 501 on failureby assigning

_aGlobSetting[GSET_L_DBSETINDEX_ERR] := .T. // default = .F.which then behaves FoxPro conform.

Example:SET EXCLUSIVE OFF && multiuser modeidx1 = "id_numb"idx2 = "name"idx3 = "salary"IF !FILE(idx3 + INDEXEXT()) && indices available?

USE personal EXCLUSIVE && no, create themDO WHILE NETERR()

? "waiting to become exclusive"INKEY (3)USE personal EXCLUSIVE

ENDDOINDEX ON idnumber TO (idx1)INDEX ON UPPER(name) TO &idx2INDEX ON salary TO salaryUSE

ENDIF

// open database and assign indices

USE personalDO WHILE NETERR() && multiuser: success ?

USE personal && - no, try againENDDOSET INDEX TO &idx1, (idx2), &idx3

SEEK 1234 && seek ID number? "ID 1234", FOUND(), nameSET ORDER TO 2 && index: nameSEEK UPPER("Smith")DO WHILE !EOF() .and. TRIM(UPPER(name)) == "SMITH"

? "Smith:", FOUND(), idnumberSKIP

ENDDO


Compatibility:The index files of FlagShip (.idx) are not compatible to their counterparts in xBASEDOS dialects (.NTX nor .NDX nor Foxbase .IDX), when the default DBFIDX driver isused. For compatible code, use INDEXEXT() or FS_SET ("translext", "ntx", "idx").

CMD 386

Keep in mind the case sensitive file names on UNIX or use FS_SET ("lower", .T.).For more details, see compatibility notes in section LNG.9.5.

After porting a DOS application and transferring the required databases (using abinary protocol), execute INDEX ON... to create the index files on the target UNIXsystem. The .idx files are compatible on the same UNIX hardware only.

Indices in VFS5, VFS6 and VFS7 are cross-compatible, but not compatible to FS4,you need to re-index these.

The EXCLUSIVE clause and the integrity check is available in FlagShip only.

Translation:DBCLEARINDEX () ; [ DBSETINDEX("index1") ...]

Related:CLOSE, INDEX, REINDEX, SET ORDER, USE, INDEXEXT(), NETERR(),FS_SET()

CMD 387

SET INPUTSyntax:

SET INPUT ON|off|(<expL>)Purpose:

Enables or disables the console input.

Arguments:ON/OFF enables/disables the console input. Alternatively, the parenthesized<expL> may be used, whereby TRUE is the same as ON. The default setting is ON.

Description:In special cases, the console input may be disabled. This setting is considered byInkey(), InkeyTrap(), INPUT, ACCEPT but not in FReadStd(), InStdChar(),InStdString().

When the input is disabled, the input function does not check the event queue orbuffer, but returns substitute character (usually ESC = 27), re-definable bySet(_SET_NOINPUTCHAR).



Related:Inkey(), Set()

CMD 388

SET INTENSITYSyntax:

SET INTENSITY ON|off|(<expL>)Purpose:

Defines whether the GETs and prompts in MENU TO will be displayed in the"standard" or the "enhanced" color.

Arguments:ON/OFF enables/disables the enhanced color setting. Alternatively, theparenthesized <expL> may be used, whereby TRUE is the same as ON.

Description:When INTENSITY is ON (the default), the active GET field in READ appears in theenhanced, all other GET fields in the "unselected" color, as specified or default. Thelight bar in MENU TO marking the current PROMPT selection also appears in the"enhanced" color and the cursor is hidden.

By setting INTENSITY OFF, GETs and the current PROMPT appear in the standardcolor. The cursor remains visible.

SET INTENSITY has no effect on ACHOICE() and DBEDIT().

Example:IF FS_SET("term") == "dummy" && which TERM used?

SET INTENSITY OFFENDIFSET FORMAT TO authorsUSE authorsREADSET FORMAT TOUSESET INTENSITY ON


Translation:SET ( _SET_INTENSITY, .T.|.F. )

Related:@..GET, READ, @..PROMPT, MENU TO, SET COLOR, SETCOLOR(), SETCURSOR, SETSTANDARD, SETENHANCED, SET()

CMD 389

SET KEY ... TOSyntax:

SET KEY <expN> TO [<procname>]Purpose:

Defines a procedure to be executed whenever the specified key is pressed in a waitstate.

Arguments:<expN> is the ASCII value of the key, including negative numbers for function keys,see INKEY() values.

Options:<procname> is the name of the procedure to be executed when the key is pressed.If <procname> is not specified, the current redirection of the <expN> key iscanceled.

Description:When the defined procedure is executed from a wait state, FlagShip invokes theUDP similarly as in the usual procedure call

DO <procname> WITH PROCNAME(), PROCLINE(), READVAR() [,lastKey]

but will use an internal code block instead. Using these parameters, contextsensitive reactions or help from within the procedure can be implemented. Note thatcode-block and the some of the procedure names in the call-stack may be filteredout, so the first and second passed parameter may differ from ProcName() andProcLine(), see details in FUN.HELP().

expN Associated Key Notes Unix terminfo28 F1 kf1-1 ... -9 F2 - F10 kf2...kf10-10 ... -19 shift F1 - F10 kf13...kf22-20 ... -29 ctrl F1 - F10 kf25...kf34-30 ... -39 alt F1 - F10 * kf37...kf46-40 ... -41 F11 - F12 ** kf11...kf12-42 ... -43 shift F11 - F12 ** kf23...kf24-44 ... -45 ctrl F11 - F12 ** kf35...kf36-46 ... -47 alt F11 - F12 * ** kf47...kf48

18, 3 PgUp, PgDn *** kpp, kpn1, 2, 3.. ^A, ^B, ^C, ... -65, 66, 67.. A, B, C, ... -

* The "Alt-FN" keys are sometimes not available on UNIX terminals, but are thenoften supported by Ctrl+Shift+FN, see terminfo (e.g. FStinfo.src). In X11 andWindows, several Alt-FN combinations are hard-wired to window manager

CMD 390

** The F11 and F12 key combinations are not supported by all of the DOSderivatives. On UNIX, their usage depends on the terminal capability (seeFStinfo.src).

*** See INKEY() or the "inkey.fh" file for other numeric codes and their DEFINEequivalents.

The SET KEY redirection is active in ACHOICE(), DBEDIT(), MEMOEDIT(),ACCEPT, INPUT, READ and WAIT but not in INKEY(). For its usage or simulationin INKEY(), see getsys.prg.

A maximum of 32 keys may be defined/redirected at one time. The F1 key is initiallyredirected to a procedure named HELP, if such exists.

SET KEY has precedence over SET FUNCTION, SET ESCAPE andSETCANCEL(). A maximum of 32 keys can be set at the same time. The SET KEYredirection is a global setting and therefore also remains active during an invocationof other UDFs or UDPs or on returning to a higher program level.

When designing a "background" procedure, it is good programming technique topreserve the current status of the application (i.e., screen appearance, currentworking area, etc.) and to restore it before exiting. CLEAR should not be used toclear the screen within a "background" procedure since it also clears GETs andtherefore terminates READ. Use CLS, CLEAR SCREEN or @...CLEAR instead. Toterminate the current READ from a "background" procedure, issue:

Command ActionCLEAR GETS Terminate READ, do not save current GETBREAK Terminate READ, do not save current GETKEYBOARD chr(23) Terminate READ, save the current GETKEYBOARD chr(27) Terminate READ, do not save current GET

When using the redirection to a STATIC PROCEDURE (or STATIC FUNCTION),the same rules as in code blocks apply: the SET KEY command must be specifiedin the same .prg file, where the STATIC procedure is defined; otherwise the<procname> will be invisible/undefined. When using redirection to a globalprocedure or UDF, the SET KEY can be defined anywhere.

You also may automatically invoke / trigger procedure, function or code block inspecific time intervals by using TriggerUdf() from FS2 Toolbox.

The HELP procedure or function (see FUN.HELP) is a special case of "background"procedure. It is already pre-defined and assigned to F1-key at program begin.

CMD 391

Example:Using the SET KEY redefinition to display the available article groups, when the[F3] key is pressed while being located in the entry field "group". In this example, itis assumed that there are just a few records in the artgroup.dbf database(otherwise, use DBEDIT() or TBROWSE instead of ACHOICE()).

#include "inkey.fh"STATIC showarr := NIL

PROCEDURE mainLOCAL menuUSE article INDEX article NEWmenu := menu_choice()IF menu == 1 // new entry

IF new_modif (.T.)APPEND BLANKREPLACE ...

ENDIFELSEIF menu == 2 // modify

IF new_modif (.F.)REPLACE ...

ENDIFENDIF

FUNCTION new_modif (newentry)PRIVATE Xarticle, Xgroup, Xprice

IF newentryXarticle := 0Xgroup := space(20)Xprice := 0

ELSEXarticle := article->articleXgroup := article->groupXprice := article->price

ENDIFSET KEY K_F3 TO show_group@ 5, 10 GET Xarticle PICTURE "999999"@ 6, 10 GET Xgroup PICTURE "!!!!!"@ 7, 10 GET Xprice PICTURE "99,999.99"READRETURN LASTKEY() # K_ESC

PROCEDURE show_group (procName, procLine, varName)LOCAL savescr := SAVESCREEN (10,50,MAXROW(),79)LOCAL choiceIF .not. (varName == "XARTICLE" .or. varName == "XGROUP")

RETURNEND@ 10,50 CLEAR TO MAXROW(),79@ 10,50 TO MAXROW(),79 DOUBLEIF VALTYPE(showarr) != "A" // initialized ?

initArray() // no, do it nowENDIF

CMD 392

choice = ACHOICE (11,51, MAXROW() -1, 78, showarr)IF choice > 0

Xgroup := SUBSTR(showarr[choice], 1, 5)ENDRESTSCREEN (10,50,MAXROW(),79, savescr)RETURN

FUNCTION initArrayLOCAL act_select := SELECT()IF VALTYPE(showarr) != "A" // initialized ?

showarr := {} // not yetUSE artgroup INDEX artgroup NEWWHILE !eof()

AADD (showarr, group + " " + textgroup)SKIP

ENDSELECT (act_select)

ENDRETURN NIL

// Compile: $ FlagShip test.prg -Mmain -na


Compatibility:Most other xBASE dialects do not support F11 and F12 keys and theircombinations. In Terminal i/o mode, refer to sections SYS, REF and the currentterminfo file (e.g. <FlagShip_dir>/terminfo/ FStinfo.src) for FN keys availableaccording to the currently assigned terminal (by TERM, FSTERM, TERMINFO andFSTERMINFO envir. variables, see section FSC.3.3). The SET KEY command ofdBASE IV has another functionality, but its ON KEY..DO.. is very similar toFlagShip's (and Clipper's) SET KEY.

Include:The INKEY() key numbers <expN> are defined in the #include "inkey.fh" file.

Translation:SETKEY (expN, {|p1, p2, p3, p4| procName(p1, p2, p3, p4)} )

Related:HELP(), SET FUNCTION, KEYBOARD, LASTKEY(), PROCLINE(), PROCNAME(),READVAR(), SETKEY(), FS2:TriggerUdf()

CMD 393

SET KEYTRANSLSyntax:

SET CHARSET|KEYTRANSL [TO] ISO|ANSISET CHARSET|KEYTRANSL [TO] PC8|ASCII|OEM

Purpose:Translates the keyboard values > 127 to Inkey() value and the screen outputaccordingly. Applicable/considered in GUI mode only.

Arguments:ANSI|ISO use default keyboard scan codes corresponding to your keyboard setting(which are ISO/ANSI values in GUI mode). The inkey codes are taken from thetable in Fsguikey.def, user definable via FS_SET("guikey",file_name)

PC8|ASCII|OEM activates an automatic translation of the inkey value fromISO/ANSI to PC8/ASCII/OEM character set. This will produce same Inkey value as

key := Ansi2oem( Inkey(0) )with SET KEYTRANSL set to ANSI

Description:In GUI i/o mode, both the screen input and output are handled in ISO/ANSI modeper default.

SET KEYTRANSL is mainly used to map/translate an user input to the samecharacter set/mode used also for output.

- If you are using ISO/ANSI/Windows character set for your source code (i.e. theeditor is for GUI mode or MS-Windows character set), you don't need change thedefault setting SET GUITRANSL ASCII OFF and SET KEYTRANSL ISO. In thismode, the u-umlaut is represented in ISO-8859-1 charset by chr(252) - as oppositeto chr(129) in PC8/ASCII mode.

- If you prefer to use PC8/ASCII character set coding (same as in DOS/Clipper or inthe most of terminal applications), you may set

SET SOURCE ASCII // translate output and inputwhich is also set in

#include "fspreset.fh" // see LNG.9.5

The generalized command SET SOURCE ASCII is a shortcut forSET GUITRANSL ASCII ON // translate outputSET KEYTRANSL ASCII // translate inputSet(_SET_PRINTASCII, .F.) // don't translate printer ISO->ASCIISet(_SET_SOURCEASCII, .T.) // source is in ISO character set

It will then display chr(129) as u-umlaut, and Inkey() will return 129 when pressingthe u-umlaut key. With separate SET GUITRANSL and SET KEYTRANSL youhowever may precise control a different behavior.

CMD 394

Example:see example in SET SOURCE


Translation:SET KEYTRANSL ISO = SET(_SET_CHARSET, _SET_CHARSET_ISO)SET KEYTRANSL ANSI = SET(_SET_CHARSET, _SET_CHARSET_ISO)SET KEYTRANSL ASCII = SET(_SET_CHARSET, _SET_CHARSET_PC8)SET KEYTRANSL PC8 = SET(_SET_CHARSET, _SET_CHARSET_PC8)SET KEYTRANSL OEM = SET(_SET_CHARSET, _SET_CHARSET_PC8)


Related:Ansi2oem(), Oem2Ansi(), FS_SET("ansi2oem"), SET ASCII, SET ANSI, SETGUITRANSL ASCII, SET SOURCE

CMD 395

SET LARGEFILESyntax:

SET LARGEFILE on|OFF|(<expL>)Purpose:

Sets or disables the capability of large file support.

Arguments:ON/OFF enables/disables the capability of large file support for databases over 2Gigabytes. With LARGEFILE ON, the system limit is increased up to 2 Terabytes(system dependant). The default setting is OFF to ensure backward compatibility toavailable databases. Alternatively, the parenthesized <expL> may be used,whereby .T. is the same as ON.

Description:Enable LARGEFILE to create or manage databases exceeding the 2GB limit.Available only on operating systems supporting large files (most of, e.g. AIX, Linux,Windows). You may check the status by Set(_SET_LARGEFILE) after executingSET LARGEFILE; it returns .T. when large files are supported.

If required, enable large files support latest before open the database.

Example:SET LARGEFILE ONif !set(_SET_LARGEFILE)

? "Large file support not available; this operating system"? "does yet not support it"waitquit

endifUSE myData SHARED...

Classification:programming, databases, file input/output

Compatibility:SET LARGEFILE is available in FS6 (and up) only.

Translation:SET ( _SET_LARGEFILE, <expL> )

Related:USE

CMD 396

SET MARGIN TOSyntax:

SET MARGIN TO <expN>Purpose:

Sets the left margin for all printed output.

Arguments:<expN> is the column number or the margin size in current coordinates to whichthe left margin is to be set. The default margin value is zero.

Description:SET MARGIN affects the printer output in two different ways:

1. when SET GUIPRINTER (or SET PRINTER GUI) is OFF (the default) and SETPRINTER is ON, or the ...TO PRINTER clause is used, the <expN> number ofspaces is printed in the front of a new line. With SET DEVICE TO PRINTER, the<expN> value is added to column during the @..SAY output. The PCOL() valuereflects the current print column position, including the margin. You may tune theprinter output by FS_SET("prset") which may be advantageous when usingproportional character set etc.

2. when SET GUIPRINTER (or SET PRINTER GUI) is ON and SET PRINTER isON or PrintGui(.T.) is active, the <expN> value is considered for the printeroutput. This GUI output mode does not consider the FS_SET("prset") tuning,and the PCOL() return value is not affected by <expN>.

SET MARGIN has no effect on SCREEN and FILE or EXTRA output.

Example: print to device or spooler file// SET PRINTER TO LPT3// SET PRINTER TO /dev/lp2// SET PRINTER TO ("myprint.txt")SET MARGIN TO 10 // add 10 spaces at left marginSET CONSOLE OFF // disable screen output

USE addressLIST Name, Area, Subarea TO PRINTER // print to device or file

SET CONSOLE ON // enable screen output// SET MARGIN TO // reset margin to 0wait "printed to " + fs_set("printfile") + " - any key..."// SET PRINTER TO // close spooler file if any

CMD 397

Example: create spooler file and print to GDI printer with previewSET COORD UNIT TO CM // or ...TO ROWCOL, MM, INCH, PIXELSET MARGIN TO 1.5 // left printout margin will be 1,5 cm// SET PRINTER TO ("myprint.txt")SET PRINTER ON // activate printer outputSET PRINTER GUI ON // creates spooler file for GDI printer

// SET CONSOLE OFF // optional, don't print to screen// SET EJECT ON // default: autom. EJECT on full page

USE addressLIST Name, Area, Subarea // print to spooler file

SET PRINTER OFF // printout is readySET CONSOLE ON // enable screen outputSET COORD UNIT TO // reset coordinates to default row/colwait "printed to " + fs_set("printfile") + " - any key..."// SET MARGIN TO // reset margin to 0

if AppIoMode() == "G" // only if running in GUI mode:ok := PrintGui() // print

endif// SET PRINTER TO // close spooler file if set


Translation:SET ( _SET_MARGIN, expN)

Related:@...SAY, SET DEVICE, SET PRINTER, SET GUIPRINTER, FS_SET("prset"),PCOL(), PrintGui(), OBJ:Printer class

CMD 398

SET MESSAGE TOSyntax:

SET MESSAGE TO [<expN> [CENTER|CENTRE] ]Purpose:

Defines the row and centering for the display of @...PROMPT messages whenexecuting MENU TO.

Arguments:<expN> is the row where the messages will be displayed. If there is no argument,or if <expN> is zero, messages will not be displayed.

Options:CENTER: When specified, the message texts are centered. Otherwise, eachmessage starts at column zero.

Description:When the clause MESSAGE is specified by the @... PROMPT command, MENUTO displays this message text on the row, given by SET MESSAGE when thePROMPT item is selected. This can be used for a short context specific help.

Example:SET MESSAGE TO 22 CENTER // msg on line 22@ 21,0 TO 21,79 DOUBLE // draw line@ 5,30 PROMPT "Append" MESSAGE "Add and edit a new record"@ 6,30 PROMPT "Change" MESSAGE "Edit current selectd. data"@ 8,30 PROMPT "Quit" MESSAGE "Exit to main menu"MENU TO choice

Classification:programming (and screen oriented output in MENU)

Translation:SET (_SET_MESSAGE, expN) [; SET (_SET_MCENTER, .T.|.F.)]

CMD 399

SET MULTIBYTESyntax:

SET MULTIBYTE on|OFF|(<expL>)Purpose:

Sets or disables the capability of multi-byte character support.

Arguments:ON/OFF enables/disables the capability of READ and other input processes tohandle multi-byte character set (like Chinese etc). The default setting is OFF toavoid flickering. Alternatively, the parenthesized <expL> may be used, whereby .T.is the same as ON.

Description:Enabled MULTIBYTE support will handle Asian 2-byte characters (glyphs) inGET/READ and MemoEdit(). Multi-byte characters contains two bytes chr(128..255)plus chr(1..255). Lower ASCII characters chr(1..127) are handled as single-byte andcan be intermixed with multi-byte glyphs in the same entry or line.

When enabled and upper ASCII character chr(128..255) is entered, READ andMemoEdit() waits for second character of the glyph.

On Linux in Terminal i/o mode, you will need to use proper window Terminal (e.g.mlterm or xiterm instead of Gnome/KDE console) for a correct support of multi-bytecharacters, see example below.

Since SET MULTIBYTE ON interprets chr(128..255) as begin of glyph (if notchanged, see Tuning), you cannot enter international single- byte characters likeUmlauts etc. in this mode. With MULTIBYTE ON, you may detect slight flickering onslower computers. Helpful links:

http://www.xuexizhongwen.de/chinese_t7.htmhttp://www.xuexizhongwen.de/index.htm?computing_t20.htm&1http://www.schaepermeier.de/linux/l_japanisch_d.htmhttp://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/pdf/Chinese-HOWTO.pdf http://www.suse.de/~mfabian/suse-cjk.pdf

Tuning:The glyph range is freely configurable by assigning the range from ...to as sub-array(or nested sub-array) inkey-values to

_aGlobSetting[GSET_A_MEMO_GET_GLYPH1]:= {128,255}_aGlobSetting[GSET_A_MEMO_GET_GLYPH2]:= {{1,31},{33,255}}

where these defaults says: the 1st glyph byte is in range chr(128) to chr(255) andthe 2nd glyph byte is in range chr(1..31) and/or chr(33..255). The Inkey() time-outperiod is set per default to 10 seconds and can be changed by assigning

_aGlobSetting[GSET_N_MEMO_GET_MULTIW] := 10.0 // defaultwhere the numeric value is equivalent to Inkey() argument, i.e. 0.0 will wait endlessuntil the user enters second glyph key. When the time-out expires without keypress, the first key is then interpreted as is - which however may cause incorrect

CMD 400

display of subsequent glyphs. When the above setting is greater 1 (or is 0), onebeep sounds after 1 second to remember you to enter second part of the glyph, andtwo beeps sounds when the time-out expires. You may set the number of beeps by

_aGlobSetting[GSET_N_MEMO_GET_BEEP1] := 1 // default 1 beep_aGlobSetting[GSET_N_MEMO_GET_BEEP2] := 2 // default 2 beeps

or disable it/them by assigning 0.

Example:SET MULTIBYTE ONmyData := space(20)@ 1,1 SAY "enter Chinese chars" GET myDataREAD

Example of start-up script on Linux:#!/bin/sh# shell requirement for Linux in Terminal i/o mode:export LC_CTYPE=zh_TW.Big5export LANG=zh_TW.Big5export LC_ALL=zh_TW.Big5## xcin &## scim &skim &XMODIFIERS="@im=skim"; export XMODIFIERSecho "---chinese"echo "LANG=$LANG"## echo ".. opening xiterm"## xiterm &echo ".. opening mlterm"## mlterm &mlterm --bg=black --fg=white --term=mlterm &

Classification:programming, screen input/output

Compatibility:SET MULTIBYTE is available in FS6 (and up) only.

Translation:SET ( _SET_MULTIBYTE, <expL> )

Related:READ

CMD 401

SET MULTILOCKSSyntax:

SET MULTILOCKS on|OFF|(<expL>)Purpose:

Sets or disables the capability of multiple record locking.

Arguments:ON/OFF enables/disables the capability to RLOCK() multiple records. The defaultsetting is OFF. Alternatively, the parenthesized <expL> may be used, wherebyTRUE is the same as ON.

Description:When a database is open in SHARED (multiuser) mode, any write access requiresa record or file lock. Usually, the RLOCK() locks the current record only, andFLOCK() is used for multiple record replacements. For a large application withmany users, locking a specified region of the database for a transaction may bemore efficient, allowing the remaining records to be replaced also by others.

When MULTILOCKS is OFF (the default), any attempt to RLOCK(),AUTORLOCK(), FLOCK() or APPEND BLANK will release all previous locks.

When MULTILOCKS is set ON, any consecutive attempt to RLOCK() orAUTORLOCK() (but not APPEND BLANK or DBAPPEND()) will add the recordnumber to an internal list of locked records. FLOCK() releases all previous recordlocks first.

The UNLOCK (or UNLOCK ALL) command will release all locked records,regardless of the SET MULTILOCKS state. You may release a specific RLOCK byusing DBRUNLOCK().

Note, the oRDD:RLOCK() does not consider the SET MULTILOCKS state, butdetermines it from the parameter passed.

Example:USE mydbf SHAREDgoto 5RLOCK() // locked: recno 5 onlyRLOCK(10) // locked: recno 10 only? RECNO() // 5 (remains unchanged)SET MULTILOCKS ONgoto 3RLOCK() // locked: recno 3 and 10RLOCK(7,8) // locked: recno 3, 7, 8 and 10

oRdd := DBOBJECT()? "List of locked records:"aeval (oRdd:RlockList, {|x| qout("RecNo", x)} )UNLOCK // release all locks

CMD 402


Compatibility:SET MULTILOCKS is not available in C5 and VO, but compatible to FoxPro.

Note for FoxPro users: SET MULTILOCKS will not perform an automatic UNLOCKALL. If such behavior is required, you may add the statement

SET MULTILOCKS <x:ON,OFF,&> => ;DBUnlockAll() ; SET(_SET_MULTILOCKS, <x>)

in your source file, or at the end of the std.fh file.

Translation:SET ( _SET_MULTILOCKS, <expL> )

Related:RLOCK(), UNLOCK, DBRUNLOCK(), SET(), oRdd:RLOCK(), oRdd:RLOCKLIST

CMD 403

SET NFSSyntax:

SET NFS on|OFF|(<expL>)SET NFS_FORCE on|OFF|(<expL>)SET NFSLOCK on|OFF

Purpose:Enable additional security handling and buffer flushing for databases and indicesmounted via NFS or SAMBA

Arguments:ON/OFF enables/disables special handling of index files on NFS file system.Alternatively, the parenthesized <expL> may be used, whereby TRUE is the sameas ON. The default setting is OFF.

Description:In some NFS versions (e.g. Linux 2.4.x NFS server), and in SAMBA, the buffercaching is over-optimized, so the standard FlagShip locking and file flushing doesnot force the server to update all buffers to the hard disk, especially on heavyloaded server. In some cases, the insufficient system cache flushing may corruptthe database or index(es) located on the server.

As long as SET NFS is ON, FlagShip's DbfIdx RDD issues additional actions likeinternal locks and forced data flushing to fix the above described NFS or SAMBAserver problem. Since this may slow-down the performance for pure server or localbased access, best to enable SET NFS ON only in applications that accessremotely mounted databases and indices via NFS or SAMBA.

For your convenience, the USE command has optional NFS clause too; this willinvoke SET NFS ON, so the special NFS handling remains active also for allsubsequent database actions, until SET NFS is set OFF.

Note: To mount the remote filesystem via NFS, you will need to use at leastnfsvers=3,rw,lock,sync mount options. But you will get better performance, whenthe executable run on the server (because of local HD access) with SET NFS OFF(default) by "shuffle" only the user i/o through the network. You may execute theapplication via ssh, telnet, emulators, X11 redirection or X11 emulator for MS-Win,CGI, mirroring etc. see also http://www.fship.com/emulators.html for details.

Note: to mount the remote filesystem via SAMBA (e.g. for concurrent Unix/Linuxand MS-Windows access), you need to specify/enable at least "path =/your_share_path", "read only = no", "create mask = 0664", "directory mask = 0775"in the [your_share_drive] section of /mnt/server/etc/samba/smb.conf and"workgroup = your_windows_group", "unix extensions = Yes", "security = user","encrypt passwords = Yes", "client code page = 850", "character set = ISO8859-15"in the [global] section of the same Samba config file. You will then access the<your_share_path> via usual mount as nfs (or as smbfs) type and from MS-Windows as usual network drive.

CMD 404

For concurrently use of Unix/Linux and MS-Windows based FlagShip applications(usually on SAMBA system), you often need to use SET NFS ON to avoid flushingproblems.



Translation:SET ( _SET_NFS_FORCE, <expL> )

Related:USE, DbUseArea(), SET INDEX TO, IndexCheck()

CMD 405

SET OPENERRORSyntax:

SET OPENERROR ON|off|(<expL>)Purpose:

Display database and/or index open failure.

Arguments:ON/OFF enables/disables raising run-time-error message when the databaseand/or index file could not be opened, e.g. because the file is not available or thereis not sufficient permission. The default is ON, which means the open i/o RTE aredisplayed. If set OFF, you need to check the USE or SET INDEX TO successmanually via Used() and NetErr(). Alternatively, the parenthesized <expL> may beused, whereby TRUE is the same as ON.

Description:The SET OPENERROR command allows you to control and to react on databaseand index open failure manually checking the Used() and NetErr() status.



Translation:Set(_SET_OPEN_ERROR, <expL> )

Related:USE, Used(), DbUseArea(), SET INDEX, DbSetIndex(), NetErr()

CMD 406

SET ORDER TOSyntax:

SET ORDER TO [<expN>]Purpose:

Identifies the specified index number as the (master) controlling index.

Arguments:<expN> specifies which index number, according to the position in the list of openindices, will become the controlling index. The valid range is 0 to 15. If <expN> isnot specified, ORDER is set to zero.

Description:When assigning the associated indices to the working area using SET INDEX TO orUSE...INDEX, all these indices are automatically updated while changing thedatabase fields.

By using SET ORDER, the required index is declared as the controlling one.Changing the index order does not change the database record position.

SET ORDER TO 0 deselects the controlling index, switches to the natural order ofrecords in the database, but leaves all the indices open. This is useful for replacingan area of indexed records without having the index interfering with the position inthe database.

Tuning:To avoid resetting FOUND() value to .F. when changing index order, set the globalswitch to_aGlobSetting[GSET_L_FOUND_SETORDER] := .T. // .F. default

which then behaves similarly to Clipper.

Example:USE employeesSET INDEX TO persid, name, born, salary? RECNO(), Idno, Lastname, Salary && 1, Jones, 25000SET ORDER TO 2? RECNO(), Idno, Lastname, Salary && 1, Jones, 25000GO TOP? RECNO(), Idno, Lastname, Salary && 52, Aaron, 23500SET ORDER TO 0REPLACE ALL lastname WITH "Mueller" ;

FOR TRIM(lastname) == "M• ller"SET ORDER TO 2SEEK "Müller" && not foundSEEK "Mueller" && found

CMD 407


Translation:DBSETORDER (expN)

Related:INDEX, REINDEX, SET INDEX, USE, INDEXORD(), INDEXEXT(), INDEXKEY(),INDEXCHECK(), DBSETORDER(), FOUND(), oRdd:SetOrder()

CMD 408

SET OUTMODESyntax:

SET OUTMODE [TO] [<expN>]Purpose:

Designates how to print zero-bytes and unprintable characters < 32 on the screen.

Arguments:<expN> is the desired output mode:

0: print all "as is", chr(0) may terminate the string1: replace chr(0) by character specified in SET(_SET_ZEROBYTEOUT) which is

per default "?", print all other characters "as is"2: print characters < 32 as "^x", i.e. chr(0) -> ^@, chr(3) -> ^C3: same as 2, except chr(7), chr(10), chr(13)4: print characters < 32 as backslash-escaped octal value -> \nnn5: same as 4, but enclosed in curly brackets -> {\nnn}6: print characters < 32 as hexadecimal value -> 0xNN7: same as 6, but enclosed in curly brackets -> {0xNN}8: print characters < 32 as CHR(nn)9: same as 8, but enclosed in curly brackets -> {CHR(nn)}

The default setting is 1. This is also set when <expN> is not given.

Description:The standard screen output via OutStd(), OutErr() or the ?, ?? commands andQOUT(), QQOUT() functions cannot print all characters below CHR(32) to thescreen. With SET OUTMODE or SET(_SET_OUTMODE) you may decide how tohandle them. When the output is redirected to another device than console/screen,SET OUTMODE is ignored.

Example:str := "ab" + chr(0) + "cd" + chr(3) + "ef" + chr(7) + "gh"? Set(_SET_OUTMODE) // 1? Set(_SET_ZEROBYTEOUT) // "?"? str // "ab?cdefgh"SET OUTMODE 0 ; ? str // "ab" or "abcdefgh"SET OUTMODE 1 ; ? str // "ab?cdefgh"SET OUTMODE 2 ; ? str // "ab^@cd^Cef^Ggh"SET OUTMODE 3 ; ? str // "ab^@cd^Cefgh"SET OUTMODE 4 ; ? str // "ab\000cd\003ef\007gh"SET OUTMODE 5 ; ? str // "ab{\000}cd{\003}ef{\007}gh"SET OUTMODE 6 ; ? str // "ab0x00cd0x03ef0x07gh"SET OUTMODE 7 ; ? str // "ab{0x00}cd{0x03}ef{0x07}gh"SET OUTMODE 8 ; ? str // "abCHR(0)cdCHR(3)efCHR(7)gh"SET OUTMODE 9 ; ? str // "ab{CHR(0)}cd{CHR(3)}ef{CHR(7)}gh"SET OUTMODE TOwait

CMD 409



Translation:Set(_SET_OUTMODE, <expN> )

Related:?, ??, QOUT(), QQOUT(), OUTSTD(), OUTERR(), SET CONSOLE, SET DEVICE

CMD 410

SET PATH TOSyntax:

SET PATH TO [<pathList>|(<expC>)]Purpose:

Sets the path that FlagShip will search when attempting to open files.

Arguments:<pathList> is a list of paths that FlagShip is to search if a specified file is notlocated in the current directory. The list of paths is separated by commas orsemicolons. Other separators, like the usual UNIX colon (:) or space separator, canbe specified using FS_SET("pathdelim"). Each path gives the absolute or relativedirectory name separated by slashes or backslashes. "\" will be automaticallytranslated to the UNIX syntax "/". The line continuation of a SET PATH commandwith a semicolon (;) is not supported. For long path names, use a characterexpression enclosed in parentheses.

SET PATH TO with no argument releases the path list.

Description:When a file is to be accessed, and the path is not given as a part of the file name,FlagShip searches for existing files

•in the current UNIX directory,•in the path given by SET DEFAULT,•in all path names specified by SET PATH.

Note that low-level file functions and the SAVE TO, RESTORE FROM or RUNcommands do not respect either the DEFAULT or PATH settings. The RUNcommand considers the PATH= variable of the UNIX shell.

To create a new file outside the current directory, either an absolute path or a SETDEFAULT must be specified.

The path (and file) names are case-sensitive in UNIX. FlagShip offers differentlevels of automatic conversion of DOS names, executed during a file or directoryaccess:

•FS_SET("pathlower"|"pathupper",.T.) converts any given path to lower or uppercase,

•FS_SET("lower"|"upper",.T.) converts any given file name and extension to loweror upper case,

•FS_SET("translext","ntx","idx") translates the specified extension to another,•FS_SET("pathdelims",",;: ") to specify the path delimiters for the SET PATH

command,•x_FSDRIVE environment variable substitutes the used DOS drive selector "x"

(like C:, D: etc.) in the program path with a UNIX directory.

CMD 411

Example:LOCAL path1 := "C:\data1" // DOS SyntaxLOCAL path2 := "/usr/data2" // UNIX SyntaxLOCAL path3 := "../../data3" // relative pathFS_SET ("PathDelim", ",;: ") // set path delimitersFS_SET ("PathLower", .T.) // path translationFS_SET ("Lower", .T.) // data translation

IF EMPTY(GETE("C_FSDRIVE")) // check C: substitut.? "set C_FSDRIVE path first"QUIT

ENDIF

SET PATH TO .\data;/usr/dataIF .not. FILE("address1" + INDEXEXT())

SET PATH TO (path1 + ";" + path2 + ":" + path3)ENDIFIF .not. FILE("address.dbf")

SET PATH TO (GETENV("PATH")) // UNIX environmentENDUSE address INDEX address1

Classification:programming, file access

Translation:SET (_SET_PATH, "path")

Related:SET DEFAULT, CURDIR(), FS_SET(), (FSC)environment

CMD 412

SET PIXELSyntax:

SET PIXEL on|OFF|(<expL>)Purpose:

Set default pixel or row/col coordinates

Arguments:ON/OFF enables/disables the specification of coordinates in pixels or in col/rowvalues in GUI mode. Alternatively, the parenthesized <expL> may be used,whereby TRUE is the same as ON. The default setting is OFF.

Description:In GUI mode, all widgets (or controls in MS-Windows terminology) are pixel based.To enable the common Xbase (FlagShip, Clipper, FoxPro etc) compatibility,FlagShip internally recalculates the col/row coordinates to pixels according to theused font.

The calculation of one row is the line height (font specific) + line inter-spacing. Onecolumn is assumed the largest width of the characters "358AMX". You may changethis calculation by setting the global variable_aGlobSetting[GSET_G_C_COL_MAXCHAR ] := "358AMX"_aGlobSetting[GSET_G_N_ROW_SPACING ] := 2

correspondingly, see also system/initio.prg and include/set.fh

The most commands or functions using coordinates accept optional clausePIXEL|NOPIXEL or an logical/NIL argument which temporarily overrides the globalSET PIXEL declaration.

One pixel is a "dot on the screen", i.e. smallest single component of a digital image.The character size in pixel depends on the used font (see SET FONT andLNG.5.3.1 & 5.3.2) and can be determined by Row2pixel(), Col2pixel() andStrLen2pix(). For example, with SET FONT "Arial",12 the width of letter "X" is 11pixel, but "i" occupy only 4 pixel; the row height is here 21 pixels, and columnstepping is 13 pixels = width of "M" (data depends on the screen resolution, here forWUXGA desktop monitor with resolution 1920x1200 pixel).

The SET PIXEL apply for GUI mode only and is ignored in Terminal and Basic i/o,which both assumes 1 pixel == 1 column or row.

Another alternative to specify coordinate units in mm, cm and inch is by SET UNITor SET COORD command.


Related:Set(_SET_PIXEL), SET FONT, Col2pixel(), Row2pixel(), Pixel2col(), Pixel2row(),StrLen2col(), StrLen2pix(), SET UNIT

CMD 413

SET PRINTERSyntax 1:

SET PRINTER TO [<file>|<device>|(<expC1>)[ADDITIVE] ][PIPE <expC2>]

Syntax 2:SET PRINTER on|OFF|(<expL>) [NEW]

Syntax 3:SET PRINTER GUI on|OFF|(<expL>)

Purpose:Echoes console output (e.g. of the ?, ?? commands) to a printer file or device.

Arguments:TO <file> is the name of an ASCII file, path and an extension included, to which theoutput will be redirected. If the file extension is not specified, .prn is assumed.

ADDITIVE causes the specified printer file to be appended to, instead of beingoverwritten. When omitted, the specified <file> is truncated. The <file> is created inthe SET DEFAULT directory when given, or in the current one otherwise.

TO <device> is any valid UNIX character device, like /dev/tty05, /dev/lp0 etc. If the<device> name starts with "/dev/", no default .prn extension is added. In MS-Windows, you may specify LPT1, LPT2, LPT3...LPT9, PRN, COM1...COM9 asdirect printing device, which of course must be available on your system. In Linux,device names /dev/lp0 and /dev/lp1 etc. corresponds to LPT1 and LPT2 etc in DOS;/dev/ttyS0 and /dev/ttyS1 etc. corresponds to COM1 and COM2 in DOS.

TO PIPE <expC2> streams the PRINTER output to be an input of the UNIXexecutable given in <expC2>, similar to the shell invocation e.g. a.out | b.out. The<expC2> expression may also contain more complex piping, like "tee out1.txt |b.out". Note: the executable given in <expC2> remains active as a child processuntil SET PRINTER TO with no arguments is executed. Thereafter, the childprocess has "zombie" status, which means the process slot remains occupied untilthe current executable is finished. Supported in Linux/Unix only.

When SET PRINTER TO is specified without an argument, the default spooler file isselected ADDITIVE.

ON/OFF activates or deactivates the output to the specified file, device, or thedefault printer file. Alternatively, the parenthesized <expL> may be used, wherebylogical TRUE is the same as ON.

NEW causes the current printer file contents to be deleted, instead of appended to.

GUI ON/OFF activates or deactivates GUI alike output. SET PRINT GUI isequivalent to SET GUIPRINTER command and PrintGui(.T./.F.) function, see moredetails there.

CMD 414

Description:Because of the usual multiuser printer sharing on UNIX, FlagShip redirects bydefault the printer output to a "spooler" file, see LNG.3.4 and LNG.5.1.6. Whenstarting a program, the default printer file is opened in the current (or by theenvironment variable FSOUTPUT assigned) directory; the SET DEFAULT pathdoes not affect the default spooler file.

The name of the default spooler file is <main_procedure>.<process_id> and can beretrieved by the FS_SET ("printfile") function. The data from a printer file can beprinted either from the application, or any time offline using the default UNIXspooler. To spool the printer data directly from the application,

•issue SET PRINTER OFF or SET PRINTER TO•retrieve the file name <printfile> := FS_SET("print")•activate the output using e.g. RUN "lp -d... <printfile>" or RUN "cp <printfile>

/dev/..." etc.,•a. delete the file using ERASE <printfile>, if the subsequent printer output is not

required,• issue SET PRINTER ON for the subsequent output.•b. issue SET PRINTER ON NEW for the subsequent output, which deletes the

previous output.

In special cases, if a spooled output is not required, even direct device (such asprinter, other terminal etc.) output is supported by FlagShip using SET PRINTERTO <device>.

The SET PRINTER ON command is equivalent to the ...TO PRINTER clause ofconsole commands like LIST, REPORT etc. To suppress the console output, SETCONSOLE OFF may be used. To redirect the @..SAY command to the printer fileor device, issue a SET DEVICE TO PRINTER.

Printer output from GUI based application can be done w/o any programming ac-tivities nearly automatically via the "File->Print ..." menu item, see additional de-scription in LNG.5.1.6 and example in the <FlagShip_dir>/examples/printer.prg file

Tuning:You may tune the printer driver by FS_SET("prset") which may be advantageouswhen using proportional character set etc. Note that some printers requires CR +LF (= carriage return + line feed) for line break instead of LF (line feed) sent bydefault. In such a case add the statement

FS_SET("prset", { chr(13)+chr(10) } )before your printer output statements.

CMD 415

Example 1:SET PRINTER ONSET CONSOLE OFF? "This is a printer output only"SET CONSOLE ON? "This goes to both the printer and the screen"SET PRINTER OFF

USE stockREPORT FORM invent TO PRINT NOCONSOLERUN ("lp -dlaser -m -s " + FS_SET("print"))

Example 2:Create printout spool file, then send it to printer

SET PRINTER ONSET CONSOLE OFFSET DEVICE TO PRINT

? "Hallo world"for ii := 3 to 20

@ ii,10 say "Line " + ltrim(ii)nexteject

SET DEVICE TO SCREENSET CONSOLE ONSET PRINTER OFF

prFile := fs_set("printfile")? "Printing Spool-File", prFile// _aGlobSetting[GSET_L_RUNDISPLAY] := .T. // optional#ifdef FS_WIN32RUN("COPY " + prFile + " PRN") // Windows default printer

#elseRUN ("cp " + prFile + " /dev/lp0") // Linux def printer

#endifwait

Example 3:Print directly to specified device

#ifdef FS_WIN32SET PRINTER TO LPT1 // or COM1 or PRN etc.

#elseSET PRINTER TO /dev/lp0 // or /dev/lp1 etc.

#endifSET PRINTER ONSET CONSOLE OFFSET DEVICE TO PRINT... Printer control codes and output via ?, ??, @...SET DEVICE TO SCREENSET CONSOLE ONSET PRINTER OFFSET PRINTER TO

CMD 416

Example 4:Send the printer output simultaneously to the file "xyz.prg" and the device "tty5c":

SET PRINTER TO PIPE "tee xyz.txt > /dev/tty5c"SET PRINTER ON? "output to text file and other device"SET PRINTER (.F.)? "output to the screen only"SET PRINTER ON? "output continued to text file and other device"SET PRINTER TO

Example 5:In GUI mode, you may choose the printer driver in a common dialog and havedifferent formatting methods. See/run the complete example in <FlagShip_dir>/examples/printer.prg

Example 6:Printer output via Ethernet: when you want to redirect the local printout (at the Unixserver) to a remote printer which has an Ethernet printserver module installed, yousimply set lp (or lpr) to the printer IP address. Printer output via Terminal emulator:you may also print remotely via terminal emulator (eg. from MS-Windows 9x/NT)when the emulator support transparent printer redirection eg via VT escapesequences. Here an example, tested with the CRT 2.3 terminal emulator (http://www.vandyke.com) and PuTTY (http://www.chiark.greenend.org.uk/~sgtatham/putty/) from local MS-Windows NT4/2000/2008/XP/Vista and a FlagShip applicationrunning on remote Unix, Linux or Windows server.

Compile: FlagShip testprint.prg -io=t -o testprintExecute via terminal emulator: ./testprint or newfsterm ./testprint

** file testprint.prglocal i, cSpoolDef, cSpoolTmp, nRow

/* 1. create some printer output into default spool file, you* of course may use any ?, ??, @..SAY etc output instead*/printTestData() // print some test data to spoolercSpoolDef := FS_SET("print") // get default spool file name

/* 2. print the plain spool file to remote printer thru* terminal emulator, using VT100 escape sequences* Note: this may fail with some Terminal Emulators*/? "printing file", cSpoolDef, "to remote printer ..."Send2print(cSpoolDef)// DELETE FILE (cSpoolDef)

/* 3. switch back to console output*/wait

CMD 417

nRow := ROW() +1for i := nRow to nRow +5

? "displaying line #", LTRIM(i), "on terminal"nextwait "done, press any key..."

/* 4. alternative print to remote printer via shell.* The output file already contains the re-rooting sequences.* Note: this usually work with any terminal emulator which* supports printer redirection via DEC VT escape sequences*/?cSpoolTmp := TempFileName(,"my_") + ".prn"? "creating another printer output file", cSpoolTmpprintTestData(.T., cSpoolTmp) // create with prefix and postfix

? "copying printer output to remote printer ..."#ifdef FS_WIN32RUN ("type " + cSpoolTmp) // print in VFS for MS-Windows

#elseRUN ("cat " + cSpoolTmp) // print in VFS for Unix/Linux

#endif// DELETE FILE (cSpoolTmp)

wait "done, press any key..."quit

// defines used below#define REROUTE_ON chr(27) + "[5i" /* VT100 sequence */#define REROUTE_OFF chr(27) + "[4i" /* VT100 sequence */#define CRLF chr(13) + chr(10)#define MY_STDOUT 2

*********************************************** print some test data into spool file* lAddReroute: if .T., add re-rooting prefix and postfix* cFile: if not empty, use this out file instd.standard*FUNCTION PrintTestData(lAddReroute, cFile)local iiif valtype(lAddReroute) != "L"

lAddReroute := .F.endif

if !empty(cFile) // specified spooler fileset printer to (cFile) // otherwise default spool file

endifset device to print // set output to printerset printer onset console off

if lAddReroute // add esc sequence to?? REROUTE_ON // Start re-routing to remote printer

endif

CMD 418

// send some data to printer@ 2,0 say "line 2, col 1"@ 5,5 say "line 5, col 5"@ 7,25 say "line 7, col 25"for ii := 1 to 5

? ; ?? "printing line#", ltrim(prow())next?if lAddReroute // add esc sequence to

?? REROUTE_OFF // end re-routing to remote printerendif

if !empty(cFile) // close spooler fileset printer to

endifset console on // set output back to consoleset printer offset device to screenreturn NIL

*********************************************** Sends the given file to remote printer* adding redirection prefix/postfix esc-sequences*FUNCTION Send2print(cFile)local fh, str, iErr := 0, lAbort := .F.

fh := fopen(cFile,0)if fh <= MY_STDOUT .or. ferror() != 0

wait "cannot open printer file '" + cFile + "' ..."else

fwrite(MY_STDOUT, REROUTE_ON) // start redirectionwhile iErr == 0

str := freadtxt(fh)iErr := ferror()fwrite(MY_STDOUT, str + CRLF)if inkey() == K_ESC

lAbort := .T.exit

endifenddofclose(fh)fwrite(MY_STDOUT, CRLF)fwrite(MY_STDOUT, REROUTE_OFF) // end redirectionif lAbort

? "Aborted by user..."endif

endifreturn NIL

Classification:programming (sequential printer/file output and system file access is used dueprinting, i.e. executing the output command/function)

CMD 419

Compatibility:This command is compatible to the xBASE dialects on DOS, but only FlagShipsupports the printer spooling by default. If a DOS device name (like LPT2, PRN,COM3) is used in 1:1 ported programs, make a link to the UNIX device beforeinvoking the executable, e.g.:

$ ln LPT2.prn /dev/lp1

The clauses PIPE, NEW and ADDITIVE are available in FS only.

Translation:SET ( _SET_PRINTER, .T.|.F.)SET ( _SET_PRINTFILE, "file", .add.)

Related:EJECT, SET CONSOLE, SET DEVICE, SET ALTERNATE, SET EXTRA,PrintGui(), FS_SET(), (FSC) environment, UNIX: man lp, ls -l /dev

CMD 420

SET PROCEDURE TOSyntax:

SET PROCEDURE TO [<file>]Purpose:

Informs the compiler that all UDFs and procedures in the specified <file> are to becompiled together with the current source file.

Arguments:<file> is the name of the source file. If no extension is specified, the default is .prg.The <file> can optionally include a path designator. SET PROCEDURE TO withoutan argument has no practical meaning in FlagShip and is simply ignored.

Description:The SET PROCEDURE statement directs the FlagShip compiler to compile anadditional source <file> into C and object file. A file can contain any number ofprocedures and UDFs. The same occurs, if a procedure call DO... is encounteredduring the compiling, the name is yet unknown and the same source file exists. Ifthe -m compiler switch is specified, the SET PROCEDURE statement is ignored.

In FlagShip, SET PROCEDURE can be omitted giving the name of the procedure<file> in the command compiler line; see section FSC.

Example:*** file test.prgSET PROCEDURE TO adr_proc && needed for adr_maskDO adr_initDO adr_maskQUIT*** eof test.prg

*** file adr_init.prg && called directly.*** PROCEDURE adr_init && PROC name = file nameRETURN*** eof adr_init.prg

*** file adr_proc.prg && not called directly,PROCEDURE adr_mask && therefore SET PROCEDURERETURN && or: FlagShip test.prg\*** eof adr_proc.prg && adr_proc.prg


Translation:_PROCREQ_ ("file")

Related:DO, FUNCTION, PROCEDURE, SET FORMAT, #include

CMD 421

SET RELATIONSyntax:

SET RELATION [ADDITIVE] [MULTIPLE]TO [<parentKey1>|<recno> INTO <childAlias1>]

[, [TO] <parentKeyN>|<recno>INTO <childAliasN>]

Purpose:Relates two or more working areas using a key expression or record number.

Arguments:<parentKey> is an expression used to perform a SEEK in the child area each timethe record pointer moves in the parent working area. This is usually a field of theparent area. The child area must have an index in use, with key expressioncorresponding to <parentKey> value.

<recno> is a record number or an numeric expression (typically the RECNO() func-tion) used to perform a GOTO to the record number in the child working areamatching the record number of the parent area. For this type of relation, the childarea need not have an index in use or the indices are disabled by SET ORDER TO0

<childAlias> identifies the child working area (or file name). The child databasemay also be opened by different RDD driver, than the current (parent) database.

SET RELATION TO without arguments removes all relations from the currentworking area.

Options:ADDITIVE adds the specified child relations to existing relations already set in thecurrent working area. If this clause is not specified, existing relations in the currentworking area are released before the new child relations are set. You maydetermine the number of relations for each parent by DbRelCount().

MULTIPLE specifies that the child database is processed as 1:n relation, otherwiseit is 1:1 relation. Only the first relation in each parent is considered as 1:n by SKIP.You may set or clear the 1:n relation also later by DbRelMultiple().

Description:SET RELATION links the active database (parent) with other opened databases(children) identified by INTO <alias>, see LNG.4.7. Each parent working area canbe linked to unlimited number of child working areas.

A relation causes the record pointer in the child area to move in accordance withthe movement of the record pointer in the parent area. If a match is not found, thechild area record pointer is positioned to the end-of-file (LASTREC() +1), EOF()returns .T. and FOUND() returns .F.

CMD 422

The typical sequence is SELECT <parent>; SET RELATION TO <parentKey> INTO<childAlias>, where the <childAlias> is indexed on a key matching the <parentKey>,e.g.

USE mydb NEW ALIAS master // has field IdKey* INDEX ON anything TO master // optionalUSE subdb NEW ALIAS child // has field IdChildINDEX ON IdMaster TO subdb // and field IdMaster* USE subsub NEW ALIAS childOfChild // has field IdChild* INDEX ON IdChild TO subsubdb...SELECT masterSET RELATION TO IdKey INTO child // opt: MULTIPLE* SELECT child* SET RELATION TO IdChild INTO childOfChild // opt: MULTIPLESELECT master// LIST IdKey, child->IdChild, child->IdMaster, child->Data, ;// childOfChild->IdChild, childOfChild->data// other processing ...SELECT masterSET RELATION TO // clear relation* SELECT child* SET RELATION TO // clear relation

If the MULTIPLE clause is specified, SKIP process the child in 1:n manner insteadof 1:1. This means, if the child contains more than one corresponding key for thisrelation, the child is skipped instead of parent. For 1:n:n:..:n relations, the last childis skipped first (as long as in the relation), then the last-1 child with all it childs inrelation, and so forth. See also LNG.4.7 and example below.

Although SET RELATION obeys SET FILTER and SET DELETED in the childworking areas, it does not obey SET SOFTSEEK, thus always behaving as if SETSOFTSEEK were off. In most cases, conditional index (INDEX ON..FOR..) is alsofaster then SET FILTER.

Although the SET RELATION is a comfortable database link, it may slow theexecution significantly; especially if the movement in the child area(s) is not neededfor each movement (SEEK, SKIP, GOTO, REPLACE...FOR etc.) in the parent area.In such a case, use a "soft link", SEEKing the child record explicitly when requiredonly. For 1:N:N relations, you will need (in worst case) to skip (records-in-parent *records-in-child1 * records-in-child2 ) -times to reach eof().

RELATing a database directly or indirectly to itself will usually result withunpredictable results, possibly endless loops!

FlagShip tries to keep the relation integrity by repositioning the dependentdatabase, e.g. on movements, SELECT, by reaching break in the GUI debugger.You may force the integrity by issuing SKIP 0 on the parent database. A manualSEEK is hence suggested when you will manipulate the record pointer of therelated database.

CMD 423

Example:SELECT 2 // child relat.USE employeeINDEX ON emplidno TO empl_idSELECT 1 // parent relat.USE families? FIELD(3) // ID_NUMBSET RELATION TO families->id_numb INTO employeeLIST Name, Employee->Name, Employee->Lastname

// The same output using a manual "soft" 1:1 relation:

USE employee NEW INDEX empl_id // childUSE families NEW // parentDO WHILE !EOF()

employee->(DBSEEK (families->id_numb)) // SEEK in child? Name, Employee->Name, Employee->LastnameSKIP

ENDDO

Example: the complete code is available in .../examples/relat_one2n.prgselect company// index on ID to company_id // not requiredselect departmindex on IDcomp to depart_id // requiredselect namesindex on IDdepart to names_id // required/** set 1:n:n relations*/select companyset relation to ID into departm MULTI // company -> departm 1:nselect departmset relation to IDdepart into names MULTI // departm -> names 1:nselect companyset filter to company->zip >= 2000 .and. company->zip < 3000// better: INDEX ON zip FOR zip >= 2000 .and. zip < 3000 TO zip2go topwhile !eof()

? "id="+str(id,4),"|"+company+"|"+departm->deptm+"|"+ ;names->name+"|"+names->first+"|"+str(names->IDpers,5)

SKIPenddoselect departmset relation to // clear relation(s) from departm to child(s)select companyset relation to // clear relation(s) from company to child(s)set filter to // clear filterwait

// the same 1:n:n output without relations:

// use ... index ... from aboveselect companyset filter to company->zip >= 2000 .and. company->zip < 3000

CMD 424

go topwhile !eof() // on company

SELECT departmSEEK company->IDif eof()

? "id=" + str(company->id,4)+ "|" + company->company + ;"|no departments"

endifwhile !eof() .and. IDcomp == company->ID // on departm

SELECT namesSEEK departm->IDdepartif eof()

? "id=" + str(company->id,4)+ "|" + company->company + ;"|" + departm->deptm + "|no names"

endifwhile !eof() .and. IDdepart == departm->IDdepart // on names

? "id=" + str(company->id,4)+ "|" + company->company + ;"|" + departm->deptm + "|" + names->name + "|" + ;names->first + "|pers.id=" + str(names->IDpers,5)

SKIP // next name for the same IDdepartenddo // while... on namesSELECT departmSKIP // next departm for the same IDcomp

enddo // while... on departmSELECT companySKIP // next company

enddo // while.. on companywait


Compatibility:The ADDITIVE clause is new in FS4. For FS4 and before, the number of child areaswas restricted to 8, VFS5 and later supports any number of relations. 1:N relationsare available in VFS7 and later.

Translation:IF ( ! .add. ) ; DbClearRel() ; ENDIFDbSetRelation ( "alias1", {key1}, "key1" [, .multi.] )[ DbSetRelation( "alias2", {key2}, "key2" [, .multi.] ) ...]

Related:INDEX, SET INDEX, SET ORDER, UPDATE, USE, SEEK, SKIP, GOTO,REPLACE, Recno(), DbSetRelation(), DbRelation(), DbClearRel(), DbRselect(),DbRelCount(), DbRelMultiple(), oRdd:SetRelation(), oRdd:ClearRelation(),oRdd:Info()

CMD 425

SET ROWADAPTSyntax:

SET ROWADAPT on|OFF|(<expL>)Purpose:

Enables or disables the automatic ROW() adaption when the screen output includesHTML tags or different FONTs.

Arguments:ON/OFF enables/disables the automatic ROW() adaption. Alternatively, theparenthesized <expL> may be used, whereby TRUE is the same as ON. Thedefault setting is OFF.

Description:When performing screen output in GUI mode using HTML tags or with differentFONTs, the COL() position is calculated automatically, but the ROW() settingconsiders the and HTML tags or the larger/smaller font only when SETROWADAPT is ON. Otherwise the ROW() remain unchanged, or is increased byone line height (using the default font size) when the ? command or QOUT() wasinvoked.

When SET ROWADAPT is OFF, you may force the ROW() adaption manually byinvoking RowAdapt() just after the output.

The final cursor position may be affected also by the current status of SETROWALIGN, see examples there.

The SET ROWADAPT and RowAdapt() adaption takes effect only for sequentialscreen output (i.e. for ?, ??, @...SAY commands and Qout(), Qqout(), DevOut(),DevOutPict() functions) in GUI mode.

Classification:programming, screen output in GUI mode


Translation:Set( _SET_ROWADAPT [, <expL>] )

Related:?, ??, @..SAY, SET ROWALIGN, SET HTMLTEXT, SET FONT, Qout(), Qqout(),RowAdapt()

CMD 426

SET ROWALIGNSyntax:

SET ROWALIGN [TO] BASELINE|DEFAULTSET ROWALIGN TOSET ROWALIGN (<expL>)

Purpose:Enables or disables the automatic ROW() alignment on baseline of the standardfont.

Arguments:BASELINE enables the automatic ROW() alignment.

DEFAULT disables the automatic ROW() alignment.

<expL> is an alternative syntax, whereby (.T.) is same as SET ROWALIGN TOBASELINE and (.F.) is same as SET ROWALIGN TO DEFAULT.

SET ROWALIGN TO is equivalent to SET ROWALIGN TO DEFAULT

Description:The default x/y alignment in GUI mode is on the top left character frame (markedwith + in the picture below), to allow start the output at 0,0 coordinates. Thecharacters "O-umlaut","h","p" are displayed as

--+------------------------------ <- top character frame| * * | | || ### | # | || # # | # | || # # | ### | #### || # # | # # | # # || ### -| # # -| #### -| <- base line| | | # || | | # |----------------------------- <- bottom character frame

--------------------------------- <- line spacing

where the size of (bottom - top) is returned by oFont:Height() or in pixel byoFont:SizePixel(); the line spacing is user definable by global variable_aGlobSetting[GSET_G_N_ROW_SPACING].

When you change the FONT size, the start position remain unchanged, i.e. largerfont has it base line located at higher Y position (in view of top/down coordinates).Sometimes you may wish to align characters on it base line, e.g. when using theFONT option to display different fonts (from the standard) in the same output linesimilarly to word processor output, e.g.

CMD 427

oFont2 := Font{"Arial",50} ; oFont2:Bold := .T.// SetPos(4,10)?? "Start "?? "Big" FONT oFont2 GUICOLOR "R+"?? " Continue" GUICOLOR "B+"

Depending on SET ROWALIGN and SET ROWADAPT setting, you will get:

with SET ROWALIGN TO DEFAULT | with SET ROWALIGN TO BASELINEand SET ROWADAPT OFF | and SET ROWADAPT OFF

|Start BBBB Continue | BBBB

B B * | B B *BBBBB i ggg | BBBBB i gggB B i g g | B B i g gBBBB i ggg | Start BBBB i ggg Continue

g | ggg | gg

with SET ROWALIGN TO DEFAULT | with SET ROWALIGN TO BASELINEand SET ROWADAPT ON | and SET ROWADAPT ON

|Start BBBB | BBBB

B B * | B B *BBBBB i ggg | BBBBB i gggB B i g g | B B i g gBBBB i ggg | Start BBBB i ggg

g | ggg | gg

Continue | Continue

Note that the base line alignment for larger font size than current default will displaydesired results only when the current Row() is > 0, since you cannot print onnegative coordinates :-)

Instead of using SET ROWALIGN TO BASELINE, you of course may control thealignment and coordinates manually by SetPos(), e.g.

oFont2 := Font{"Helvetica",60} ; oFont2:Bold := .T.?? "Start "ySave := Row(.T.)yNew := max(0, ySave - oFont2:SizePixel() + ;

m->oApplic:Font:SizePixel() )SetPos(yNew, Col(.T.), .T.) ; ?? "Big" FONT oFont2SetPos(ySave, Col(.T.), .T.) ; ?? " Continue"

The SET ROWALIGN alignment takes effect only for sequential screen output (i.e.for ?, ??, @...SAY commands and Qout(), Qqout(), DevOut(), DevOutPict()functions) in GUI mode.

CMD 428

Classification:programming, screen output in GUI mode


Translation:Set( _SET_ROWALIGN_BASE [, <expL>] )

Related:?, ??, @..SAY, SET ROWADAPT, SET HTMLTEXT, SET FONT, Qout(), Qqout(),RowAdapt()

CMD 429

SET SCRCOMPRESSSyntax:

SET SCRCOMPRESS on|OFF|(<expL>)Purpose:

Enable/disable compressing screen image for SaveScreen() and RestScreen() inGUI mode.

Arguments:ON/OFF enables/disables the compressing of screen images in GUI mode.Alternatively, the parenthesized <expL> may be used, whereby TRUE is the sameas ON. The default setting is OFF.

Description:In GUI, the structure of the screen variable <retS> is incompatible to <retS> fromTerminal i/o mode. In GUI, it is compressed or uncompressed bitmap object asopposite to Curses "window" structure in Terminal i/o.

In GUI, you may decide if the bitmap is stored "as is" (default) or in compressedformat which requires significantly less memory. On the other hand, a compressedformat may cause some side-effects depending on the used graphic card and theselected color depth. If you have many Save/RestScreen() in the application, try toset SET SCRCOMPRESS ON (default is OFF) and watch if not side effects (likeslight color shifting) occurs after RestScreen(), otherwise let the compressiondisabled by SET SCRCOMPRESS OFF.

The SET SCRCOMPRESS setting apply for GUI mode only and is ignored inTerminal and Basic i/o.



Related:Set(_SET_SCRCOMPRESS), SaveScreen(), RestScreen()

CMD 430

SET SCOREBOARDSyntax:

SET SCOREBOARD ON|off|(<expL>)Purpose:

Defines whether the messages issued by READ and MEMOEDIT() are displayed ornot.

Arguments:ON/OFF enables/disables the display of messages on line zero. Alternatively, theparenthesized <expL> may be used, whereby TRUE is the same as ON.

Description:When SCOREBOARD is ON, the messages are displayed at the uppermost line ofthe display. The messages are: the indication of the INSERT mode, the RANGEerror message, and an abort query message in MEMOEDIT().

In FlagShip, the message text can be user-specified, for example for foreignlanguages, using FS_SET ("loadlang") and FS_SET("setlang"). The querymessages for MEMOEDIT() are re-definable in the file <FlagShip_dir>/system/scor_mem.prg.

Example:SET SCOREBOARD OFFSET FORMAT TO authorsUSE authorsREADSET FORMAT TOUSESET SCOREBOARD ON


Compatibility:The user definable messages are available in FlagShip only.

Translation:SET ( _SET_SCOREBOARD, .T.|.F.)

Related:@...GET, READ, MEMOEDIT(), FS_SET(), SET()

CMD 431

SET SOFTSEEKSyntax:

SET SOFTSEEK on|OFF|(<expL>)Purpose:

Defines whether SEEK and FIND will have softer criteria in searching or whetherthey will be strict.

Arguments:ON/OFF enables/disables soft searching. Alternatively, the parenthesized <expL>may be used, whereby TRUE is the same as ON.

Description:When SOFTSEEK is ON, and a matching index key is not found while SEEKing, thefirst higher value key is reported as found and the record pointer is located on it. IfSOFTSEEK is OFF, only the exact match will be found.

SEEK with SOFTSEEK ON FOUND() EOF()Index key found .T. .F.Next index key found .F. .F.Next index key not available .F. .T.

SEEK with SOFTSEEK OFF FOUND() EOF()Index key found .T. .F.Index key not found .F. .T.

The current state of SET FILTER and SET DELETED is obeyed in SEEK,regardless of the SOFTSEEK setting.

Note: SEEKing the child record of a SET RELATION specified database ignores thecurrent SET SOFTSEEK switch.

Example:LOCAL searchnameSET SOFTSEEK ONUSE address INDEX adrnameDO WHILE .T.

ACCEPT "enter name to search (or <┘) " TO searchnameIF EMPTY(searchname)

EXITENDIFSEEK searchnameDO CASECASE FOUND()

? "Found: ", name, firstCASE .not. EOF()

? "Next name found: ", name, firstOTHERWISE

? "The same or next name not available"ENDCASE

ENDDO

CMD 432


Translation:SET ( _SET_SOFTSEEK, .T.|.F.)

Related:SEEK, FIND, SET INDEX, SET ORDER, SET RELATION, EOF(), FOUND(), SET(),oRdd:Seek()

CMD 433

SET SOURCESyntax:

SET SOURCE ASCII | PC8 | OEMSET SOURCE ISO | ANSI

Purpose:Enable support of national character sets, i.e. source strings containing specialcharacters coded in either in PC8/ASCII or in ISO/Ansi. For a fullinternationalization discussion refer to section LNG.5.4

Description:To support national character sets coded in ASCII (e.g. by using DOS sourceeditor) in GUI i/o mode (which is usually ISO oriented) and for printer output, anautomatic ASCII -> ISO conversion during the output is available via SET SOURCEASCII. This is very similar to converting the string output via Oem2Ansi() likeQout(Oem2Ansi("M"+chr(129)+"nchen")) // u-umlaut in PC-8

Note: SET SOURCE ASCII is issued in #include "fspreset.fh" to enable an easy portof DOS applications.

To support national character sets coded in ISO/Ansi in GUI mode, you may informthe system that no automatic ASCII -> ISO conversion during the output is requiredusing SET SOURCE ISO. This is very similar to the string output Qout("M"+chr(252)+"nchen") // u-umlaut in ISO-8859-1

In Terminal i/o mode, the input and output is assumed to be in ASCII, i.e. u-umlautas chr(129), same as in DOS and Clipper. If you are using an ISO or Windowssource-code editor (which will code chr(252) for u-umlaut), you may preferably usethe -iso compiler switch, which will translate ISO strings to ASCII.

The #include "fspreset.fh" statement (see LNG.9.5) sets SET SOURCE ASCII andSET GUITRANSL TEXT ON to enable backward compatibility to DOS and terminali/o oriented source.

SET SOURCE ISO is not equivalent to set(_SET_SOURCEASCII). The SETSOURCE command sets also additional flags for your convenience, whilstSet(_SET_SOURCEASCII) only reports if SET SOURCE was invoked. See also the#command SET SOURCE in std.fh for details.

SET SOURCE ASCII (or PC8 or OEM) will setSet(_SET_SOURCEASCII, .T.) // source is in ASCII charsetSet(_SET_GUIASCII, .T.) // translate screen outputSet(_SET_ANSI, .F.) // read/write database 1:1Set(_SET_CHARSET, _SET_CHARSET_PC8) // translate Inkey()Set(_SET_PRINTASCII, .F.) // printer output 1:1

SET SOURCE ANSI (or ISO) will setSet(_SET_SOURCEASCII, .F.) // source is in ISO charsetSet(_SET_GUIASCII, .F.) // GUI screen output 1:1Set(_SET_ANSI, .T.) // translate read/write databaseSet(_SET_CHARSET, _SET_CHARSET_ISO) // Inkey() is 1:1Set(_SET_PRINTASCII, .T.) // translate printer output

CMD 434

Note: The automatic support of IBM-PC8 semi-graphic characters in GUI mode isenabled when SET GUITRANSL TEXT ON is set. Without changing the translationtables heavily - see fs_set("ansi2oem"), the semi-graphic output work properly onlywith SET SOURCE ASCII, since chr(176..223) equivalence is not available in theISO/Ansi character set. In Terminal i/o mode, the IBM-PC8 semi-graphic characterssupport is enabled per default.

Note other GUI defaults, modified by SET GUITRANSL command:Set(_SET_GUIDRAWTEXT) = .F. // don't draw PC-8 charsetSet(_SET_GUIDRAWBOX) = .F. // don't draw PC-8 boxesSet(_SET_GUIDRAWLINES) = .F. // don't draw PC-8 lines

Classification:programming, screen and printer output

Example:see <FlagShip_dir>/examples/setsource.prg and <FlagShip_dir>/examples/printer.prg

Example:? "--------- Defaults"? "SET GUITRANSL ASCII=" + if(set(_SET_GUIASCII),"ON","OFF"), ;", SET KEYTRANSL=" + if(set(_SET_CHARSET) == _SET_CHARSET_PC8, ;"ASCII", "ISO"), ", Printer ASCII translation=" + ;if(set(_SET_SOURCEASCII), "ON", "OFF")

?? "This paragraph is coded in GUI/Windows editor, where u-umlaut"? "is chr(252), e.g. in München or M" + chr(252) + "nchen"? "press u-umlaut key :"key := inkey(0)?? " key =", ltrim(key),"=", chr(key) // key = 252 in ISO-8859-1

?SET SOURCE ASCII? "--------- SET SOURCE ASCII"? "SET GUITRANSL ASCII=" + if(set(_SET_GUIASCII),"ON","OFF"), ;", SET KEYTRANSL=" + if(set(_SET_CHARSET) == _SET_CHARSET_PC8, ;"ASCII", "ISO"), ", Printer ASCII translation=" + ;

if(set(_SET_SOURCEASCII), "ON", "OFF")?? "This paragraph is coded in DOS/ASCII editor, where u-umlaut"? "is chr(129), e.g. in M• nchen or M" + chr(129) + "nchen"? "press u-umlaut key :"key := inkey(0)?? " key =", ltrim(key),"=", chr(key) // key = 129?

SET SOURCE ISO? "--------- SET SOURCE ISO"? "SET GUITRANSL ASCII=" + if(set(_SET_GUIASCII),"ON","OFF"), ;", SET KEYTRANSL=" + if(set(_SET_CHARSET) == _SET_CHARSET_PC8, ;"ASCII", "ISO"), ", Printer ASCII translation=" + ;if(set(_SET_SOURCEASCII), "ON", "OFF")

CMD 435

? "press u-umlaut key :"key := inkey(0)?? " key =", ltrim(key),"=", chr(key) // key = 252wait "done ..."

Translation:SET SOURCE ASCII or PC8 or OEM

== Set(_SET_SOURCEASCII, .T.) + Set(_SET_GUIASCII, .T.) +Set( _SET_CHARSET, _SET_CHARSET_PC8)

SET SOURCE ISO or ANSI== Set(_SET_SOURCEASCII, .F.) + Set(_SET_GUIASCII, .F.) +

Set( _SET_CHARSET, _SET_CHARSET_ISO)


Related:SET GUITRANSL, SET ANSI, Set(_SET_GUIDRAWTEXT), Set(_SET_GUIDRAW-BOX), Set(_SET_GUIDRAWLINE), Set(_SET_GUITASCII)

CMD 436

SET TYPEAHEAD TOSyntax:

SET TYPEAHEAD TO <expN>Purpose:

Sets the size of the keyboard buffer.

Arguments:<expN> is the number of characters that the keyboard buffer can hold. It is aninteger in the range from zero up to 2 GB. If not specified, or if a negative value isspecified, the buffer is set to default of 10000 bytes.

Description:FlagShip stores user key stokes in an internal type-ahead buffer, which enables topre-enter input; see more in chapter LNG.5.2.

If the keyboard buffer's length is set to zero, keyboard polling is suspended andNEXTKEY() will always return zero. The LASTKEY() values are not affected by SETTYPEAHEAD.

The SET TYPEAHEAD buffer size does not affect the number of characters thatcan be pushed in by a program using the KEYBOARD command.

If you wish to copy-and-paste large text (e.g. to MemoEdit), you may need toincrease the TYPEAHEAD buffer accordingly. The default size is sufficient for ca. 2pages of fully printed paper sheets.

Example:? "working, please do not disturb..."SET TYPEAHEAD TO 0USE accountsCOUNT FOR turnover = 0 TO zeroSET TYPEAHEAD TO? zero, "customers with no turnover"


Compatibility:On function keys F2 to F48, 2 bytes for each keystroke are needed. In DOSdialects, the buffer length is limited to 4KB.

Translation:SET ( _SET_TYPEAHEAD, expN)

Related:ACCEPT, INPUT, KEYBOARD, READ, SET KEY, INKEY(), LASTKEY(),NEXTKEY(), SET()

CMD 437

SET UNITSyntax:

SET UNIT [TO]SET UNIT [TO] ROWCOL | PIXEL | MM | CM | INCH |

( <expN> )Syntax:

SET COORDINATE [UNIT] [TO]SET COORDINATE [UNIT] [TO] PIXEL | MM | CM | INCH |

( <expN> )Purpose:

Sets the unit for subsequently given screen (and printer with active PrintGui()output) coordinates. Applicable in GUI mode only.

Arguments:none same as ROWCOLROWCOL all subsequent coordinates are in common rows and columns.PIXEL all subsequent coordinates are in pixelsMM all subsequent coordinates are millimeterCM all subsequent coordinates are centimeter (ea 10 mm)INCH all subsequent coordinates are in inch (ea 25.4 mm)<expN> parenthesized numeric value, e.g. UNIT_ROWCOL, UNIT_MM,

UNIT_CM, UNIT_INCH, UNIT_PIXEL, UNIT_DOTS (specifiedin the set.fh include file)

Description:In GUI mode, all widgets (or controls in MS-Windows terminology) are pixel based.To enable the common Xbase (FlagShip, Clipper, FoxPro etc) compatibility,FlagShip internally recalculates the col/row coordinates to pixels according to theused font. The mm, cm, and inch coordinates are re-calculated according to thescreen resolution and size, returned (or set) by oApplic:DesktopHeight() andoApplic:DesktopWidth().

SET UNIT TO PIXEL is equivalent to SET PIXEL ON, SET UNIT TO ROWCOL isequivalent to SET PIXEL OFF.

Classification:programming, screen and printer coordinates

Compatibility:Available in VFS7 and later only.

Translation:SET ( _SET_COORD_UNIT, expN)

Related:SET PIXEL, SET()

CMD 438

SET UNIQUESyntax:

SET UNIQUE on|OFF|(<expL>)Purpose:

Defines whether only unique keys will be included while indexing or not.

Arguments:ON/OFF enables/disables the UNIQUE indexing. Alternatively, the parenthesized<expL> may be used, whereby TRUE is the same as ON.

Description:When UNIQUE is ON, and a new index is created with INDEX ON...TO, only uniquekeys are included in the index file, ignoring all subsequent keys of the same values.This is the same as creating an index with the INDEX...UNIQUE command.

Since the UNIQUE setting is stored in the index header, the index retainsuniqueness regardless of the UNIQUE settings at later REPLACE, REINDEX,PACK or other database operations.

If a unique key is changed to a value of a key already in the index, the changedrecord is lost from the index. If there is more than one instance of a key value in adatabase file, changing the visible key value does not bring forward another recordwith the same key until the index is rebuilt with REINDEX, PACK, orINDEX...UNIQUE.

Example:List all magazine names from a large article database:

SET UNIQUE ONUSE articleINDEX ON Magazine TO magname && UNIQUELIST magazine

SET UNIQUE OFFREINDEX && remains UNIQUEINDEX ON Magazine TO magnames && not UNIQUE


Translation:SET ( _SET_UNIQUE, .T.|.F.)

Related:FIND, INDEX, REINDEX, SEEK, SET INDEX, USE, SET(), oRdd:OrderIsUnique(),oRdd:CreateIndex(), oRdd:CreateOrder()

CMD 439

SET WRAPSyntax:

SET WRAP on|OFF|(<expL>)Purpose:

Toggles wrapping of the light bar in MENU TO.

Arguments:ON/OFF enables/disables the wrapping. Alternatively, the parenthesized <expL>may be used, whereby TRUE is the same as ON.

Description:Wrapping means that when the light bar is at the last option in MENU and thedown-arrow or right-arrow key is pressed, the lightbar moves to the first choice; ifthe light-bar is at the first choice and up-arrow or left-arrow key is pressed, the light-bar moves to the last choice of the MENU.

When WRAP is OFF, pressing up-arrow or left-arrow at the first menu item or down-arrow or right-arrow at the last menu item does nothing.

Example:@ 10,20 PROMPT "First item"@ 11,20 PROMPT "Second item"SET WRAP ONMENU TO choiceSET WRAP OFF


Translation:SET ( _SET_WRAP, .T.|.F.)

CMD 440

SETSTANDARDSETENHANCEDSETUNSELECTEDSyntax:

SETSTANDARDSyntax:

SETENHANCEDSyntax:

SETUNSELECTEDPurpose:

Selects the required color attribute for screen output.

Description:The color set with SET COLOR or SETCOLOR() can include three different colorpairs: the "standard", used in all screen output statements, the "enhanced" used [email protected], READ, MENU, ACHOICE and "unselected", used in the READ command.

In screen output commands (such as @...SAY, @...BOX, ?, QOUT() etc.), only the"standard" color pair will be used. The SETENHANCED and SETUNSELECTEDcommands switch the corresponding color pair to become the "standard" one,SETSTANDARD resets the original state.

Example:Simulates the READ output:

SET COLOR TO "W+/B,R+/BG,,,GR+/BG"@ 1, 2 say "Name, First"SETENHANCED@ 1,20 say "Smith "SETUNSELECTED@ 1,40 say "Peter "SETSTANDARD


Translation:_SETSTANDARD() | _SETENHANCED() | _SETUNSELECTED()

Related:SET COLOR, SETCOLOR(), READ, @..SAY, ?, ??

CMD 441

SET ZEROBYTEOUTSyntax:

SET ZEROBYTEOUT [TO] <expC>Purpose:

Set the output char for \0 byte in [q]qout() if fs_set("zero") is active.

Arguments:<expC> is the character displayed instead of \0 (binary zero) by ? and ??commands or Qout() and Qqout() functions. The default setting is chr(63) = "?"

Description:The embedded zero byte in strings cannot be displayed at all. To be able to see thischaracter in the output, the \0 byte is replaced by this substitute during the consoleoutput when FS_SET("zerobyte") is set .T.

SET ZEROBYTEOUT is considered also by SET OUTMODE which specify how todisplay other unprintable characters < 32



Related:Set(_SET_ZEROBYTEOUT), FS_SET("zero"), ?, ??, Qout(), Qqout(), SETCONSOLE

CMD 442

SKIPSyntax:

SKIP <expN1> [ALIAS <alias>|(<expN2>)]Purpose:

Moves the record pointer in the specified working area relative to the current pointerposition.

Arguments:<expN1> specifies the number of records to move the record pointer from thecurrent position. A positive value moves the pointer forwards, while a negative valuemoves the pointer backwards. SKIP 0 flushes the current working area buffers,equivalent to DBCOMMIT() or similar to COMMIT.

SKIP without an argument moves the record pointer to the next record in the currentworking area, having the same effect as SKIP 1.

Options:ALIAS causes movement of the record pointer in the designated working areaspecified by the <alias> name or by the numeric expression <expN2>.

Description:SKIP moves the record pointer to a new position relative to the record position inthe current or specified working area. If an index file is in use, SKIP moves thespecified number of positions according to the index keys.

SKIP also obeys SET FILTER and SET DELETED when calculating the movementof the record pointer.

Skipping beyond the end-of-file positions the record pointer at RECCOUNT() +1,and EOF() returns .T. Skipping backwards beyond the beginning-of-file moves therecord pointer to the first record, and BOF() returns .T.

Skipping on an empty index (created by INDEX...FOR), both BOF() and EOF()return TRUE and the record pointer is set beyond the end-of-file.

Multiuser:Any record movement command, including SKIP, will make changes in the currentworking area visible to other applications, if the current file is shared and changeswere made.

To force an update to become visible without changing the current record position,or to update the current FIELD variables, use SKIP 0 or COMMIT (or DBCOMMIT(),DBCOMMITALL() respectively). For further details, see chapter LNG.4.8.

CMD 443

Example:USE employee? RECNO(), name && 1 MillerSKIP? RECNO(), name && 2 JohnsonSKIP 1 + MAX(3,2)? RECNO(), name && 5 SmithSKIP -10? RECNO(), BOF(), name && 1 .T. MillerSELECT 2SKIP 5 ALIAS employee? employee->(RECNO()), employee->name && 5 Smith


Translation:DBSKIP (expN1) -or- alias->(DBSKIP (expN1))

Related:BOF(), EOF(), RECNO(), COMMIT, GOTO, SEEK, FIND, LOCATE, CONTINUE,DBCOMMIT(), DBCOMMITALL(), DBSKIP(), oRdd:Skip()

CMD 444

SORT ...ON...TOSyntax:

SORT ON <field1> [/[A|D][C]][,<field2> [/[A|D][C]] ...]

TO <file>|(<expC>)[<scope>][FOR <condition>] [WHILE <condition>]

Purpose:Sorts records from the database in use to a new database file according to thespecified key fields.

Arguments:ON <field1...fieldn> are the fields to be used as sorting criteria.

TO <file> is the name of the target database file. Unless otherwise specified, thenew file is assigned a .dbf extension. The given path or the SET DEFAULT isobeyed.

Options:/A/D/C or /AC or /DC specifies the order of the <field> sorting:

/A sorts records in ascending order from smallest to greatest value. This is thedefault setting.

/D sorts records in descending order from greatest to smallest value.

/C in case of a character field, ignores the character case.

<scope> is the part of the current database file to sort. The default scope is ALL.

<condition> specified by the FOR and/or WHILE clause restricts the range of thesource database to be sorted and copied to the target file.

Description:The SORT command is similar to INDEXing and COPYing one database toanother. Therefore, the result of the sorting also depends on the current UNIQUE,FILTER and DELETED setting.

Character fields are sorted by the ASCII value of each character (obeying thesorting order set by FS_SET("loadlang")), date fields chronologically, numeric fieldsare sorted in numeric order, and logical fields with the FALSE value first. Memofields cannot be sorted, but are copied to the target.

After replacing the sort key or adding a new record, the database is usually notsorted properly any more. Therefore it is more usual to use INDEX instead ofSORT, because indices are always updated automatically when assigned to thedatabase.

CMD 445

Multiuser:In a multiuser environment, the source database file must be opened inEXCLUSIVE mode.

Performance:For large databases, there is often much faster to use indices instead of SORT,since the SORT copies the whole database (or at least all records matchingFOR/WHILE/REST criteria). See example below.

Example:Outputs a list of magazine articles, grouped by the theme, from the latest to theoldest

USE articleSORT ON theme/AC, publ_date/D TO art_sortUSE art_sortLIST theme, publ_date, author

Example:The same example, using an index:

USE articleINDEX ON UPPER(theme) + DESCEND(DTOS(publ_date)) TO artsortLIST theme, publ_date, author


Compatibility:The new database carries the same access rights as the source database does,see LNG.3.3.4.

Translation:__DBSORT ("file", {"fields"}, ;

{for}, {while}, next, rec, .rest. )

Related:INDEX, ASORT(), SET EXCLUSIVE, USE..EXCLUSIVE, oRdd:Sort()

CMD 446

STATICSyntax:

STATIC <memvar> [:= <exp>] [, ...]Purpose:

Declares and optionally initializes STATIC variables and arrays.

Arguments:<memvar> is the name of a FlagShip variable or array, to be declared in the(lexically scoped) STATIC class. The name may be of any length, but only the first10 character are significant (see more LNG.2.6). Variable names in the FlagShiplanguage are not case sensitive.

If the <memvar> is followed by square brackets [ ], an array is created. The numberof elements for each array dimension can be specified as [dim1,dim2, ..,dimn] or[dim1][dim2][dimn]. The maximum number of dimensions and of the elements perdimension in FlagShip is 65535.

Options, Initializing:<exp> is any valid FlagShip expression including a literal (constant) array toinitialize the variable. If the initializer (:= <exp>) is not given, the variable (or allarray elements) will be set to NIL.

The STATIC variable will be created on program start with a NIL value. The time ofinitialization with the <exp> value depends on the variable scope, see below.

Scope, Visibility:The lifetime of STATIC variables is the entire program execution time. The scopeand visibility is restricted to the containing procedure or .prg file, depending onwhere the declaration statement is placed:

•UDF wide scope: if the STATIC declaration is given within a procedure orfunction body, the variables are visible there only. The variable is initialized by the<exp> value when first entering the module.

•File-wide scope: if the declaration is placed before the first FUNCTION orPROCEDURE statement and the compiler switch -na is used, the variable isvisible for all UDFs or UDPs within the .prg file. The initialization with the <exp>value is done when first entering any of the modules in the file.

The last value of a STATIC variable is available on subsequent entries into themodule (or .prg file). If a procedure or UDF is invoked recursively (calls itself), eachrecursive activation may change the static variables.

The static variables can be passed by value or by reference to other UDFs or UDPscalled at the same level. In code blocks, only STATIC variables of the modulewhere the block is declared are visible; see LNG.2.3.3.

CMD 447

STATIC variable declarations hide all inherited PRIVATE, PARAMETERS, PUBLICor FIELD variables with the same name. If the variable name is already declared inthe same module by using another declarator (LOCAL, GLOBAL, MEMVAR,FIELD), a compiler error is generated. For more information, refer to sectionLNG.2.6.

Description:STATIC is a declaration statement that declares one or more variables or arraysstatic to the current procedure or user- defined function or the whole .prg file.

In FlagShip, the STATIC declarator may be placed anywhere in the function body;the scope and visibility for the compiler starts from this declaration on.

The variable names are known at compile-time only. Therefore, a STATIC variablecan be evaluated by simple macros, but it cannot be used as composed macros orwithin the macro string; see also LNG.2.10. Static variables cannot be SAVEd andRESTOREd from .mem files, nor released by CLEAR or RELEASE.

To determine the type of a STATIC variable, only the standard functionVALTYPE(varname) can be used; since the TYPE("varname") tries to evaluate thestring using a macro and the variable is invisible during string evaluation.

Example:*** File test1.prg ***STATIC array1[20,10], array2[20][10] // file-wide scopeSTATIC array3 := { 1, 2, 3 } // file-wide scope

PROCEDURE test1 // not automatic.LOCAL var1 := "test"STATIC var2 := "test1" // UDP wide scopeSTATIC array4 := {DATE(), TIME()} // UDP wide scope? array3[1], array4[2]? test2 (var2), var2RETURN

FUNCTION test2 (par)STATIC var2 := VAL(TIME()) // UDF wide scope? var2++, parRETURN var2

Compile: $ FlagShip -na test1.prg [-m -c ...]


Compatibility:The lexical scope is new in FS4, and is compatible to Clipper 5x. Clipper has a fixedorder of the declaration and cannot use expressions to initialize the STATICvariable, but can use only a constant. Also the time of the initialization and themaximal array size is different in FlagShip and C5.

Related:STATIC..AS, LOCAL, GLOBAL, PRIVATE, PUBLIC, FIELDS, DO, FUNCTION,TYPE(), VALTYPE(), CONSTANT

CMD 448

STATIC ... ASSyntax 1:

STATIC <tvarList> [:= <expN>] AS <C-type>Syntax 2:

STATIC_<C-type> <tvarList> [:= <expN>]Purpose:

Declares and initializes C-TYPED STATIC variables.

Arguments:<tvarList> is a comma separated list specifying the names of variables, to bedeclared as TYPED STATIC. The name may be of any length, but only the first 10character are significant (see more LNG.2.6). The variable names in the FlagShiplanguage are not case sensitive; when accessing them from #Cinline statements,use lowercase.

AS <C-type> is the alternate syntax to STATIC_<type> where <type> is one of theC-like type keywords listed in LOCAL...AS.

Example of valid syntax:STATIC iVar := 4, ipos := 0, iCount AS INTSTATIC_LONG iOther := 5, myCount

Options, Initializing:<expN> is any valid expression returning a numeric value within the <type> rangeto initialize the variable at the declaration time. If the initializer (:= <expN>) is notgiven, the TYPED STATIC variables is initialized with zero.

The TYPED STATIC variable are created and initialized in the same way as theSTATIC variables, except that the initial value is zero instead of NIL.

Scope, Visibility:The scope, visibility and lifetime of TYPED STATIC variables is identical to theusual, lexical STATIC variables. The only difference is the fixed storage type, whichallows faster runtime access and the direct usage in #Cinline statements. Thelifetime is the entire executable, the scope and visibility depends on the declarationplacement:

•UDF wide scope: if the STATIC...AS declaration is given within the procedure orfunction body, the variables are visible in this entity only. The variable is initializedwith the <exp> value when first entering the module.

•File-wide scope: if the declaration is placed prior to the first FUNCTION orPROCEDURE statement and the compiler switch -na is used, the variable isvisible for all UDFs or UDPs within the .prg file. The initialization with the <exp>value is done when first entering any of the modules in the file.

CMD 449

The last value of the TYPED STATIC variable is available on the subsequententries into the module (or .prg file). If a procedure or UDF is invoked recursively(calls itself), each recursive activation may change the static variables.

Typed variables can be passed by value to other UDFs or UDPs called at the samelevel. In code blocks, only STATIC variables of the module where the block isdeclared are visible; see LNG.2.3.3.

Like with all other lexical variables, the STATIC...AS declarations hide all inheriteddynamic variables. For more information, refer to the section LNG.2.6.

Description:STATIC..AS is a declaration statement that declares TYPED lexical variable, verysimilar to STATIC, but:

•The type and storage range is fixed during compile time and cannot be changedat runtime. Since additional runtime type checking may be omitted, the usageresults in faster program execution.

•The variables occupy only 1, 4 or 8 bytes, compared to approx. 28 bytes forstandard FlagShip variables.

•The programmer must consider the storage range of the variable's <type>.Otherwise, the resulting value will be truncated to the (last) available bytes.

•The typed variables can be accessed directly in #Cinline statements (giving thename in lowercase).

•A TYPED variable cannot be used for any macro evaluation, but are usable incode blocks. The function VALTYPE(varname) will return "N"; TYPE("varname")cannot be used.

•The TYPED variables will always be passed to a UDF and UDP by value,regardless of the calling convention used (@ prefix or the DO...WITH procedurecall).

•If typed variables are intermixed with non-typed variables within an operation orcommand, they will be internally converted temporarily to non-typed ones.Therefore, use only typed variables or constants within the e.g. FOR... declarationto maintain the speed advantages.

The visibility is static to the current procedure, user-defined function or the whole.prg file. In FlagShip, the STATIC..AS declarator may be placed anywhere in thefunction body; the scope and visibility for the compiler start from this declaration.

CMD 450

Example:See also examples in chapter LOCAL...AS and GLOBAL...AS

*** File test.prgLOCAL angleLOCAL radian, sine, cosine AS DOUBLESTATIC_DOUBLE pi := 3.1415926535, deci := 2DO WHILE .T.

INPUT "Please enter angle 0..360 or <┘ only:" TO angleIF angle == NIL

RETURNENDIFradian := 2.0 * pi * angle / 360.0

#Cinlinesine = sin (radian); /* std. math library */cosine = cos (radian);

#endCinlineSET FIXED ONSET DECIMALS TO (deci++)? "sin(" + ltrim(str(angle)) + ")=", sine , ;"cos(" + ltrim(str(angle)) + ")=", cosine

angle := NIL // for the next entryENDDO


Compatibility:Typed variables are available in FlagShip and VO only. To remain compatible toClipper 5, use syntax 2 and #defines such as:

#ifndef FlagShip# define STATIC_BYTE STATIC# define STATIC_LONG STATIC# define STATIC_DOUBLE STATIC#endif

Related:STATIC, LOCAL...AS, LOCAL, GLOBAL, GLOBAL..AS, PRIVATE, PUBLIC,FIELDS, DO, FUNCTION, TYPE(), VALTYPE(), #Cinline, #define, #ifdef

CMD 451

STORESyntax 1:

STORE <exp> TO <memvarList>Syntax 2:

<memvar1> := [<memvar2> := ...] <exp>Purpose:

Initializes and/or assigns a value to one or more memory variables.

Arguments:<exp> is a value of any data type (constants, expression, memory variables,database fields) that is to be assigned to the target memory variable(s).

<memvarList> are the memory variables of any class to initialize and/or assignvalues. Their names can have any length, only the first 10 characters are significant(see more LNG.2.6).

Description:STORE is identical to the simple assignment operators = and :=, and refers to thesyntax 1 and 2. STORE assigns the same value to a set of memory variables. If thevariable name is unknown or invisible, a new autoPRIVATE is created.

When assigning a <memvar>, the same named memory variable takes precedenceover a field variable. To assign a value to a database field (same as REPLACE), thevariable must be declared as FIELD or the alias-> or the FIELD-> pseudo aliasmust precede the variable name.

On the other hand, when assigning <exp> to a variable, the field variable <exp>takes precedence over a dynamic memory variable with the same name, unless thedeclarator MEMVAR or the aliasing M-> or MEMVAR-> is used; see LNG.2.6 toLNG.2.9 and LNG.4.4.

To assign a value to an entire array, use the AFILL() function or the {...} literal array,see LNG.2.6.4 and LNG.2.7.

Example:Create PRIVATE variables var1..var3 and a..c:

STORE "String" TO var1, var2, var3a := b := c := 22? var1, var3, a, c // String String 22 22


Compatibility:The := assignment is available in FlagShip and C5 only. FlagShip allows anunlimited number of memory variables to exist at one time. The only physicallimitation is the available RAM memory plus the swap space of the operatingsystem.

CMD 452

Translation:<var1> := [ <var2 := ...] <exp>

Related:REPLACE, LOCAL, STATIC, GLOBAL, CLEAR MEMORY, PRIVATE, PUBLIC,RELEASE, SAVE, RESTORE

CMD 453

SUMSyntax:

SUM [<scope>] <expList>TO <memvarList>

[FOR <condition>] [WHILE <condition>]Purpose:

Sums a list of numeric expressions to specified memory variables for a range ofrecords in the current database file.

Arguments:<expList> is a list of numeric expressions (typically database fields) to SUM foreach processed record.

<memvarList> specifies the set of variables in which the results of summing are tobe stored. If a variable does not exist or is invisible, a new autoPRIVATE is created.The <memvarList> must have the same number of elements as the <expList>.

Options:<scope> is the part of the current database to SUM. The default scope is ALL.

<condition> specified by the FOR and/or WHILE clause restricts the range of thedatabase records to be calculated, see general command description.

Description:SUM totals a series of numeric expressions for a range of records in the currentworking area and assigns the results to a series of variables.

Example:USE employeepresent = 29.95SUM no_child * present TO total_spend FOR EMPTY(leavedate)? "We'll spend ", total_spend, ;" on Christmas presents for"

? "the employees' children"


Translation:var1 [ := var2 ... ] := 0DBEVAL ({|| var1 += exp1 [, var2 += exp2... ]}, ;


Related:AVERAGE, TOTAL, DBEVAL(), oRdd:Sum()

CMD 454

TEXT ... ENDTEXTSyntax:

TEXT [TO PRINT]|[TO FILE <file> [ADDITIVE]]<text>...

ENDTEXTPurpose:

Displays a block of text on the screen optionally echoing output to the printer and/ora text file.

Arguments:<text> is the block of literal characters to be displayed on the screen, exactly asformatted. The <text> may contain any number of lines, separated by the NEWLINE(LF or CR/LF) character.

Options:TO PRINT: echoes the display to the printer.

TO FILE: echoes the display to the specified <file>. Extension .txt is automaticallyadded if no other is specified. If the clause ADDITIVE is specified, the text isappended to, instead of overwriting the <file>.

Description:TEXT...ENDTEXT is a console command construct that displays a block of textlines to the screen, optionally echoing output to the printer and/or a ASCII file. Tosuppress the screen output, use SET CONSOLE OFF.

The text lines are displayed exactly as formatted in the .prg file, including anyindentation. Macro variables encountered within <text> block are expanded in thesame way as the macro text substitution).

Example:USE addressDO WHILE .not. EOF()

TEXT TO PRINTER&first &last&address

Dear &title &lastname :...

Sincerely,ENDTEXTEJECT ; SKIP

ENDDO

Classification:programming, sequential output

Compatibility:The ADDITIVE clause is available in FlagShip only.

Related:?, ??, @...SAY, MEMOEDIT(), MLCOUNT(), MEMOLINE(), LNG.2.10

CMD 455

TOTALSyntax:

TOTAL ON <keyExp> [<scope>][FIELDS <fieldList>]

TO <file>|(<expC>)[FOR <condition>] [WHILE <condition>]

Purpose:Summarizes records by key value by summing specified fields and copyingsummary records to a new database file.

Arguments:ON <keyExp> defines a group of records that produce, one after another, a newrecord in the target database. To make the summarizing operation accurate, thesource database should be indexed or sorted on the same <keyExp>.

TO <file> is the target file where the summary records are to be copied. The defaultextension, if not otherwise specified, is .dbf.

Options:FIELDS <fieldList> specifies the list of numeric fields to total. If the clause is notspecified, the fields are not totaled; while the target record contains the values ofthe first record matching the <keyExp>.

<scope> is the part of the current database file to total. The default scope is ALL.

<condition> specified by the FOR and/or WHILE clause restricts the range of thedatabase records to be totaled, see general command description.

Description:The TOTAL command sequentially processes the current database summarizingrecords by the specified key value and copying them to a new database file.

When the TOTAL starts, it copies first the structure of the source database into thetarget; but without memo fields. It then sequentially scans the current databasewithin the <scope>.

As each record with a unique <keyExp> is encountered, that record is copied to thetarget database. Otherwise, if the <fieldList> is specified, the values of source fieldsfrom the <fieldList> are added to the target fields.

Remember that numeric fields in the source database file must be large enough tohold the largest possible total for that field.

TOTAL considers the SET DELETED and SET FILTER status. If DELETED is OFF,the deleted records are copied to the target, but the delete flag will be not set.

CMD 456

Example:LOCAL total := 0USE employeeINDEX ON UPPER(lastname) TO emplnameTOTAL ON UPPER(lastname) FIELDS salary TO summary ;

FOR YEAR(salarydate) = YEAR(DATE())

USE summarySET CENTURY ON? "Salaries for the year", YEAR(DATE()), "to", DATE()WHILE .not. EOF()

? lastname, salarytotal += salarySKIP

ENDDO? "Total:", total


Translation:__DBTOTAL ("file", {keyexp}, { "field1"... }, ;


Related:AVERAGE, SUM, INDEX, SORT, oRdd:Total()

CMD 457

TYPESyntax:

TYPE <file1>|(<expC>)[TO PRINT][TO FILE <file2>|(<expC>) [ADDITIVE]]

Purpose:Displays the contents of a text file to the screen, printer and/or to another file.

Arguments:<file1> is the name of the ASCII file, including extension, that is to be displayed.

Options:TO PRINT sends the display to the printer file/device. The clause is equivalent toSET PRINTER ON.

TO FILE <file2> sends the display to the <file> specified in this clause. If noextension is specified, .txt is added. When using the ADDITIVE clause, the text isadded to, instead of overwriting the file.

Description:TYPE is a console command that displays the contents of a text file to the screen,optionally echoing the display to the printer and/or another text file. To suppress thescreen output, use SET CONSOLE OFF.

Ctrl-S is used to pause output. ESC has no effect on interrupting the listing. For asimilar, but paged output, RUN "cat file1 | pg" or MEMOEDIT() can be used.

Example:TYPE test.prg

@ MAXROW(),0 SAY "Scroll by PgUp/PgDn, ESC to continue"MEMOEDIT(MEMOREAD("test.prg"),1,0,MAXROW()-1,MAXVOL(), .F.)RUN MESSAGE "press any key..." cat test.prg | pgINKEY (0)REFRESH


Compatibility:The ADDITIVE clause is available in FlagShip only.

Translation:__TYPEFILE ("file1", .print., ["file2"],[.add.])

Related:COPY FILE, SET DEFAULT, SET PATH, SET PRINTER, FS_SET()

CMD 458

UNLOCKSyntax:

UNLOCK [<expN> | ALL]Purpose:

Releases file or record locks, which were set by the current program.

Options:<expN> is the physical record number, that is to be unlocked. When SETMULTILOCKS is ON and this argument is given (e.g. UNLOCK RECNO() orUNLOCK 5), only the specified record is unlocked, if such was previouslyRLOCKed. Otherwise, all record/file locks are removed.

ALL: if this clause is specified, all locks set by the current program in all usedworking areas are released. If the ALL clause is not given, only locks of thecurrently selected database are released.

Description:UNLOCK frees all records and file locks of the current or of all databases used inthe multiuser/multitasking mode.

Multiuser:In multiuser mode (or when using a concurrent databases accesses in the sameapplication), SET EXCLUSIVE OFF or USE...SHARED is required to open thedatabase in the current working area.

Before any write database access (like REPLACE, DELETE, RECALL), the recordor the database must be locked using RLOCK() or FLOCK(). Otherwise, if the lockis not set by the programmer, FlagShip invokes the AUTOxLOCK() function, if thisis not disabled by SET AUTOLOCK OFF. The only exception is APPEND BLANKwhich locks the new record automatically.

Note: global changes of the physical record storage (PACK and ZAP) or rebuildingthe index files (REINDEX and usually INDEX ON) requires an EXCLUSIVE openmode; for more see LNG.4.8.

When the write access is finished, UNLOCK will release the previously set recordand file locks, so that another user may lock the file or record. If the clause ALL isgiven, locks of all active working areas are released.

UNLOCK does not automatically release a record lock along a RELATION chainunless UNLOCK ALL or alias-> (DBUNLOCK()) is used.

If the AUTOxLOCK() function is invoked by FlagShip, it releases the lockautomatically after the write access, by using the AUTOUNLOCK() function.

Using another RLOCK(), FLOCK() or APPEND BLANK will also release theprevious locking of the current database. Closing the database and ending oraborting a program automatically releases all locks set by this executable.

CMD 459

The UNLOCK command in FlagShip implies updating the current working areabuffers to UNIX, which makes changes visible to other applications. To flush theUNIX or MS-Windows buffers physically to the file, use COMMIT, DBCOMMIT() orDBCOMMITALL(), see LNG.4.8. When SET AUTOCOMMIT is ON (default is OFF),every UNLOCK will also commit (flush) the current work area physically to harddisk, same as COMMIT.

Example:LOCAL new_name := "Smith", new_first := "Peter", countSET EXCLUSIVE OFFUSE address NEWWHILE NETERR(); USE ADDRESS; ENDSET INDEX to adr1, adr2FOR count = 1 TO 10

IF RLOCK()REPLACE name WITH new_nameREPLACE first WITH new_firstUNLOCKEXIT

ELSEIF count < 10? "waiting to lock this record"INKEY(1)

ELSE? "update failed"

ENDIFNEXT


Compatibility:This command and its usage is fully compatible to other xBASE dialects. Theinternal locking mechanism conform to the UNIX standard; the locking mechanismof other xBASE derivates are mostly not compatible.

In FlagShip, the multiuser mode also applies to the same database concurrentlyopen in different working areas; cf. the USE command.

The AutoLock and multiple record locking feature is new in FS4 and not available inClipper.

Translation:DBUNLOCK([expN]) | DBUNLOCKALL()

Related:SET EXCLUSIVE, SET AUTOLOCK, SET MULTILOCKS, USE, FLOCK(),RLOCK(), APPEND BLANK, AUTORLOCK(), AUTOFLOCK(), oRdd:Unlock(),oRdd:RlockList()

CMD 460

UPDATESyntax:

UPDATE ON <keyExp>FROM <alias>|(<expC>)REPLACE <field1> WITH <exp1>

[, <field2> WITH <exp2>...][RANDOM] [APPEND <expB>]

Purpose:Updates the current database file from another database file based on a keyexpression.

Arguments:ON <keyExp> is an expression defining the FROM records to be read.

FROM <alias> specifies the source working area which updates the current (target)database.

<fieldn> is the target field to be updated.

<expn> is the value or expression which updates the <fieldn>. Any field containedin the FROM working area must be referenced with the <alias>-> selector.

Options:RANDOM clause is used, when the FROM database is not indexed or sorted on<keyExp>, but only the current database has such an index active. If the RANDOMclause is not used, both the target and source must be indexed or sorted by the<keyExp>.

APPEND <expB> clause specifies, that, in case the <keyExp> is not found in thecurrent database, a new record should be added, the code block evaluated, and thefields replaced by the WITH clause(s). If the current database has not active index,no action is performed, since unpredictable results may occur.

Description:UPDATE replaces fields in the current working area with values from anotherworking area based on the specified key expression.

The UPDATE command supports 1:n and n:1 logical relations between the currentand the FROM area. When in the current (target) working area there is more thanone instance of the <keyExp> value, only the first record with the key value isupdated. However, the FROM work area can have duplicate key values, whichmultiply replace the target.

UPDATE works in two different ways, depending on the RANDOM clause:

•If RANDOM is specified, the current database must have an active indexmatching <keyExp>. The FROM database is skipped, while the matching recordis SEEKed in the current database and updated only if found; or a new record is

CMD 461

added in the current database, if the APPEND clause is given.

•If the RANDOM clause is not specified, the current database is SKIPpedaccording to the FROM sequence. The target record is updated only if the<keyExp> values exactly match in both the target and source record; or a newrecord is added in the current database, if the APPEND clause is given.

Multiuser:In multiuser mode, the current database file must be locked with FLOCK() or usedEXCLUSIVEly; otherwise AUTORLOCK is used, if possible. The FROM databasefile may be opened in any mode.

Example:SELECT 1USE custom INDEX custom EXCLUSIVE? INDEXKEY() //UPPER(name)USE invoice INDEX inv_cust ALIAS inv NEW? INDEXKEY() //UPPER(name)SELECT 1UPDATE ON UPPER(name) FROM inv ;

REPLACE debit WITH debit + inv->amountUSE orders NEWSELECT 1FIELD name, idUPDATE ON UPPER(name) FROM orders ;

REPLACE debit WITH debit + orders->amount ;APPEND {|| name := orders->name, id := orders->idnum }


Compatibility:The APPEND clause is available in FlagShip only.

Translation:__DBUPDATE ("alias", {keyExp}, .random., ;{|| _FIELD->fld1 := exp1 [, _FIELD->fld2 := exp2...] }, ;[appendBlock] )

Related:APPEND FROM, REPLACE, JOIN, INDEX, SORT, SET AUTOLOCK.oRdd:Update()

CMD 462

USESyntax:

USE <file>|(<expC>)[ALIAS <alias>|(<expC>)][INDEX <fileList>|(<expC>)][EXCLUSIVE | SHARED][READONLY][NEW][NFS][VIA <driver>]

Syntax 2:USE

Purpose:Opens the specified database file, its associated memo file when memo fields exist,and, optionally, associated index files in the selected working area.

Arguments:<file> is the name of the database file to open in the current (or a NEW) workingarea. If an extension is not specified, the default .dbf extension is assumed. The<file> can optionally include drive and/or path. If only file name is given, thedatabase file name is searched for:

•in the current directory (see also note below)

•in the path specified by SET DEFAULT statement (if any)

•in all paths specified by SET PATH command (if any)

If the file could not be opened (file not found or access denied), no error messageoccurs when SET OPENERROR is OFF. You therefore should test the success orfailure of USE command by subsequent USED() which returns .T., or by NETERR()which returns .F. on success.

If <file> is not specified (syntax 2), the current working area is closed, equivalent tothe CLOSE command.

Options:ALIAS <alias> is the name to be associated with the working area. If not specified,the main part of the <file> name is assigned to <alias>. If the given alias is invalid,USE will try to generate a valid name and will display corresponding warning.

INDEX <fileList> specifies up to 15 index files to be opened in the current workingarea. Each index file may be specified either as a literal filename or as a characterexpression enclosed in parentheses. If the <expC> returns NIL or an empty string, itis ignored. The first index file in the list becomes the controlling index. It is notrecommended to use this clause in multiuser mode. See also SET INDEX, INDEXON and LNG.4.5.

CMD 463

EXCLUSIVE opens the database file for non-shared use in a network ormultitasking environment. Other users cannot access the database until it is closed.It is a synonym for USE with SET EXCLUSIVE ON. This clause overrides the SETEXCLUSIVE state.

SHARED opens the database file for shared use in a multiuser, multitasking,network or concurrent mode. It is a synonym for USE with SET EXCLUSIVE OFF.This clause overrides the current SET EXCLUSIVE state.

NEW selects an unused working area making it the current one, and opens thedatabase <file> there. The clause is equivalent to SELECT 0 prior to the USE...command. If this clause is not given, the database is opened in the currentlySELECTed working area.

NFS clause enables the global switch SET NFS ON, which then remain active forall subsequent database actions and USEs until SET NFS is set OFF. This clausecan be used for databases and indices located on NFS mounted file system, whenthe NFS server does not flush all buffers correctly - resulting sometimes incorrupted index reported by IndexCheck(). See further details in the SET NFSdescription.

READONLY opens the database for read-only purposes. The UNIX access rights -r- are sufficient for the database and memo <file> (but not for index files, whichmust be always -rw-). An attempt to REPLACE or APPEND a record brings a run-time error.

VIA <driver> defines the replaceable database driver (RDD) to use for the currentworking area. The default is the "DbfIdx" RDD. You may need to add the statement"EXTERN <driver>" (e.g. EXTERN myRdd) to force the linker to add your RDDdriver into the executable, if the object file containing "CLASS myRdd" is not linkedexplicitly. To set another driver globally, use RddSetDefault("myRdd")

Description:USE opens an existing database .dbf file, its associated memo .dbt (or .dbv) file,and optionally associated index .idx files in the current or the next available workingarea. Before USE opens a database file and its associated files, it closes any activefiles already open in the working area.

Note: when only <file> name is given (without path), the database is tried to open inthe current directory (and then in SET DEFAULT, SET PATH directories whenspecified). This means "access in current directory" work fine when you start theexecutable from the working directory containing your data. However when you (orthe end-user) invoke the application from other drive or directory or by searchingthe PATH environment variable, or via link on desktop, or via file manager (likeWindows Explorer, NC, Konqueror etc.), the used "current directory" is mostprobably not what you really meant :-) In such a case, either use fully qualified filenames, or (better) specify the current directory by CURDIR("/my/data") or use SETDEFAULT TO "D:\my\data" or SET DEFAULT TO (getenv("MYDATA")) which readsthe setting from user's environment variable etc. In doubt, you may check/display

CMD 464

the current directory by CURDIR() and the availability of files by IF!FILE("mydata.dbf") ; SET DEFAULT ... see example below.

After opening the database, the record pointer refers to the first physical record inthe file which defaults to record 1 if no index file is specified. With active index, therecord pointer is set to the first logical record. When SET DELETED is ON or SETFILTER is active, you will need to invoke GO TOP to set the pointer to the firstvisible record. Note the GO TOP is not done automatically for performancepurposes and to allow you to check the indices via IndexCheck() before moving therecord pointer.

When opening an empty database or an empty index (created by INDEX...FOR),both BOF() and EOF() return TRUE and the record pointer is set beyond the end-of-file.

USE without an argument closes the active database file and the associated memoand index files, if any, equivalent to the CLOSE command. To close the databasefiles in all work areas, use CLOSE ALL or CLOSE DATABASES.

When the open fail, NetErr() will report .T. and Used() .F. When SET OPENERRORis ON (the default), an open failure will raise run-time error. If you wish to avoidRTE, use SET OPENERROR OFF and check the NetErr() or Used() status.

Additional warnings are available by using FS_SET("devel", .T.)

In FlagShip, up to 65534 working areas may be opened simultaneously, each withup to 65534 indices and relations.

Each working area has the following attributes:

Attribute/Action Retrieving Command/FunctionOpen/close work area USE, CLOSE DATAChange work area SELECT WAno, SELECT aliasIndices USE..INDEX, SET INDEXRelations SET/CLOSE RELATIONFiltering SET FILTER, SET DELETEDSearching SEEK, LOCATE, FINDMoving GOTO, SKIPAlias name ALIAS()Database file DBF(), INDEXDBF()Working area no. SELECT()Index file ext, names INDEXEXT(), INDEXNAMES()Index key, contrl.no. INDEXKEY(), INDEXORD()Index integrity check INDEXCHECK()Record number RECNO()Record count LASTREC(), RECCOUNT()Field count FCOUNT()Field name FIELD()Field description AFIELDS()Beginning-of-file flag BOF()End-of-file flag EOF()

CMD 465

Filter condition DBFILTER(), DELETED()Locate/Seek result FOUND()Relation DBRELATION(), DBRSELECT()Header size HEADER()Network cmd result NETERR()Locking RLOCK(), FLOCK(), UNLOCK, SET AUTOLOCK, AUTOxLOCK(),

SET MULTILOCKS

Multiuser:If a multiuser, multitasking and/or network access is required, database files can beopened EXCLUSIVEly or SHARED. The exclusive status stops the database frombeing used by other users (or in other working areas concurrently) until the file isclosed; the shared mode allows other users to use the database and its associatedfiles for concurrent access.

The open status of the database is determined by the SET EXCLUSIVE command,or the EXCLUSIVE or SHARED clause respectively:

•If SET EXCLUSIVE is ON (the default), the database is open exclusively; thegiven SHARED clause will override the current global setting.

•If SET EXCLUSIVE is OFF, the database is open in sharable mode. Specifyingthe EXCLUSIVE clause on the USE command will override the default setting.

Opening a database EXCLUSIVEly will succeed only if it is not already in use bysome other user. Attempting to open a database SHARED will succeed only if thedatabase is not opened exclusively by another user (or concurrently in anotherworking area).

Instead of USE..INDEX.. it is better practice to open the database, check successby USED(), then assign index/indices by SET INDEX TO.. and check success byNETERR() which should be .F.

In the SHARED mode, any write attempt to the database or memo file (likeREPLACE, DELETE, RECALL, or alias->name := ...) requires that the currentrecord or the whole file is locked beforehand using RLOCK() or FLOCK(). This willensure data integrity denying other users a write access to the same record ordatabase. When the write access is finished, use UNLOCK or UNLOCK ALL torelease the previously set record and file locks, so that another user may lock thefile or record. If the lock is not set by the programmer and SET AUTOLOCK is ON,FlagShip locks the record or file automatically by using the AUTOxLOCK() function.

Global changes to the physical record storage order (PACK and ZAP) or rebuildingthe index files (INDEX, REINDEX) requires an EXCLUSIVE open mode.

Concurrent Databases:For special purposes, FlagShip allows the same database to be USEdsimultaneously in different working areas, when the given ALIAS names aredifferent. Note: FlagShip distinguishes between database equivalents on the sameinode number, not only on the DBF() name itself. When performing operations on

CMD 466

the SAME physical database (used concurrently in different working areas), seealso chapter LNG.4.8.7.

The handling of concurrent databases is the same, as the usage of shareddatabases in multiuser mode. Therefore, using concurrent databases in the sameapplication requires their SHARED use, NETERROR() checking and RLOCK() orFLOCK() on write access.

Large Files:FlagShip supports also large files > 2Gigabytes. If you need to use this feature,enable SET LARGEFILE ON at the begin of your application, latest before open thedatabase. See additional details in CMD.SET LARGEFILE.

Tuning:As noted above, FlagShip do not raise run-time error on failure, so check byUSED() or NETERR() reports failure or success. You however may force RTE 501on failure by assigning

_aGlobSetting[GSET_L_DBUSEAREA_ERR] := .T. // default = .F.which then behaves FoxPro conform.

When the database is closed, FlagShip flushes the database and index files to harddisk. You may optimize this by setting

_aGlobSetting[GSET_N_CLOSEOPTIMIZE] := 1 //defaultwhere 0 = flush always except opened read only, 1 = only if changed, and 3 = don'tflush.

Example:Open 3 databases (and their indices) in single user mode:

SELECT 22USE address // address in WA 22SELECT 1 // customer in WA 1USE "\data\customer" ALIAS cust INDEX customerif neterr()

alert("cannot open customer database or index")endifUSE invoices NEW // invoices in next WAIF .not. FILE("inv_1" + INDEXEXT()) // inv_1.idx

INDEX ON customno TO inv_1INDEX ON invdate TO inv_2

ENDIFSET INDEX TO inv_1, inv_2

Example:Open a database and its indices in multiuser mode:

SET EXCLUSIVE OFF // multiuserUSE addresscount := 0while !used() .and. file("address.dbf") // error ?

sleepms(100) // wait 0.1 secUSE address // yes, try againif ++count > 20 // but max.

exit // for 2 secondsendif

CMD 467

ENDDOif !used()

alert("cannot open address.dbf")quit

endif

SET INDEX TO adr_name, adr_zipif NETERR()

alert("could not open index ...")quit

endif

Example:Open a database and indices SHARED with RTE on failure

LOCAL dbfname := "address", idx1 := "adr_name", idx2 := "adr_zip"_aGlobSetting[GSET_L_DBUSEAREA_ERR ] := .T. // force RTE on failure_aGlobSetting[GSET_L_DBSETINDEX_ERR] := .T. // force RTE on failure

USE (dbfname) SHARED NEW INDEX (idx1), (idx2)

Example:Check and set the "working directory" from the current location, or from userenvironment variable MYDATA, or from location of the executable:

#include "fspreset.fh" // optional, see LNG.9LOCAL dbfname := "address"LOCAL cWorkDir := "", lFound := .F.// check current directoryif file(dbfname + ".dbf")

lFound := .T. // everything is okendif// check directory specified in environment variablecWorkDir := getenv("MYDATA")if !lFound .and. !empty(cWorkDir)

if file(cWorkDir + PATH_SLASH + dbfname + ".dbf")SET DEFAULT TO (cWorkDir) // or: CURDIR(cWorkDir)lFound := .T.

endifendif// check the directory of executable (i.e. of current .exe file)cWorkDir := left(execname(.T.), rat(execname(.T.),PATH_SLASH) -1)if !lFound .and. !empty(cWorkDir)

if file(cWorkDir + PATH_SLASH + dbfname + ".dbf")SET DEFAULT TO (cWorkDir) // or: CURDIR(cWorkDir)lFound := .T.

endifendifif !lFound

alert("Sorry, cannot locate the databases, set MYDATA envir.")quit

endif// now you can handle it w/o worrying about current directoryUSE (dbfname) ...

CMD 468

Example:Example for multitasking, support of the DOS file and path names also inUnix/Linux, the usage of a general open routine, including checking for success:

SET EXCLUSIVE OFF // multiuser mode#ifdef FlagShip

FS_SET ("lower", .T.) // auto file transl.FS_SET ("pathlower", .T.) // auto path transl.IF GETENV("C_FSDRIVE") == "" // C: drive substitution

? "set the environment var C_FSDRIVE first !"QUIT

END#endifSET DEFAULT TO C:\Data\Adr // DOS path support is avail.SELECT 23IF .not. FILE("adr_name" + INDEXEXT()) .OR. ;

.not. FILE("adr_idno" + INDEXEXT())my_use ("Address",, .T., .F.) // USE..EXCLUSIVEINDEX ON UPPER(name) + STR(zip,1,5) TO adr_nameINDEX ON custno TO adr_idno

ENDmy_use ("address", "adr" .F., .F.) // USE..SHAREDSET INDEX TO adr_name, adr_idnoSELECT adrSEEK "SMITH" // seek nameSEEK "SMITH 54321" // seek name + zipSET ORDER TO 2SEEK 12345 // seek id number

FUNCTION my_use (dbf, alias, excl, new)**************************************** [dbf] (C) dbf name* [alias] (C) alias name or NIL for alias=dbf* [excl] (L) .T. use exclusive, NIL for SET EXCLUSIVE flag* [new] (L) use in a new working area

LOCAL timebeg := SECONDS(), ii := 0LOCAL shared := IF (excl != NIL, !excl, NIL)new := IF (new == NIL, .F., new)alias := IF (alias == NIL .or. EMPTY(alias), NIL, alias)#define TIMELIMIT 10IF EMPTY(dbf)

USEELSE

DBUSEAREA (new, , dbf, alias, shared)WHILE NETERR() .AND. (SECONDS() - timebeg) <= TIMELIMIT

@ 0,0 SAY str(++ii) + ". try to open database " + dbfINKEY(1) // error, try againDBUSEAREA (new, , dbf, alias, shared)@ 0,0

ENDDOENDIFRETURN USED()

CMD 469


Compatibility:The clause NEW, SHARED, EXCLUSIVE, READONLY and VIA are available inFS4 and C5 only. FlagShip is able to handle 65534 working areas simultaneously,each with additional memo files and up to 15 indices. Clipper'87 supports 255,Clipper 5.x and VO up to 250 working areas only. Refer to the section SYS for theUNIX kernel settings for open file limits.

Large file support (over 2 Gigabytes) depends on the used operating system and isavailable in VFS 6.1 and newer. Once the file exceeds the 2 GB limit, it isincompatible to DOS!

See also chapter LNG.9.5 describing how to maintain full compatibility to the DOSwritten programs running on UNIX. All databases and memo files must betransferred from or to DOS using a binary protocol. If the text mode is used thedatabase is corrupted !

Translation:DBUSEAREA(.new.,"rdd","dbfName","alias", .shared., .ronly.)[ DBSETINDEX (indexname1) ...]

Related:CLOSE, SELECT, SET AUTOLOCK, SET MULTILOCKS, SET INDEX, NETERR(),SELECT(), RLOCK(), FLOCK(), UNLOCK, USED(), DBF(), FS_SET(),DBUSEAREA(), RddSetDefault(), SET LARGEFILE, OBJ.6, RDD.3

CMD 470

WAITSyntax:

WAIT [POPUP | WINDOW][TIMEOUT <expN2>][COLOR <expC3>][GUICOLOR <expC4>][GUISHAPE <expN5>] [NOSHAPE][ECHO|NOECHO][<expC1>]

WAIT [<expC1>]TO <memvarC>

[POPUP | WINDOW][TIMEOUT <expN2>][COLOR <expC3>][GUICOLOR <expC4>][GUISHAPE <expN5>] [NOSHAPE][ECHO|NOECHO]

Purpose:Displays a prompt and waits for a key to be pressed.

Options:<expC1> is the user prompt which is displayed if specified. It can be an expressionof any data type. If <expC1> is not specified, the default prompt "Press any key tocontinue..." will be displayed. Note: this default string is pre-defined in the globalvariable _aGlobSetting[GSET_C_WAITPROMPT] (see also the ininit.prg source)and may hence be simply re-defined to your preferred prompt text. If a null string isspecified, only NEWLINE is printed. When SET CONSOLE is OFF, neither newlinenor the prompt is displayed.

<memvarC> is the memory variable to contain the character entered. If the variabledoes not exist or is not visible, a new autoPRIVATE one is created.

POPUP displays the message in Popup window (MessageBox) instead of the nextconsole row. The equivalent WINDOW clause is supported for FoxPro compatibility.

TIMEOUT <expN2> waits max. for <expN2> seconds. If not given, wait until userkey press.

COLOR <expC3> specifies the color for displaying the <expC1> data. Only the firstcolor pair (standard) is significant. If this clause is not given, the current color settingis used. In GUI mode, first the GUICOLOR clause is checked. If not set, theCOLOR <expC3> or the current color is used, but only when SET GUICOLOR isON. Specifying COLOR and GUICOLOR allows you to handle different colors forGUI and Terminal mode, without switching the SET COLOR and SET GUICOLORsetting.

CMD 471

GUICOLOR <expC4> specifies the color for displaying the <expC1> dataconsidered in GUI mode. Only the first color pair (standard) is significant. IfGUICOLOR is set, it is used regardless the current SET GUICOLOR on/off setting.If omitted and SET GUICOLOR is ON, either the COLOR <expC3> is used if given,or the current SetColor() is used. The GUICOLOR clause apply for GUI mode only,and is ignored otherwise.

GUISHAPE <expN5> specifies the text cursor shape displayed at the end of theprompt message <expC1> and signaling an user input. Apply for GUI mode only,ignored otherwise. The default shape is CURSOR_HAND, but may be re-defined byany other value assigned to global variable _aGlobSetting[GSET_G_N_WAITSHAPE]. You may override it temporarily by setting your own shape using theCURSOR_* constant or it corresponding value:

mouse.fh constant value Description0 same as CURSOR_INVISIBLE

CURSOR_ARROW -1 standard arrow cursorCURSOR_UPARROW -12 upwards arrowCURSOR_CROSS -8 crosshair (+)CURSOR_WAIT -9 hourglassCURSOR_IBEAM -11 i-beam (I)CURSOR_SIZE_VER -2 vertical resizeCURSOR_SIZE_HOR -3 horizontal resizeCURSOR_SIZE_RDIAG -5 diagonal resize (/)CURSOR_SIZE_LDIAG -4 diagonal resize (\)CURSOR_SIZE_ALL -13 all directions resizeCURSOR_INVISIBLE -17 blank/invisible cursorCURSOR_SPLITVER -14 vertical splittingCURSOR_SPLITHOR -3 horizontal splittingCURSOR_HAND -6 a pointing handCURSOR_FORBIDDEN -16 forbidden action cursorCURSOR_UNDERSCORE -21 underscoreCURSOR_BOX -22 box in size of one largest characterCURSOR_DEFAULT_TEXT -21 same as CURSOR_UNDERSCORE

NOSHAPE disables the text cursor displayed at the end of the prompt messageand is equivalent to GUISHAPE 0 or GUISHAPE CURSOR_INVISIBLE clause.

ECHO or NOECHO clause temporarily overrides the current setting of Set(_SET_WAIT_ECHO). Echo is displayed only when SET CONSOLE is ON.

Description:WAIT is a console command with wait state. The specified or default prompt isdisplayed after a NEWLINE. The command then waits for a user input or reads onefrom the type-ahead buffer. The input key is echoed on the screen if not disabled bythe NOECHO clause or by global setting SET(_SET_WAIT_ECHO,.F.).

When the TIMEOUT <expN2> is specified and a key is not pressed within the giventime frame, WAIT exits returning "".

CMD 472

When a key assigned via SET KEY or ON KEY is pressed, the UDF is executedand WAIT waits for next key input. When the Escape (K_ESC) key was assigned toan UDF by SET KEY or ON [ANY] KEY, you need to press Escape key twice toterminate WAIT - this avoids a possible infinite loop.

When a FN key is assigned to a string by SET FUNCTION and this FN key waspressed, WAIT exits returning the assigned string in the <memvarC> variable.

For backward compatibility to other xBase dialects, function keys are ignored if notassociated to SET KEY, ON KEY or SET FUNCTION. When function keys (i.e.inkey() values 28 and less than 0) should exit WAIT too, use SET(_SET_WAIT_IGNFUN,.F.) - the default setting is .T.

When you don't wish echo the input key, use Set(_SET_WAIT_ECHO,.F.) wherethe default setting is .T. You also may use the ECHO | NOECHO clause totemporarily override the global status for this WAIT.

WAIT displays the <expC1> or standard prompt per default also with SETCONSOLE OFF. You may disable this feature by assigning

_aGlobSetting[GSET_L_WAIT_PROMPT] := .F. // default is .T.which then considers current SET CONSOLE setting. Without this set, you alsomay use WAIT "" to avoid prompt, or WAIT "" NOECHO which is then equivalent toInkey(0). The above setting however does not affect waiting for user key press,which always apply.

Example:WAIT TO key//WAIT NOECHO "press any key to continue, ESC to abort"IF lastkey() = 27

QUITENDIF//@ 10,0 say "Press any key: "key := INKEY(0)IF key > 32

?? CHR(key)ENDIF


Compatibility:The support of foreign language prompts is available in FlagShip only. The COLOR,GUICOLOR, POPUP, TIMEOUT, ECHO, NOECHO, GUISHAPE and NOSHAPEclauses are new in FS5. For FlagShip 4 compatible behavior, useSet(_SET_WAIT_IGNFUN,.F.), see text above.

Translation:[var := ] __WAIT ( [exp], ... )

Related:@..GET, READ, ACCEPT, INPUT, INKEY(), FS_SET(), ?, ??, QOUT(), SETGUICURSOR, SetGuiCursor()

CMD 473

ZAPSyntax:

ZAPPurpose:

Removes all records from the currently selected database file.

Description:ZAP permanently removes all records from the database, memo file and associatedindices in the current working area. The disk space previously occupied by theallocated files is released.

ZAP performs the same operation as COPY STRUCTURE and REINDEXcommands. It is therefore faster, than the similar DELETE ALL followed by PACK.

Multiuser:ZAP requires the database to be EXCLUSIVEly opened.

Example:USE taxes INDEX tax? RECCOUNT() && 34ZAP? RECCOUNT() && 0

Example:// The same example as multiuser:

SET EXCLUSIVE OFFmy_use ("taxes", , .T.) // see example of USESET INDEX TO tax? RECCOUNT() // 34ZAPmy_use ("taxes", , .F.) // USE shareableSET INDEX TO tax? RECCOUNT() // 0


Translation:__DBZAP()

Related:DELETE, PACK, USE, COPY STRUCTURE, oRdd:Zap()

CMD 474

CMD 475

Index CMD

!

! command ................................... CMD-11

&

& CMD-see &see comment

*

* comment............................ CMD-14, 239

.

.BMP image ........................... CMD-37, 60

.FRM Report file................. CMD-286, 288

.GIF image ............................. CMD-37, 60

.JPEG image.......................... CMD-37, 60

.LBL Label file .................... CMD-212, 215

.MEM memory file .............. CMD-291, 301

.PNG image ........................... CMD-37, 60

.PPM image ........................... CMD-37, 60

.XBM image ........................... CMD-37, 60

.XPM image ........................... CMD-37, 60

/

/*...*/ comment ............................. CMD-14// comment ................................... CMD-14

?

? command .................................. CMD-16?# command ................................ CMD-20?? command ................................ CMD-16??# command .............................. CMD-20??## command ............................ CMD-20

@

@..BOX........................................ [email protected] ............................. CMD-22, 28

@..DRAW CIRCLE ...................... [email protected] ELLIPSE..................... [email protected] IMAGE........................ [email protected] LINE ........................... [email protected] POLYGON ................. [email protected] RECTANGLE ............. [email protected] ........................................ CMD-64

- align fields ............................ CMD-372- color selection ...................... CMD-388- confirm exit........................... CMD-330- field delimiters ...................... CMD-341- multi-byte characters............ CMD-399

@..GET..CHECKBOX.................. [email protected]................. [email protected]....................... [email protected] ............. [email protected]............ [email protected] ............. [email protected].................. [email protected]........................ CMD-48, 232

- message............................... [email protected] ........................................ [email protected] BITMAP.......................... [email protected] IMAGE............................ [email protected]............................... [email protected] ........................................ CMD-104

A

ACCEPT .................................... CMD-106ACCESS ............................ CMD-107, 235Alias

- assign................................... CMD-462- select .................................... CMD-309

ANNOUNCE .............................. CMD-108ANSI..................... CMD-see character setAPPEND BLANK ....................... CMD-110APPEND FROM......................... CMD-111Application

- terminate .............................. CMD-266Array

- browsing............................... CMD-102- declaration............................ CMD-159- local .............................. CMD-219, 222- private .......................... CMD-159, 248

CMD 476

- public.................................... CMD-261- static............................. CMD-446, 448

ASCENDING clause .................. CMD-199ASCII.................... CMD-see character setASSIGN ............................. CMD-107, 235AVERAGE.................................. CMD-115

B

Background- processing...................... CMD-12, 296

BEGIN SEQUENCE .................. CMD-116Box

- checkbox................................ CMD-76- combo .................................... CMD-80- command ............................... CMD-23- listbox ..................................... CMD-82- pushbutton ............................. CMD-88

BREAK....................................... CMD-116Button

- pushbutton ............................. CMD-88- radiobutton ............................. CMD-93- radiobutton group................... CMD-97

C

C function- invocation ............................. CMD-121

Call- C function ............................. CMD-121- function................................. CMD-186- procedure ............................. CMD-168

CALL .......................................... CMD-121CANCEL ............................ CMD-123, 266CASE ......................................... CMD-170Century ...................................... CMD-320Change directory ....................... CMD-344Character set

- database .............................. CMD-314-- ISO, ANSI........................ CMD-336-- PC8, ASCII, OEM............ CMD-336

- in GUI mode......................... CMD-377- keyboard

-- ISO, ANSI........................ CMD-393-- PC8, ASCII, OEM............ CMD-393

- source-- ISO, ANSI........................ CMD-433-- PC8, ASCII, OEM............ CMD-433

- unprintable characters ......... CMD-408Checkbox

- create ..................................... CMD-76Class

- access method..................... CMD-235- assign method...................... CMD-235- declaration............................ CMD-124- instance................................ CMD-124- Instance................................ CMD-126

-- exported .......................... CMD-126-- hidden.............................. CMD-126-- protected ......................... CMD-126

- method ................................. CMD-235- prototyping ........................... CMD-124

CLASS ....................................... CMD-124Clear

- get fields............... CMD-131, 132, 133- keyboard buffer .................... CMD-138- memory ........................ CMD-134, 279- screen .................... CMD-28, 131, 136

CLEAR ....................................... CMD-131CLEAR ALL................................ CMD-132CLEAR GETS ............................ CMD-133CLEAR MEMORY...................... CMD-134CLEAR MENU ........................... CMD-135CLEAR SCREEN....................... CMD-136CLEAR TYPEAHEAD ................ CMD-138Close

- alias...................................... CMD-139- database .............................. CMD-139

-- all ..................................... CMD-132- get fields............... CMD-131, 132, 133- index..................................... CMD-139

-- all ..................................... CMD-132CLOSE....................................... CMD-139CLS ............................................ CMD-136Color

- background .......................... CMD-322- border................................... CMD-322- enhanced ..................... CMD-322, 440- foreground............................ CMD-322- in GUI mode ......................... CMD-373- output ............................... CMD-17, 53- standard ....................... CMD-322, 440- unselected.................... CMD-322, 440

Combo box- create ..................................... CMD-80

Command- abbreviation.............................. CMD-7

CMD 477

- argument .................................. CMD-7- case sensitivity ......................... CMD-7- clause....................................... CMD-8- keyword.................................... CMD-7- notation .................................... CMD-7- scope........................................ CMD-8- translation................................. CMD-9

Comments............................ CMD-14, 239COMMIT .................................... CMD-141Compiler

- procedure files...................... CMD-420condition

- if..endif.................................. CMD-197CONSTANT ............................... CMD-145CONTINUE ................................ CMD-144Coordinate

- units...................................... CMD-437Coordinates

- in pixel .................................. CMD-412COPY FILE ................................ CMD-146COPY STRUCTURE.................. CMD-151COPY TO................................... CMD-147COPY TO..STRUCT .................. CMD-152Copying

- databases............................. CMD-147- files ....................................... CMD-146

COUNT ...................................... CMD-154CREATE ............................ CMD-155, 156Cursor

- type....................................... CMD-374- wait ....................................... CMD-470

Cut and paste....................... CMD-71, 271

D

Database- add record ............................ CMD-110

-- automatically ................... CMD-347- add records

-- from other database CMD-111, 209-- from text file..................... CMD-111

- assign index ......................... CMD-384- average ................................ CMD-115- browsing............................... CMD-102- calculate

-- average ........................... CMD-115-- records in scope.............. CMD-154-- sum.................................. CMD-453

- character set ................ CMD-314, 336- clear ..................................... CMD-473- close............................. CMD-139, 462- close all ................................ CMD-132- commit.................................. CMD-141- controlling index ................... CMD-406- copy...................................... CMD-147

-- structure .......................... CMD-152- count records ....................... CMD-154- create

-- from other database ........ CMD-152-- from structure .................. CMD-156-- structure .................. CMD-151, 155-- totals................................ CMD-455

- default directory.................... CMD-410- delete all records.................. CMD-473- delete record ........................ CMD-161- deleted records

-- visible .............................. CMD-340- delimited input ...................... CMD-111- delimited output.................... CMD-147- display

-- records ............................ CMD-217-- records scope.................. CMD-167

- error handling ....................... CMD-405- exclusive .............................. CMD-354- field

-- assign .............................. CMD-282-- modify.............................. CMD-282-- replace............................. CMD-282

- filter-- clear................................. CMD-358-- set.................................... CMD-358

- filtering.................................. CMD-358- flushing................................. CMD-141- index

-- close ................................ CMD-384-- create .............................. CMD-199-- open ................................ CMD-384

- indexing........................ CMD-199, 277- join with other database ....... CMD-209- locking

-- automatic......................... CMD-316-- multiple ............................ CMD-401-- unlock .............................. CMD-458

- merge ................................... CMD-209- modify record ....................... CMD-282- multi-user ..................... CMD-462, 465- open ..................................... CMD-462

CMD 478

-- error handling .................. CMD-405-- exclusive.......................... CMD-354-- shared ............................. CMD-354

- packing................................. CMD-244- record movement ......... CMD-194, 442

-- bottom ............................. CMD-194-- top ........................... CMD-194, 371

- relations................................ CMD-421-- clear................................. CMD-421-- set.................................... CMD-421

- remove deleted records ....... CMD-244- scope........................................ CMD-8- SDF input ............................. CMD-111- SDF output ........................... CMD-147- search

-- by index ........... CMD-180, 305, 307-- conditional ....................... CMD-228-- conditional by index. CMD-305, 307-- continue........................... CMD-144-- index key ......... CMD-180, 305, 307-- locate first ........................ CMD-228-- sequential ........................ CMD-228-- soft seek.......................... CMD-431

- select.................................... CMD-309- shared .................................. CMD-354- sorting .......................... CMD-199, 444

-- ascending........................ CMD-201-- descending...................... CMD-201-- unique...................... CMD-199, 438

- sum numeric fields ............... CMD-453- text input............................... CMD-111- text output ............................ CMD-147- totals to other dbf ................. CMD-455- translation............................. CMD-314- un-delete record................... CMD-275- unique index................. CMD-199, 438- update from other database. CMD-460

Date- century ................................. CMD-320- century digits ........................ CMD-348- epoch ................................... CMD-348- format ................................... CMD-334

Decimals ............................ CMD-338, 360Declaration

- access global C-like typed vars . CMD-192

- array-- local ......................... CMD-219, 222-- private...................... CMD-159, 248

-- public ............................... CMD-261-- static ........................ CMD-446, 448

- class ..................................... CMD-124-- access method ................ CMD-235-- assign method................. CMD-235-- instance ........................... CMD-124-- method ............................ CMD-235

- condition-- case................................. CMD-170-- if..endif............................. CMD-197

- constant................................ CMD-145- database field....................... CMD-178- function......................... CMD-184, 250- global C-like typed vars........ CMD-189- loop

-- for .................................... CMD-182-- while ................................ CMD-172

- memory variable................... CMD-230- parameter list ....................... CMD-246- UDF.............................. CMD-184, 250- variable

-- constant........................... CMD-145-- local ......................... CMD-219, 222-- parameter ........................ CMD-246-- private.............................. CMD-248-- protected ................. CMD-145, 264-- public ............................... CMD-261-- public, protected.............. CMD-264-- static ........................ CMD-446, 448

DECLARE .................................. CMD-159DELETE ..................................... CMD-161DELETE FILE ............................ CMD-162DELETE TAG............................. CMD-163Delimited

- database input...................... CMD-111- database output ................... CMD-147

DESCENDING clause ............... CMD-199DIR............................................. CMD-165Directory

- change ................................. CMD-344- default .......................... CMD-339, 410- listing .................................... CMD-165

DISPLAY.................................... CMD-167DO.............................................. CMD-168DO CASE................................... CMD-170DO WHILE ................................. CMD-172DOS coded source..................... CMD-433Drawing

- bitmap .............................. CMD-37, 60

CMD 479

- box.................................. CMD-23, 104- circle....................................... CMD-33- ellipse ..................................... CMD-35- image ............................... CMD-37, 60- lines................................ CMD-39, 104- polygon................................... CMD-44- rectangle ................................ CMD-46

E

Edit- single line ............................... CMD-64

EJECT........................................ CMD-174ELSE.......................................... CMD-197ELSEIF....................................... CMD-197END.................................... CMD-170, 172END SEQUENCE ...................... CMD-116ENDCASE.................................. CMD-170ENDDO ...................................... CMD-172ENDFOR.................................... CMD-182ENDIF ........................................ CMD-197ENDTEXT .................................. CMD-454EOF

- add record automatically...... CMD-347ERASE....................................... CMD-175Escape key ................................ CMD-350Exception handling............. CMD-116, 241EXCLUSIVE clause ................... CMD-462Execute

- C function ............................. CMD-121Executing

- CMD ............................... CMD-12, 296- external FlagShip program... CMD-298- external program ............ CMD-11, 295- in background................. CMD-12, 296- OpenOffice ........................... CMD-298- shell ................................ CMD-12, 296- StarOffice ............................. CMD-298- WinWord ........................ CMD-13, 298

EXIT ................................... CMD-172, 182EXIT FUNCTION ....................... CMD-184EXIT PROCEDURE................... CMD-250EXPORT instance...................... CMD-126EXPORT INSTANCE................. CMD-176External

- announce ............. CMD-108, 177, 290EXTERNAL ................................ CMD-177External application.................... CMD-295

F

Field- assign................................... CMD-282- modify................................... CMD-282- replace ................................. CMD-282

FIELD......................................... CMD-178File

- alternate output ............ CMD-312, 356- copy...................................... CMD-146- default input directory........... CMD-410- default output directory ........ CMD-339- delete ........................... CMD-162, 175- directory listing ..................... CMD-165- display .................................. CMD-457- large over 2GB ..................... CMD-395- memory

-- restore ............................. CMD-291-- save................................. CMD-301

- move .................................... CMD-280- rename ................................. CMD-280

FIND........................................... CMD-180FlagShip

- library-- commands........................... CMD-7

Flushing- database .............................. CMD-141

FOR............................................ CMD-182Function

- declaration............................ CMD-184- invoking ................................ CMD-186- vs. procedure ....................... CMD-187

FUNCTION ................................ CMD-184Function key

- simulate input ....................... CMD-369

G

Get field- close..................... CMD-131, 132, 133

GLOBAL..................................... CMD-189GLOBAL_EXTERN.................... CMD-192GO.............................................. CMD-194GOTO......................................... CMD-194GUI

- colors.................................... CMD-373GUI mode

- boxes.................................... CMD-377

CMD 480

- character set ........................ CMD-377- cursor type ........................... CMD-374- HTML formatting .................. CMD-381- PC8 semi-graphic ................ CMD-377

H

Help- input ....................................... CMD-70

HIDDEN instance....................... CMD-126HIDDEN INSTANCE.................. CMD-196HTML

- output adaption .................... CMD-425HTML formatting ........................ CMD-381

I

IFCMD-197Image ..................................... CMD-37, 60Index

- ascending............................. CMD-200- close............................. CMD-139, 384- close all ................................ CMD-132- conditional ............................ CMD-199- controlling............................. CMD-406- create ........................... CMD-199, 277- default directory ................... CMD-410- delete tag ............................. CMD-163- descending........................... CMD-200- error handling ....................... CMD-405- open ..................................... CMD-384

-- error handling .................. CMD-405- order..................................... CMD-406- rebuild .................................. CMD-277- search

-- soft seek.......................... CMD-431- skip....................................... CMD-442- sorting

-- ascending........................ CMD-201-- descending...................... CMD-201

- unique .......................... CMD-199, 438INDEX ON.................................. CMD-199INIT FUNCTION......................... CMD-184INIT PROCEDURE .................... CMD-250Inkey( )

- filtering.................................. CMD-351Input

- accept................................... CMD-106

- checkbox ................................ CMD-76- combo box.............................. CMD-80- conditional .............................. CMD-67- console oriented........... CMD-106, 206- cut and paste.................. CMD-71, 271- database .............................. CMD-102- default directory.................... CMD-410- escape key........................... CMD-350- field......................................... CMD-64- filtering.................................. CMD-351- formatted ................................ CMD-64- help ........................................ CMD-70- input ..................................... CMD-206- keyboard buffer .................... CMD-436- listbox ..................................... CMD-82- menus ............................ CMD-48, 232

-- wrap................................. CMD-439- on/off .................................... CMD-387- prompt .................................. CMD-470- pushbutton ............................. CMD-88- radiobutton ....................... CMD-93, 97- radiogroup .............................. CMD-97- READ ................................... CMD-267

-- confirm exit ...................... CMD-330- redirection ............ CMD-240, 243, 389- screen oriented .............. CMD-64, 267

-- array ................................ CMD-102-- database.......................... CMD-102

- simulate key press ............... CMD-210- simulated.............................. CMD-369- single line ............................... CMD-64- validation ............ CMD-66, 67, 70, 270- wait ....................................... CMD-470

INPUT ........................................ CMD-206INSTANCE......................... CMD-126, 208Invoking external application ..... CMD-295ISO....................... CMD-see character setISO coded source ...................... CMD-433

J

JOIN........................................... CMD-209Jump

- exception.............................. CMD-116

K

Keyboard

CMD 481

- escape.................................. CMD-350- filtering.................................. CMD-351- function key .......................... CMD-369- input ............................. CMD-106, 206- input buffer ........................... CMD-436- localizing .............................. CMD-393- on/off .................................... CMD-387- redirection ............ CMD-240, 243, 389

-- restore ............................. CMD-265-- save................................. CMD-265

- simulate input ....................... CMD-369- simulate key press ............... CMD-210- translation............................. CMD-393

KEYBOARD ............................... CMD-210Keyboard buffer

- clear ..................................... CMD-138

L

LABEL EDIT............................... CMD-212Label file

- creating ................................ CMD-212- display .................................. CMD-215- editing................................... CMD-212- print ...................................... CMD-215

LABEL FORM ............................ CMD-215Linker

- announce external CMD-108, 177, 290LIST............................................ CMD-217Listbox

- create ..................................... CMD-82LOCAL ....................................... CMD-219LOCAL..AS ................................ CMD-222Localizing

- keyboard .............................. CMD-393LOCATE..................................... CMD-228Locking

- automatic.............................. CMD-316- multiple records.................... CMD-401- unlock................................... CMD-458

Loop- for ......................................... CMD-182- while ..................................... CMD-172

LOOP ................................. CMD-172, 182

M

MemoEdit( )

- messages............................. CMD-430Memory

- release ......................... CMD-134, 279MEMVAR ................................... CMD-230MENU TO ............................ CMD-48, 232

- message............................... CMD-398- wrap ..................................... CMD-439

METHOD ................................... CMD-235MS-Word.............................. CMD-13, 298

N

NEW clause ............................... CMD-462NEXT.......................................... CMD-182NFS

- handling................................ CMD-403NOTE command .................. CMD-14, 239Number

- output-- decimals .................. CMD-338, 360

O

OEM..................... CMD-see character setON ANY KEY ............................. CMD-240ON ERROR................................ CMD-241ON ESCAPE .............................. CMD-243ON KEY ..................................... CMD-240OpenOffice................................. CMD-298OTHERWISE ............................. CMD-170Output

- bell........................................ CMD-319- box.................................. CMD-23, 104- browsing............................... CMD-102- database

-- screen oriented................ CMD-102- decimals ....................... CMD-338, 360- default directory.................... CMD-339- display text file...................... CMD-457- embedded program text....... CMD-454- extra file.................. CMD-16, 312, 356- formatted ................................ CMD-53

-- labels ............................... CMD-215-- report ............................... CMD-288

- line........................................ CMD-104- printer ..................................... CMD-16

-- GUI/GDI mode................. CMD-376-- on/off ............................... CMD-343

CMD 482

- redirection ...................... CMD-20, 343- screen

-- adaption for HTML .......... CMD-425-- adaption of ROW() .......... CMD-426-- boxes......................... CMD-23, 104-- circle .................................. CMD-33-- clear................... CMD-28, 131, 136-- clear line ............................ CMD-22-- color............. CMD-17, 53, 322, 440-- color in GUI mode ........... CMD-373-- cursor .............................. CMD-333

--- gui type....................... CMD-374-- drawing...... CMD-33, 35, 39, 44, 46-- ellipse ................................ CMD-35-- lines ........................... CMD-39, 104-- on/off ....................... CMD-331, 343-- pixel coordinates ............. CMD-412-- polygon.............................. CMD-44-- prompt ....................... CMD-48, 232-- rectangle ........................... CMD-46-- refresh ............................. CMD-276-- restore ............................. CMD-293-- sequential .......................... CMD-16-- store ................................ CMD-303-- text..................................... CMD-53

- screen oriented-- array ................................ CMD-102-- database ......................... CMD-102

- to console window.................. CMD-20- to stderr .................................. CMD-20- unprintable characters ......... CMD-408- zero byte .............................. CMD-441

P

PACK ......................................... CMD-244Parameter passing............. CMD-186, 252PARAMETERS .......... CMD-184, 246, 250PC8 ...................... CMD-see character setPixel coordinates ....................... CMD-412POP KEY ................................... CMD-265Print

- embedded program text....... CMD-454Printer

- margin .................................. CMD-396- new page.............................. CMD-346- new page.............................. CMD-174- on/off ............................ CMD-343, 413

- redirection ............................ CMD-413PRIVATE.................................... CMD-248Procedure

- automatic.............................. CMD-252- compiler instruction .............. CMD-420- declaration............................ CMD-250- files....................................... CMD-420- invoking ................................ CMD-168- vs. function ........................... CMD-253

PROCEDURE............................ CMD-250Program

- character set ........................ CMD-433- exception handling ............... CMD-116- exit................................ CMD-123, 266- terminate ...................... CMD-123, 266

PROTECT instance ................... CMD-126PROTECT INSTANCE .............. CMD-255PROTECT PUBLIC.................... CMD-264PROTOTYPE............................. CMD-256PROTOTYPE ACCESS............. CMD-235PROTOTYPE ASSIGN .............. CMD-235PROTOTYPE CLASS................ CMD-124PROTOTYPE METHOD ............ CMD-235PUBLIC ...................................... CMD-261PUSH KEY................................. CMD-265Pushbutton

- create ..................................... CMD-88

Q

QUIT .................................. CMD-123, 266

R

Radiobutton- create ..................................... CMD-93- group ...................................... CMD-97

READ ................................... CMD-64, 267- align fields ............................ CMD-372- color selection ...................... CMD-388- confirm exit........................... CMD-330- messages............................. CMD-430- termination by escape.......... CMD-350

READONLY clause.................... CMD-462RECALL ..................................... CMD-275Record

- delete ................................... CMD-161- delete all............................... CMD-473

CMD 483

- deleted-- visible .............................. CMD-340

- display .......................... CMD-167, 217- filtering.................................. CMD-358- locking

-- automatic......................... CMD-316-- unlock .............................. CMD-458

- modify................................... CMD-282- movement .................... CMD-194, 442

-- first........................... CMD-194, 371-- last................................... CMD-194

- new....................................... CMD-110-- automatically ................... CMD-347

- remove deleted .................... CMD-244- replace ................................. CMD-282- un-delete .............................. CMD-275

RECOVER ................................. CMD-116Redirection

- output ..................................... CMD-20REFRESH.................................. CMD-276REINDEX ................................... CMD-277Relation of databases ................ CMD-421RELEASE .................................. CMD-279Remove file ........................ CMD-162, 175RENAME.................................... CMD-280Rename file................................ CMD-280REPLACE .................................. CMD-282REPORT EDIT........................... CMD-286Report file

- creating ................................ CMD-286- display .................................. CMD-288- editing................................... CMD-286- print ...................................... CMD-288

REPORT FORM ........................ CMD-288REQUEST.................................. CMD-290RESTORE FROM ...................... CMD-291RESTORE SCREEN.................. CMD-293RETURN .................... CMD-184, 250, 294ROW( )

- adaption ............................... CMD-426RUN ........................................... CMD-295

S

SAVE SCREEN ......................... CMD-303SAVE TO ................................... CMD-301Screen

- clear ....................... CMD-28, 131, 136

- cursor ........................... CMD-333, 374- output

-- on/off ............................... CMD-331- restore .................................. CMD-293- store ..................................... CMD-303

Screen outputfrom external applic.............. CMD-296

SDF- database input...................... CMD-111- database output ................... CMD-147

SEEK.......................................... CMD-305SEEK EVAL ............................... CMD-307SELECT ..................................... CMD-309SET ALTERNATE...................... CMD-312SET ANSI................................... CMD-314SET AUTOLOCK ....................... CMD-316SET BELL .................................. CMD-319SET CENTURY.......................... CMD-320SET CHARSET.................. CMD-321, 393SET COLOR or COLOUR ......... CMD-322SET CONFIRM .......................... CMD-330SET CONSOLE ......................... CMD-331SET COORDINATE................... CMD-437SET CURSOR ........................... CMD-333SET DATE ................................. CMD-334SET DBREAD ............................ CMD-336SET DBWRITE .......................... CMD-336SET DECIMALS......................... CMD-338SET DEFAULT........................... CMD-339SET DELETED .......................... CMD-340SET DELIMITERS ..................... CMD-341SET DEVICE.............................. CMD-343SET DIRECTORY...................... CMD-344SET EJECT................................ CMD-346SET EOFAPPEND..................... CMD-347SET EPOCH .............................. CMD-348SET ESCAPE ............................ CMD-350SET EVENTMASK..................... CMD-351SET EXACT ............................... CMD-352SET EXCLUSIVE....................... CMD-354SET EXTRA ............................... CMD-356SET FILTER............................... CMD-358SET FIXED ................................ CMD-360SET FORMAT............................ CMD-367SET FUNCTION ........................ CMD-369SET GOTOP.............................. CMD-371SET GUIALIGN.......................... CMD-372SET GUICOLORS ..................... CMD-373SET GUICURSOR..................... CMD-374

CMD 484

SET GUIPRINTER..................... CMD-376SET GUITRANSL ...................... CMD-377SET HTMLTEXT........................ CMD-381SET INDEX ................................ CMD-384SET INPUT ................................ CMD-387SET INTENSITY ........................ CMD-388SET KEY.................................... CMD-389SET KEYTRANSL ..................... CMD-393SET LARGEFILE ....................... CMD-395SET LOCK ................................. CMD-318SET MARGIN............................. CMD-396SET MESSAGE ......................... CMD-398SET MULTIBYTE....................... CMD-399SET MULTILOCKS.................... CMD-401SET NFS.................................... CMD-403SET OPENERROR.................... CMD-405SET ORDER.............................. CMD-406SET OUTMODE......................... CMD-408SET PATH ................................. CMD-410SET PIXEL................................. CMD-412SET PRINTER ........................... CMD-413SET PROCEDURE.................... CMD-420SET RELATION......................... CMD-421SET REPROCESS .................... CMD-318SET ROWADAPT ...................... CMD-425SET ROWALIGN ....................... CMD-426SET SCOREBOARD ................. CMD-430SET SCRCOMPRESS............... CMD-429SET SOFTSEEK........................ CMD-431SET SOURCE............................ CMD-433SET TYPEAHEAD ..................... CMD-436SET UNIQUE............................. CMD-438SET UNIT................................... CMD-437SET WRAP ................................ CMD-439SET ZEROBYTEOUT................ CMD-441SETENHANCED........................ CMD-440SETSTANDARD ........................ CMD-440SETUNSELECTED.................... CMD-440SHARED clause......................... CMD-462SKIP........................................... CMD-442SOFTSEEK................................ CMD-305SORT ......................................... CMD-444Sorting

- ascending............................. CMD-201- descending........................... CMD-201

Source- autolock.prg.......................... CMD-318- DOS/OEM vs. ISO/ANSI...... CMD-433

StarOffice ................................... CMD-298

STATIC ...................................... CMD-446STATIC CLASS ......................... CMD-124STATIC FUNCTION................... CMD-184STATIC PROCEDURE .............. CMD-250STATIC..AS ............................... CMD-448std.fh file....................................... CMD-10Stderr

- output ..................................... CMD-20- redirection .............................. CMD-20

STORE....................................... CMD-451String

- comparison-- influencing ....................... CMD-352

SUM ........................................... CMD-453

T

TEXT.......................................... CMD-454TOTAL ....................................... CMD-455Translation

- character set ........................ CMD-377Trigger

- UDF-- at key press..................... CMD-389

TYPE.......................................... CMD-457

U

UDF............................................ CMD-184UDP ........................................... CMD-250UNIQUE clause.......................... CMD-199Unique index ...................... CMD-199, 438Units ........................................... CMD-437UNLOCK .................................... CMD-458Unprintable characters............... CMD-408UPDATE .................................... CMD-460USE............................................ CMD-462

V

Variable- assigning .............................. CMD-451- local .............................. CMD-219, 222- modifying.............................. CMD-451- parameter............................. CMD-246- private .................................. CMD-248- protected ...................... CMD-145, 264

CMD 485

- public .................................... CMD-261- public, protected................... CMD-264- release ......................... CMD-134, 279- restore from file .................... CMD-291- save to file ............................ CMD-301- static ............................. CMD-446, 448- typed local ............................ CMD-222- typed static ........................... CMD-448

W

WAIT .......................................... CMD-470WHILE........................................ CMD-172

WinWord .............................. CMD-13, 298Work area

- close..................................... CMD-462- new............................... CMD-309, 462- open ..................................... CMD-462- select .................................... CMD-309

Z

ZAP ............................................ CMD-473Zero byte

- displaying ..................... CMD-408, 441

CMD 486

CMD 487

ty

CMD 488

The whole FlagShip 7 manual consist of following · PDF fileCMD 8 [item] The entry is...

Documents

Transcript of The whole FlagShip 7 manual consist of following · PDF fileCMD 8 [item] The entry is...