nanoBase user's manual
##INDEX## ================================================================ <Index> <Copyright> <Introduction> <Dos xBase> <.DBF Files> <Index Files> <Relations> <Composition> <How to use nB> <Status Line> <The Dot Line> <The menu system> <Menu File> <File - New .Dbf> <File - Modify .Dbf structure> <File - Open .Dbf> <File - New .Ntx / New Tag> <File - Open Index> <File - Select> <File - Display structure> <File - Close active Alias> <File - Close all Aliases> <File - Order List Rebuild> <File - Order Set Focus> <File - Order List Clear> <File - Set Relation> <File - Clear Relation> <File - Show actual RDD default> <File - Set default RDD> <Menu Edit> <Edit - View> <Edit - Edit/Browse> <Edit - Replace> <Edit - Recall> <Edit - Delete> <Edit - Pack> <Menu Report> <Report - New Label> <Report - Modify Label> <Report - Label Form> <Report - New Report> <Report - Modify Report> <Report - Report Form> <Report - Create/Modify/Print Text> <Menu Htf> <Htf - Open Help Text File> <Htf - New Help Text File> <Htf - New HTML File> <Menu Macro> <Macro - Start Recording> <Macro - Save Recording> <Macro - Erase Recording> <Macro - Edit Recording> <Macro - Macro compilation> <Macro - Load + Execute Macro> <Menu Info> <Info - About> <Info - Manual browse> <Info - [F1] help> <Info - [F3] Alias info> <Info - [F5] Set output to> <Info - [F8] Dot Line Calculator> <Menu Doc> <Doc - New> <Doc - Open> <Doc - Save> <Doc - Save as> <Doc - Set output to> <Doc - Print as it is> <Doc - Print with RPT() once> <Doc - Print with RPT() std> <Doc - Exit DOC()> <The Text Editor Doc()> <The Help Text File> <Macro> <Macro statements> <Procedure> <Do Procedure> <Begin Sequence> <Do Case> <While> <If> <Variable declaration> <Macro structure> <Macro comments> <Macro long lines split> <The macro recorder> <Data Types> <Character> <Memo> <Date> <Numeric> <Logical> <NIL> <Array> <Code Block> <Operators> <Delimiters> <Code Blocks> <Standard functions> <AADD()> <ABS()> <ACLONE()> <ACOPY()> <ADEL()> <ALERT()> <ALIAS()> <AFILL()> <AINS()> <ALERT()> <ALIAS()> <ALLTRIM()> <ARRAY()> <ASC()> <ASCAN()> <ASIZE()> <ASORT()> <AT()> <ATAIL()> <BIN2I()> <BIN2L()> <BIN2W()> <BOF()> <CDOW()> <CHR()> <CMONTH()> <COL()> <COLORSELECT()> <CTOD()> <CURDIR()> <DATE()> <DAY()> <DBAPPEND()> <DBCLEARFILTER()> <DBCLEARINDEX()> <DBCLEARRELATION()> <DBCLOSEALL()> <DBCLOSEAREA()> <DBCOMMIT()> <DBCOMMITALL()> <DBCREATE()> <DBCREATEINDEX()> <DBDELETE()> <DBEVAL()> <DBFILTER()> <DBGOBOTTOM()> <DBGOTO()> <DBGOTOP()> <DBRECALL()> <DBREINDEX()> <DBRELATION()> <DBRLOCK()> <DBRLOCKLIST()> <DBRSELECT()> <DBRUNLOCK()> <DBSEEK()> <DBSELECTAREA()> <DBSETDRIVER()> <DBSETFILTER()> <DBSETINDEX()> <DBSETORDER()> <DBSETRELATION()> <DBSKIP()> <DBSTRUCT()> <DBUNLOCK()> <DBUNLOCKALL()> <DBUSEAREA()> <DESCEND()> <DEVOUT()> <DEVOUTPICT()> <DEVPOS()> <DIRECTORY()> <DISKSPACE()> <DISPBOX()> <DISPOUT()> <DOW()> <DTOC()> <DTOS()> <EMPTY()> <EOF()> <EVAL()> <EXP()> <FCLOSE()> <FCOUNT()> <FCREATE()> <FERASE()> <FERROR()> <FIELDBLOCk()> <FIELDGET()> <FIELDNAME()> <FIELDPOS()> <FIELDPUT()> <FIELDWBLOCK()> <FILE()> <FLOCK()> <FOPEN()> <FOUND()> <FREAD()> <FREADSTR()> <FRENAME()> <FSEEK()> <FWRITE()> <GETENV()> <HARDCR()> <HEADER()> <I2BIN()> <IF()> <INDEXEXT()> <INDEXKEY()> <INDEXORD()> <INKEY()> <INT()> <ISALPHA()> <ISCOLOR()> <ISDIGIT()> <ISLOWER()> <ISPRINTER()> <ISUPPER()> <L2BIN()> <LASTKEY()> <LASTREC()> <LEFT()> <LEN()> <LOG()> <LOWER()> <LTRIM()> <LUPDATE()> <MAX()> <MAXCOL()> <MAXROW()> <MEMOEDIT()> <MEMOLINE()> <MEMOREAD()> <MEMORY()> <MEMOTRAN()> <MEMOWRIT()> <MEMVARBLOCK()> <MIN()> <MLCOUNT()> <MLCTOPOS()> <MLPOS()> <MONTH()> <MPOSTOLC()> <NETERR()> <NEXTKEY()> <NOSNOW()> <ORDBAGEXT()> <ORDBAGNAME()> <ORDCREATE()> <ORDDESTROY()> <ORDFOR()> <ORDKEY()> <ORDLISTADD()> <ORDLISTCLEAR()> <ORDLISTREBUILD()> <ORDNAME()> <ORDNUMBER()> <ORDSETFOCUS()> <OS()> <OUTERR()> <OUTSTD()> <PAD?()> <PCOL()> <PROW()> <QOUT()> <RAT()> <RDDLIST()> <RDDNAME()> <RDDSETDEFAULT()> <READINSERT()> <READMODAL()> <READVAR()> <RECNO()> <RECSIZE()> <REPLICATE()> <RIGHT()> <RLOCK()> <ROUND()> <ROW()> <RTRIM()> <SAVESCREEN()> <SCROLL()> <SECONDS()> <SELECT()> <SET()> <SETBLINK()> <SETCANCEL()> <SETCOLOR()> <SETCURSOR()> <SETKEY()> <SETMODE()> <SETPOS()> <SETPRC()> <SOUNDEX()> <SPACE()> <SQRT()> <STR()> <STRTRAN()> <STUFF()> <SUBSTR()> <TIME()> <TONE()> <TRANSFORM()> <TYPE()> <UPDATED()> <UPPER()> <USED()> <VAL()> <VALTYPE()> <YEAR()> <nB functions> <ACCEPT()> <ACHOICE()> <ACHOICEWINDOW()> <ALERTBOX()> <ATB()> <BUTTON()> <BCOMPILE()> <COLORARRAY()> <COORDINATE()> <COPYFILE()> <DBAPP()> <DBCLOSE()> <DBCONTINUE()> <DBCOPY()> <DBCOPYSTRUCT()> <DBCOPYXSTRUCT()> <DBDELIM()> <DBISTATUS()> <DBISTRUCTURE()> <DBJOIN()> <DBLABELFORM()> <DBLIST()> <DBLOCATE()> <DBOLDCREATE()> <DBPACK()> <DBSDF()> <DBSORT()> <DBTOTAL()> <DBUPDATE()> <DBZAP()> <DISPBOXCOLOR()> <DISPBOXSHADOW()> <DIR()> <DOC()> <DOTLINE()> <DTEMONTH()> <DTEWEEK()> <EX()> <GET()> <GVADD()> <GVDEFAULT()> <GVFILEDIR()> <GVFILEEXIST()> <GVFILEEXTENTION()> <GVSUBST()> <HTF()> <ISFILE()> <ISWILD()> <ISMEMVAR()> <ISCONSOLEON()> <ISPRINTERON()> <KEYBOARD()> <LISTWINDOW()> <MEMOWINDOW()> <MEMPUBLIC()> <MEMRELEASE()> <MEMRESTORE()> <MEMSAVE()> <MENUPROMPT()> <MENUTO()> <MESSAGELINE()> <MOUSESCRSAVE()> <MOUSESCRRESTORE()> <PICCHRMAX()> <QUIT()> <READ()> <RF()> <RPT()> <RPTMANY()> <RPTTRANSLATE()> <RUN()> <SAY()> <SETCOLORSTANDARD()> <SETFUNCTION()> <SETMOUSE()> <SETOUTPUT()> <SETRPTEJECT()> <SETRPTLINES()> <SETVERB()> <SETVERB("EXACT")> <SETVERB("FIXED")> <SETVERB("DECIMALS")> <SETVERB("DATEFORMAT")> <SETVERB("EPOCH")> <SETVERB("PATH")> <SETVERB("DEFAULT")> <SETVERB("EXCLUSIVE")> <SETVERB("SOFTSEEK")> <SETVERB("UNIQUE")> <SETVERB("DELETED")> <SETVERB("CANCEL")> <SETVERB("TYPEAHEAD")> <SETVERB("COLOR")> <SETVERB("CURSOR")> <SETVERB("CONSOLE")> <SETVERB("ALTERNATE")> <SETVERB("ALTFILE")> <SETVERB("DEVICE")> <SETVERB("EXTRA")> <SETVERB("EXTRAFILE")> <SETVERB("PRINTER")> <SETVERB("PRINTFILE")> <SETVERB("MARGIN")> <SETVERB("BELL")> <SETVERB("CONFIRM")> <SETVERB("ESCAPE")> <SETVERB("INSERT")> <SETVERB("EXIT")> <SETVERB("INTENSITY")> <SETVERB("SCOREBOARD")> <SETVERB("DELIMITERS")> <SETVERB("DELIMCHARS")> <SETVERB("WRAP")> <SETVERB("MESSAGE")> <SETVERB("MCENTER")> <STRADDEXTENTION()> <STRCUTEXTENTION()> <STRDRIVE()> <STREXTENTION()> <STRFILE()> <STRFILEFIND()> <STRGETLEN()> <STRLISTASARRAY()> <STROCCURS()> <STRPARENT()> <STRPATH()> <STRTEMPPATH()> <STRXTOSTRING()> <TB()> <TEXT()> <TGLINSERT()> <TIMEX2N()> <TIMEN2H()> <TIMEN2M()> <TIMEN2S()> <TRUESETKEY()> <WAITFILEEVAL()> <WAITFOR()> <WAITPROGRESS()> <Normal command substitution> <?> <@BOX> <@TO> <@GET> <@SAY> <APPEND> <CLEAR> <CLOSE> <COMMIT> <COUNT> <DEFAULT> <DELETE> <EJECT> <ERASE> <FIND> <GO> <INDEX ON> <READ> <RECALL> <REINDEX> <RENAME> <REPLACE> <RESTORE> <SAVE> <SEEK> <SELECT> <SET> <SKIP> <STORE> <SUM> <UNLOCK> <USE> <nB command substitution functions> <GET> <SAY> <APPEND FROM> <CONTINUE> <COPY> <CREATE> <JOIN> <KEYBOARD> <LABEL FORM> <LIST> <LOCATE> <PACK> <PUBLIC> <QUIT> <RELEASE> <REPORT FORM> <RESTORE FROM> <RUN> <SAVE TO> <SET FUNCTION> <SORT> <TOTAL> <UPDATE> <ZAP> <RPT - the nB print function> <RPT - memvars and fields> <RPT - commands> <*COMMAND> <*DBSKIP> <*FOOT> <*IF> <*INSERT> <*HEAD> <*LPP> <*NEED> <*PA> <*REM> <*WHILE> <RPT - examples> <Page definition> <Header and footer> <Code insertion> <How can I> <create a UDF function> <create a big code block> <create a virus> <protect myself from viruses> <The source files> <Aknoledgments> <Known problems> <nB history> <How to contact the author> ##COPYRIGHT## ================================================================ nB (nano Base) Copyright (c) 1996-1997 Daniele Giacomini This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. Send your comments, suggestions, bug reports and english text corrections to: Daniele Giacomini Via Turati, 15 I-31100 Treviso Italy daniele@tv.shineline.it <Index> ##INTRODUCTION## ================================================================ First of all, I am sorry for my bad English. nB ("nano Base": "n" = "nano" = 10**(-9) = "very little") is a little DOS xBase written in CA-Clipper 5.2 that can help to access .DBF file created with different standards. nB can access files created with Fox Pro 2, dBASE IV, dBASE III, dBASE III PLUS and CA-Clipper. nB is: * a dot command interpreter, * a menu driven xBase, * a xBase program interpreter, nB may be useful because: * it is Freeware and contains the source code; * it is a all in one utility; * with nB, a commercial compiler is no more needed to make simple programs: * it can compile some simple xBase programs and then execute them, * may functions are added to the standard CA-Clipper language. nB is compiled in two versions: a small one to be used on old computers (x86 with 640K ram), and a second one to be used on better computers, at least 286 (or better) with 2M ram. nB has many level of use. If you want to make complex programs with nB, you need to know how the CA-Clipper programming language works. This manual is already very big, but it isn't enough to understand all the possibility of nB. A good book about CA- Clipper will help you in the right direction. <Index> ##DOS XBASE## ================================================================ This chapter (Dos xBase) is a breaf description of the functionality of a tipical Dos xBase and can be ignored form the people who well know how work Clipper and/or dBase. The first purpose of a xBase program is to handle data inside a .DBF file. These files may be indexed with the help of index files and more .DBF files may be linked with a relation to obtain something like a relational database. ##.DBF FILES## ---------------------------------------------------------------- .DBF files are files organised in a table structure: ---------------------------- | field1 | field2 | field3 | record1 ---------------------------- | | | | record2 ---------------------------- | | | | record3 ---------------------------- | | | | record4 ---------------------------- | | | | record5 ---------------------------- | | | | record6 ---------------------------- The lines of this table are records and the columns are fields. Records are numbered starting from the first that is number 1. Columns are defined as fields and fields are distinguished by name and these names are saved inside the .DBF file. Every field (column) can contain only one specified kind of data with a specified dimention: * C character originally the maximum dimension was 254 characters, minimum is 1; * N numeric a numeric field that can contain also sign and decimal values; * D date a field dedicated to date information; * L logic a filed that may contain only "T" for True or "F" for False used as a boolean variable; * M memo a character field with no predefined dimension, not allocated directly inside the .DBF, but inside a .DBT file, automatically linked. No other field type is available for a typical xBase .DBF file. To access the data contained inside a .DBF file the following list of action may be followed: * Open a .DBF file inside the current area, where these areas are something like file handlers. <DBSELECTAREA()> <DBUSEAREA()> * After the .DBF file is opened, it referenced only by the ALIAS name that usually correspond to the original filename without extention. <ALIAS()> * Move the record pointer to the desired location. <DBGOTO()> * Lock the current record to avoid access from other users. <DBRLOCK()> * Do some editing with the data contained inside the current record using the field names like they were variables. * Relese the lock. <DBRUNLOCK()> * Move the record pointer to another desired location. <DBGOTO()> * Lock the current record to avoid access from other users. <DBRLOCK()> * [...] * Close the ALIAS. <DBCLOSEAREA()> Before you go further, you have to understand that: * A .DBF file is opened using a free WORK AREA that may be associated to the concept of the file handler. * The .DBF file is opened with a ALIAS name that permit to open the same .DBF file more times when using different ALIAS names * After the .DBF file is opened, we don't speek any more of file, but ALIAS. * If the WORK AREA "n" is used from the ALIAS "myAlias", speeking of WORK AREA "n" or of ALIAS "myAlias" is the same thing. <DBSELECTAREA()> <SELECT()> ##INDEX FILES## ---------------------------------------------------------------- .DBF files are organised with record number, that is, you can reach a specific record and not a specific information unless that you scan record by record. To obtain to "see" a .DBF file somehow logically ordered (when phisically it is not), index files are used. A index file, also called INDEX BAG, is a file that contains one or more indexes Indexes are rules by which a .DBF file may be seen ordered. A typical index file may contain only one index. A index file may have the following extention: .NDX single index dBase III and dBase III plus; .NTX single index Clipper; .MBX multiple index dBase IV; .CDX multiple index FoxPro. Every index file may be used only in association with the .DBF for what it was made. The problem is that normally there is no way to avoid errors when the user try to associate the right .DBF file with the wrong index. To access the data contained inside a .DBF file the following list of action may be followed: * Open a .DBF file. <DBUSEAREA()> * Open a index file. <ORDLISTADD()> * Select a particular order. <ORDSETFOCUS()> * Search for a key or move the record pointer on a different way. <DBSEEK()> <FOUND()> <DBGOTOP()> <DBGOBOTTOM()> <DBSKIP()> <BOF()> <EOF()> * Lock the current record to avoid access from other users. <DBRLOCK()> * Do some editing with the data contained inside the current record using the field names like they were variables. * Relese the lock. <DBRUNLOCK()> * Move the record pointer to another desired location. * Lock the current record to avoid access from other users. * [...] * Close the ALIAS. <DBCLOSEAREA()> Before you go further, you have to understand that: * As orders are contained inside a INDEX BAG file phisically distinguished form the .DBF file, it may happen that a .DBF file is wrongly opened and edited without the index. In this case, the INDEX BAG is not updated and when the INDEX BAG will be opened, the records contained inside the .DBF file may not correspond. * For the same reason, an inproper program termination may result in an uncomplete data update. That is: .DBF file may be allright, INDEG BAG not. * This is why xBase programs are "weak" relational databases or they are not relational databases at all. * When troubles occurs, indexes must be rebuild. <ORDLISTREBUILD()> ##RELATIONS## ---------------------------------------------------------------- Many .DBF files with indexes may be opened simultaneously. Data contained inside more .DBF files may be somehow connected together. See the example. ------------------------------------------ | Date | Time IN | Time OUT | Employee # | ------------------------------------------ | xxxx | xxxxxxx | xxxxxxxx | 01 | -------->| ------------------------------------------ | | yyyy | yyyyyyy | yyyyyyyy | 02 | | ------------------------------------------ | | zzzz | zzzzzzz | zzzzzzzz | 01 | -------->| ------------------------------------------ | [...] | | |<-----------------------------------------| | | | ---------------------------------------- | | Employee # | Name | Address |.....| | ---------------------------------------- |------->| 01 | aaaaaaa | aaaaaaa |.....| ---------------------------------------- | 02 | bbbbbbb | bbbbbbb |.....| ---------------------------------------- | 03 | ccccccc | ccccccc |.....| ---------------------------------------- The first .DBF file contains some data that refers to an Employee number that may appear repeated on more records. Emplyee informations are stored inside another .DBF file that contains only one record for every employee. Establising a relation from the first .DBF file to the second, moving the record pointer of the first .DBF file, that is the first ALIAS, the record pointer of the second, the CHILD ALIAS, is moved automatically to the record containing the right data. The relation is an expression that should result in a number if the CHILD Alias is opened without index, or in a valid index key if the CHILD Alias is opened with an index. To relate two .DBF files the following list of action may be followed: * Open the first .DBF file. <DBUSEAREA()> * Open a index file for the first Alias. <ORDLISTADD()> * Select a particular order. <ORDSETFOCUS()> * Open the second .DBF file. <DBUSEAREA()> * Open a index file for the second Alias. <ORDLISTADD()> * Select a particular order. <ORDSETFOCUS()> * Select the first Alias. <DBSELECTAREA()> * Define a relation form the first Alias and the second Alias: the CHILD alias. <DBSETRELATION()> <DBRELATION()> * Search for a key or move the record pointer of the first Alias (don't care about the Child Alias). <DBSEEK()> <FOUND()> <DBGOTOP()> <DBGOBOTTOM()> <DBSKIP()> <BOF()> <EOF()> * Lock the current record to avoid access from other users. <DBRLOCK()> * If data contained inside the Child Alias should be edited (usually it doesn't happen), lock the current record of the Child Alias. * Do some editing with the data contained inside the current record using the field names like they were variables. * Relese the lock (also with the Child Alias if a lock was made). <DBRUNLOCK()> * Move the record pointer to another desired location. * Lock the current record to avoid access from other users. * [...] * Release the relation. <DBCLEARRELATION()> * Close the Child Alias. <DBCLOSEAREA()> * Close the first Alias. <DBCLOSEAREA()> As may be seen, relations are not saved inside files, but are obtained with lines of code. ##COMPOSITION## ================================================================ nB is composed from the following files, where "xx" is the the version code. NBASExx1.ZIP EXEs for small PCs NBASExx2.ZIP Runtime EXEs for small PCs NBASExx3.ZIP EXEs for 286 with 2M+ NBASExx4.ZIP DOCs NBASExx5.ZIP EXAMPLEs NBASExx6.ZIP SRCs for version 96.06.16 NBASExx7.ZIP SRCs for the current version Every archive file contains: COPYING.TXT GNU General Public Licence version 2 in Dos text format. README.TXT the readme file. FILE_ID.DIZ definition. The file NBASExx1.ZIP contains also the following files. NB.EXE the executable program for DBFNTX and DBFNDX files, linked with RTLINK. NB.HLP this manual in "Help Text File" format. The file NBASExx2.ZIP contains also the following files. NB.EXE the run-time to execute macro programs for DBFNTX and DBFNDX files handling, linked with RTLINK. The file NBASExx3.ZIP contains also the following files. NB.EXE the executable program for DBFCDX, DBFMDX, DBFNDX and DBFNTX files, linked with EXOSPACE. NB.HLP this manual in "Help Text File" format. The file NBASExx4.ZIP contains also the following files. NB.PRN this manual in printed text format. NB.RTF this manual in RTF format. NB.TXT this manual in ASCII text format. NB.HTM this manual in HTML format. The file NBASExx5.ZIP contains also the following files. _ADDRESS.DBF an example database file. _ADDRESS.NTX index file associated to _ADDRESS.DBF. _ADDRESS.LBL a label form file used to print data contained inside _ADDRESS.DBF. _ADDRESS.FRM a report form file used to print data contained inside _ADDRESS.DBF. _ADDRESS.RPT a RPT text file used to print data contained inside _ADDRESS.DBF. _MAINMNU.& a macro program source example of a menu that executes some others macro programs. This example is made to demonstrate how nB can execute directly a soruce code without compiling it. This example is made only to taste it: it is very slow and only a speady machine can give the idea of it. 0MAINMNU.& a macro program source example of a menu that executes some others macro programs. It is the same as _MAINMNU.& but it is made to start the execution of the compliled macros. 0MAINMNU.NB compiled macro program 0MAINMNU.& 0MAINMNU.BAT a batch file to show how to run the execution of 0MAINMNU.NB 1ADDRESS.& a macro program source example for handling a .DBF file containig addresses in various ways. 1ADDRESS.NB compiled macro 1ADDRESS.&. 2ADDRESS.& a macro program source example for handling a .DBF file containig addresses in various ways: a little bit more complicated than 1ADDRESS.&. 2ADDRESS.NB compiled macro 2ADDRESS.&. 3ADDRESS.& a macro program source example for handling a .DBF file containig addresses in various ways: a little bit more complicated than 2ADDRESS.&. 3ADDRESS.NB compiled macro 3ADDRESS.&. 4ADDRESS.& a macro program source example for handling a .DBF file containig addresses in various ways: a little bit more complicated than 3ADDRESS.&. 4ADDRESS.NB compiled macro 4ADDRESS.&. ABIORITM.& a macro program source example for calculating the personal bio wave. ABIORITM.NB compiled macro ABIORITM.&. _STUDENT.DBF a .DBF file used inside the BSTUDENT macro example. _STUDENT.NTX index file used for _STUDENT.DBF. _STUDSTD.DBF a .DBF file used inside the BSTUDENT macro example. _STUDENT.RPT a RPT text file used to print data contained inside _STUDENT.DBF. _STUDSTD.RPT a RPT text file used to print data contained inside _STUDSTD.DBF. BSTUDENT.& a macro program source example for students evaluation: a description about students is obtained linking other standard descriptions. BSTUDENT.NB compiled macro BSTUDENT.&. CBATMAKE.& a macro program source example to generate a batch file to be used to back up an entire hard disk. CBATMAKE.NB compiled macro CBATMAKE.&. BROWSE.& a macro program source example to start an automatic browse. BROWSE.NB compiled macro BROWSE.&. BROWSE.BAT batch file to start a .DBF browse with the BROWSE macro program. MENU.& a macro program source example for a Dos menu. MENU.NB compiled macro MENU.&. MENU.BAT batch file to use the MENU macro. The file NBASExx6.ZIP contains also the following files: source code for the version 96.06.16. NB.PRG the main source file for version 96.06.16. NB_REQ.PRG the source file conatinig links to all the standard functions. NB.LNK link file for compilation. NB_NRMAL.RMK rmake file to compile with RTLink. NB_EXOSP.RMK rmake file to compile with Exospace. NB_RUNTI.RMK rmake file to compile with RTLink defining RUNTIME to obtain a small nB runtime version. MACRO.LNK link file to compile and link a macro. MACRO.RMK rmake file to compile and link a macro. The file NBASExx7.ZIP contains also the following files: source code for the current version. NB.PRG the main source file. REQUEST.PRG the source file conatinig links to all the CA- Clipper functions. STANDARD.PRG the source file for standard functions. EXTRA.PRG the source file for other standard functions. STANDARD.CH general include file that subtitues all include file normally used for normal Clipper compilations. NB.CH include file specific for nB. NB.LNK link file for compilation. NB_RUNTI.LNK link file for runtime compilation. NB_NRMAL.RMK rmake file to compile with RTLink. NB_EXOSP.RMK rmake file to compile with Exospace. NB_RUNTI.RMK rmake file to compile with RTLink defining RUNTIME to obtain a small nB runtime version. MACRO.CH include file to compile and link a macro. MACRO.LNK link file to compile and link a macro. MACRO.RMK rmake file to compile and link a macro. CLIPMOUSE.ZIP a simple Freeware library for mouse support under Clipper (c) 1992 Martin Brousseau. <Index> ##HOW TO USE nB## ================================================================ nB normal syntax is: nB [<nB_parameters>] [<macro_filename>] [<macro_parameters>] To run nB, just type the word "NB" and press [Enter] to execute. It will run in command mode, this means that it will look like an old xBASE command prompt. To run the program as a macro interpreter, type the word NB followed from the macro file name with extention (no default extention is supposed). If parameters are given, after the macro file name, these will be available inside the public variables: c_Par1, c_Par2, ..., c_Par9. c_Par0 will contain the macro file name (see the macro file BROWSE.&). nB will terminate execution when the macro terminates. These parameters are available for nB: -c Suppress the copyright notice. It is usefull when using nB for macro interpretation. -w Suppress the "Wait-Wheel" if not desired. It is the "Wheel" that appears at top-left when a macro is interpreted or other long elaborarions are executed. -? Shows a short help. nB macro "compilation" syntax is: nB -m <source_macro_filename> [<destination_macro_filename>] With the -m parameter, nB "compiles" the ascii <source_macro_filename> into <destination_macro_filename>. <Index> ##STATUS LINE## ================================================================ nB shows a "status line" at the top of the screen when the nB command prompt or the menu system is active. It shows some important informations. | |DBFNTX ||*| 1|ADDRESS | 1/ 4|ADDRESS.NTX | | | | | | | | | | | | | | | | | | | | | Last record (7). | | | | | | | | | | | Record pointer position (6). | | | | | | | | | Active Alias (5). | | | | | | | Current Work Area (4) | | | | | Deleted record appearence (3) | | | Actual default database driver (2). | Macro recorder indicator (1). | 1/ 4|ADDRESS.NTX | 1|ADDRESS | | | | | | | | | Order Tag Name (10) | | | Order number (9) | Order Bag name (8) (1) This is the place for the macro recorder indicator. The symbol used is "&". BLANK - means that the macro recorder is OFF; & blink - means that the macro recorder is ON; & - means that the macro recorder is PAUSED. (2) The name of the default database driver. It is not necessarily the database driver for the active Alias; it is only the database driver that will be used for the next open/create operation. (3) An asterisk (*) at this position indicates that SET DELETED is OFF. This means that deleted records are not filtered. When a BLANK is in this place, SET DELETED is ON, so that deleted records are filtered. (4) The active work area number, that is, the area of the active Alias. (5) The active Alias name. Note that the Alias name is not necessarily equal to the .DBF file name. (6) The actual record pointer position for the active Alias. (7) The number of records contained inside the active Alias. (8) The Order Bag name; that is the index file name. (9) The order number. (10) The order tag (name). When DBFNTX database driver is used, it correspond to the Order Bag name. <Index> ##THE DOT LINE## ================================================================ Starting nB without parameters, the dot line appears. This is the place where commands in form of functions may be written and executed like a old xBase. The functions written inside the command line that don't result in an error, are saved inside a history list. This history list may be recalled with [F2] and then the selected history line may be reused (eventually edited). Key [up]/[down] may be used to scroll inside the history list without showing the all list with [F2]. [Enter] is used to tell nB to execute the written function. As the dot line is not an easy way to use such a program, a menu is available pressing [F10] or [Alt]+[M]. The [F10] key starts the ASSIST() menu. This menu may be started also entering the name of the function: "ASSIST()". nB includes a simple built-in text editor: DOC(). It may be started from the dot line entering "DOT()". No special key is dedicated to start this function. <The Menu System> <The Text Editor Doc()> <Index> ##THE MENU SYSTEM## ================================================================ The nB menu system appears differently depending on the place where it is "called". When available, the menu system appears pressing [Alt]+[M] or [F10]. The Menu system is organised into: * Horizontal menu, * Vertical menu, * Pop-up menu. The horizontal menu contains selectable items organised horizontally: One Two Three Four Five * The cursor may be moved on a different position using arrow keys [Left]/[Right]. * [Esc] terminates the menu. * [Enter] opens a vertical menu. The vertical menu contains selectable items organised vertically: One Two Three Four Five ------------ |First | |Second | |Third | ------------ * The cursor may be moved on a different position using arrow keys [Up]/[Down]. * The arrow keys [Left]/[Right] change the Vertical menu. * [Esc] closes the vertical the menu. * [Enter] starts the selected menu function. The vertical menu contains selectable items organised vertically: One Two Three Four Five ------------ |First | |Second >|--------------- |Third |Sub function 1| -----------|Sub function 2| ---------------- * The cursor may be moved on a different position using arrow keys [Up]/[Down]. * [Esc] closes the pop-up the menu. * [Enter] starts the selected menu function. It follows the menu system description. <Index> <The Menu System> <Menu File> <Menu Edit> <Menu Report> <Menu Htf> <Menu Macro> <Menu Info> <Menu Doc> ##MENU FILE## ---------------------------------------------------------------- The menu File contains important function on .DBF file, indexes, relations and Replaceable database drivers. For database files are considered two aspects: the fisical aspect, and the logical Alias. When a .DBF file is opened, it becames a Alias. Indexes are considered as index files and index orders. Here is a brief menu function description. CHANGE DIRECTORY changes the actual drive and directory. FILE .DBF contains a pop-up menu for .DBF operations. New .DBF creates a new .DBF file. Modify .DBF structure modifies a .DBF file structure. Open .DBF opens a .DBF file. FILE .NTX contains a pop-up menu for phisical indexes operations. New .NTX / new TAG creates a new index file or a new order. Open a .NTX file opens an index. ALIAS contains a pop-up menu for logical databases (Alias) operations. Select selects an Alias or a new area from the available ones. Display structure displays the active Alias structure. Close active Alias closes the active Alias (the Alias of the actual area). Close all Aliases close all Aliases (all active areas). ORDER contains a pop-up menu for logical indexes (orders). Order list rebuild makes a reindex. Order set focus selects an order from the list of available ones. Order list clear closes all indexes associated to the active Alias. RELATION contains a pop-up menu for relations (links with other Aliases). Set relation creates a new relation. Clear relation releases all relation for the active Alias. RDD DEFAULT contains a pop-up menu for Replaceable Database Driver defaults. Show actual RDD default shows the active database driver. Set defauld RDD changes the default database driver showing the list of availables ones. <Index> <The Menu System> <Menu File> <Menu Edit> <Menu Report> <Menu Htf> <Menu Macro> <Menu Info> <Menu Doc> ##FILE - NEW .DBF## ................................................................ A .DBF file is a table where columns, called Fields, must be specified and lines, called records, are added, edited and deleted by the program. Field caracteristics are: NAME the field name must be unique inside the same file, it is composed of letters, number and underscore (_), but it must start with a letter and it is not case sensitive. TYPE the field type determinates the type of data it can hold. LENGTH is the field total length in characters; it doesn't matter of the type of data. DECIMAL is the length of positions after decimal point. This information is used normally for numeric fields. In this case, take note that the DECIMAL length, toogether with the decimal point, will subtract space for the interger part of the number from the total LENGTH of the filed. Field Types: C Character it is a text field long LENGTH characters. N Numeric it is a numeric field long LENGTH characters with DECIMAL characters for decimal positions. Note that if LENGHT is 4 and DECIMAL is 0 (zero), the field may conatain integers from -999 to 9999; but if LENGTH is 4 and DECIMAL 1, the field may contain numbers from -9.9 to 99.9: two position for the interger part, one position for the decimal point and one position for decimal. D Date it is a date field: it contains only dates; the length should not be specified as it is automatically 8. L Logic it is a logical (boolean) field: it contains only TRUE, represented by "Y" or "T", or FALSE, represented by "N" or "F". The lenngth should not be specified as it is automatically 1. M Memo it is a character field with unknown dimention. It is recorded into a parallel file with .DBT extention. The original .DBF file holds a space for a pointer inside the .DBT file. The length of a Memo field is automatically 10 and is referred to the memo pointer. After the function "NEW .DBF" is selected, a table for the field specifications appears. +--------------------------------+ | Database file structure | | | | Field Name Type Length Decimal | |--------------------------------| | | | 0| 0 | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | To navigate and to edit the tabel use the following keys: [Up]/[Down]/[Left][Right] move the cursor one position (up, down, left or right); [PgUp] move to previous screen page; [PgDn] move to next screen page; [Ctrl]+[PgUp] move to top of table; [Ctrl]+[PgDn] move to bottom of table; [Ctrl]+[Home] move to first column; [Ctrl]+[End] move to last column; [Ctrl]+[Enter] append a new empty line; [Ctrl]+[F1] delete (cut) the current line and save a copy into the "clipboard"; [Ctrl]+[F2] copy current line into the table "clipboard"; [Ctrl]+[F3] insert (paste) the content of the "clipboard" in the current position; [Enter] start editing in the current position; [Esc] terminate; [...] any other key will be written in the current position. When the editing is terminated, press [Esc] and a dialog box will ask for the file name and the RDD. xBase files (.DBF) are not all equal, this way, when a new .DBF file si created, the RDD (Replaceable Database Driver) is asked. The normal RDD is DBFNTX, the one used by CA-Clipper. <Menu File> <The Menu System> <Index> ##FILE - MODIFY .DBF STRUCTURE## ................................................................ The modification of a .DBF file structure is a delicate matter if it contains data. In fact, it is a data transfer from a source .DBF file to a destination .DBF file with a different structure. This way, the destination .DBF will be updated only for the fields with the same name of the source one. The position may be different, but names cannot be changed (not so easyly). Mistakes may be dangerous, so, before doing it, it is recommened a backup copy of the origina .DBF file. See also <File - New .Dbf> for more informations. <Menu File> <The Menu System> <Index> ##FILE - OPEN .DBF## ................................................................ When a .DBF file is opend, it becames a Alias, a logical file, pleced inside a work area. The same .DBF file may be opened inside different areas with different Alias names. The required information to open the file are: FILENAME the phisical file name. ALIAS the alias name. If not assigned, it becames automatically the same of FILENAME without extention. RDD the Replaceable Database Driver to use to access to this file. SHARED a logical value: TRUE means that the file will be accessible to other users, FALSE means use exclusive. READ ONLY a logical value: TRUE means that the file will be only readable and no modification will be allowed, FALSE means that no restriction on editing will be made. <Menu File> <The Menu System> <Index> ##FILE - NEW .NTX / NEW TAG## ................................................................ If the active area is used we have an active Alias. In this case a index may be created. The index is a way to see the active Alias ordered without changing the phisical position of records. There are two words to understand: ORDER and INDEX-BAG. The index bag is the file that contains the information on the record ordering, the order is the rule followed to order the records. A index bag may contains one or more orders depending on the Replaceable Database Driver in use. Typical .NTX file are index bag containing only one order. Depending on the RDD in use the following field may be filled. INDEX FILENAME this is the name of the index bag. KEY EXPRESSION the expression that defines the rule for the record ordering. ORDER NAME this is the nane to give to the order (tag) when the RDD permits to have a index bag containing more than one order. In the other case, the index bag name correspond to the order name. FOR EXPRESSION a FOR condition to filter records before indexing. <Menu File> <The Menu System> <Index> ##FILE - OPEN INDEX## ................................................................ If a index file already exists, it can be associated to the active Alias simply opening it. Take note that the system is not able to verify if the index belong the active Alias and if it is not so a error will result. INDEX NAME is the name of the index bag file to open. <Menu File> <The Menu System> <Index> ##FILE - SELECT## ................................................................ Only one may be the active Alias and with this function the active Alias may be changed choosing from the list of used aread. Selecting the area number zero, no Alias is active. <Menu File> <The Menu System> <Index> ##FILE - DISPLAY STRUCTURE## ................................................................ With this function the active Alias structure may be viewed. ##FILE - CLOSE ACTIVE ALIAS## ................................................................ Selecting this function the active Alias is closed. That is: the .DBF file and evenutual indexes are closed. <Menu File> <The Menu System> <Index> ##FILE - CLOSE ALL ALIASES## ................................................................ With this function all Aliases are closed. <Menu File> <The Menu System> <Index> ##FILE - ORDER LIST REBUILD## ................................................................ This function rebuild the indexes opened and associated to the active Alias. <Menu File> <The Menu System> <Index> ##FILE - ORDER SET FOCUS## ................................................................ This function permits to change the active order selecting form the ones opened and associated to the active Alias. ##FILE - ORDER LIST CLEAR## ................................................................ This function closes all orders associated to the active Alias. <Menu File> <The Menu System> <Index> ##FILE - SET RELATION## ................................................................ This function permits to establish a relation between a Alias and a Child Alias showing as a reslut a unique database. CHILD is the Alias name to connect to the active Alias. EXPRESSION is the relation expression that specify the rule for the relation. The value of this expression is the key to access the Child Alias: if this Child Alias is accessed without index, it must be the record number, if this Child Alias is accessed via index, it must be a valid index key. <Menu File> <The Menu System> <Index> ##FILE - CLEAR RELATION## ................................................................ This function eliminates any relation that originate form the active Alias. <Menu File> <The Menu System> <Index> ##FILE - SHOW ACTUAL RDD DEFAULT## ................................................................ It simply shows the actual Replaceable Database Driver. <Menu File> <The Menu System> <Index> ##FILE - SET DEFAULT RDD## ................................................................ Select a new default Replaceable Database Driver. <Menu File> <The Menu System> <Index> ##MENU EDIT## ---------------------------------------------------------------- The menu Edit contains functions to access data from the active Alias (the actual area). VIEW browse the active Alias with eventual relations, without the possibility to modify it. EDIT/BROWSE browse the active Alias with eventual relations. REPLACE interactive replace on the active Alias. RECALL interactive recall of previously deleted records on the active Alias. DELETE interactive delete of records on the active Alias. PACK packs the active Alias eliminating the deleted records on the active Alias. Note that the active Alias must be opened in exclusive mode (not shared and not read only ). <Index> <The Menu System> <Menu File> <Menu Edit> <Menu Report> <Menu Htf> <Menu Macro> <Menu Info> <Menu Doc> ##EDIT - VIEW## ................................................................ This function permits you to view the active Alias with eventual relations as a table. No edit is allowed. To navigate the table use the following keys. [Enter] start field editing. [PgUp] show previous screen page. [PgDn] show next screen page. [Ctrl]+[PgUp] show top of Alias. [Ctrl]+[PgDn] show bottom of file. [Ctrl]+[Home] show the first column. [Ctrl]+[End] show last column. <Menu Edit> <The Menu System> <Index> ##EDIT - EDIT/BROWSE## ................................................................ This function permits you to edit the active Alias with eventual relations as a table. To navigate and edit the table use the following keys. [Enter] start field editing. [PgUp] show previous screen page. [PgDn] show next screen page. [Ctrl]+[PgUp] show top of Alias. [Ctrl]+[PgDn] show bottom of file. [Ctrl]+[Home] show the first column. [Ctrl]+[End] show last column. [Ctrl]+[Enter] append a new empty record. [Ctrl]+[F2] copy the current record. [Ctrl]+[F3] append and paste a record. [Ctrl]+[F4] paste a previously copyed record, overwriting the content of the current one. [Ctrl]+[Y] delete or recall the current record. [Ctrl]+[Del] delete or recall the current record. When a memo field is edited: [Esc] cancel and close the memo window. [Ctrl]+[Y] line delete." [Ctrl]+[W] save and close the memo window <Menu Edit> <The Menu System> <Index> ##EDIT - REPLACE## ................................................................ The content of a Field of the active Alias may be replaced with an expression. The required data is: FIELD TO REPLACE the Field name to be replaced. NEW VALUE EXPRESSION the expression that obtain the new value for the selected Field. WHILE EXPRESSION the WHILE condition expression: the replacement continue until this expression results True. The constant ".T." is ever True and is the default. FOR EXPRESSION the FOR condition expression: the replacement is made for all records that satisfy the condition. The constant ".T." is ever True and is the default. <Menu Edit> <The Menu System> <Index> ##EDIT - RECALL## ................................................................ The records signed for deletion (deleted but still there), may be recalled (undeleted). The required data is: WHILE EXPRESSION the WHILE condition expression: the record recall continue until this expression results True. The constant ".T." is ever True and is the default. FOR EXPRESSION the FOR condition expression: the record recall is made for all records that satisfy the condition. The constant ".T." is ever True and is the default. <Menu Edit> <The Menu System> <Index> ##EDIT - DELETE## ................................................................ Deletes (sign for deletion) a group of record depending on the required conditions. The required data is: WHILE EXPRESSION the WHILE condition expression: the record deletion continue until this expression results True. The constant ".T." is ever True and is the default. FOR EXPRESSION the FOR condition expression: the record deletion is made for all records that satisfy the condition. The constant ".T." is ever True and is the default. <Menu Edit> <The Menu System> <Index> ##EDIT - PACK## ................................................................ This function eliminates definitely records previously deleted (signed for deletion). It may work only if the active Alias was opened in exclusive mode. <Menu Edit> <The Menu System> <Index> ##MENU REPORT## ---------------------------------------------------------------- The menu Report contains functions for data report (print). In particular, label files .LBL and report file .RPT may be created and used for printing. There is also another way to print, with the RPT() system that is available inside the nB internal editor DOC(). DBGOTOP() moves the record pointer for the active Alias at the first logical record. NEW LABEL creates a new label form file (.LBL). MODIFY LABEL modifies a label form file (.LBL). LABEL FORM prints labels using the active Alias. NEW REPORT creates a new report form file (.FRM). MODIFY REPORT modifies a report form file (.FRM). REPORT FORM prints a report using the active Alias. CREATE/MODIFY/PRINT TEXT activates the function DOC() that is a text editor with the ability to include Fields, form the active Alias. <Index> <The Menu System> <Menu File> <Menu Edit> <Menu Report> <Menu Htf> <Menu Macro> <Menu Info> <Menu Doc> ##REPORT - NEW LABEL## ................................................................ With this function can be created a standard label file (.LBL under the dBaseIII standard). Labels may be printed in more than one column and can contain 16 lines maximum. he label data is the following. REMARK a label remark that will not be printed. HEIGHT the label vertical dimension. WIDTH the label horizontal dimension. MARGIN the left margin in characters. LINES the vertical spacing between labels. SPACES the horizzontal spacing between labels in characters. ACROSS the number of label columns. LINE 1 The first line inside labels. ... LINE 16 The 16th line inside labels. The number of lines inside the lables depend on the HEIGHT and the maximum value is 16. The label lines can contain constant string and/or string expressions. See the example below. Margin <--> XXXXXXX|XXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXX|XXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXX Height XXXX <--- Width ----> XXXXXXXXXXXXXXXX XXXXXXX|XXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXX|XXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX | | Lines <--> | Spaces XX Line 1 XXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XX Line 2 XXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XX Line 3 XXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XX Line 4 XXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XX Line 5 XXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX | | | | | | | | | +---------------- Across ---------------+ <Menu Report> <The Menu System> <Index> ##REPORT - MODIFY LABEL## ................................................................ This function permits you to modify a label file. See <Report - New Label> for more informations. <Menu Report> <The Menu System> <Index> ##REPORT - LABEL FORM## ................................................................ This function permits you to print labels with the data provided by the active Alias: one lable each record. The following data is required. LABEL FILENAME the label filename. WHILE the WHILE condition: the lable printing goes on as long as this condition remain True. FOR the FOR condition: only the records from the active Alias that satisfy the condition are used for the label print. <Menu Report> <The Menu System> <Index> ##REPORT - NEW REPORT## ................................................................ This function permits you to create a standard report form file (.FRM under the dBaseIII standard). The informations to create a .FRM file are divided into two parts: * the head and groups, * * the columns. The first part: head and groups, requires the folliwing informations: PAGE WIDTH the page width in characters. LINES PER PAGE the usable lines per per page. LEFT MARGIN the left margin in characters. DOUBLE SPACED? double spaced print, yes or no. PAGE EJECT BEFORE PRINT? form feed before print, yes or no. PAGE EJECT AFTER PRINT? form feed after print, yes or no. PLAIN PAGE? plain page, yes or no. PAGE HEADER the page header, max 4 lines (the separation between one line and the other is obtained writing a semicolon, ";"). GROUP HEADER the group title. GROUP EXPRESSION the group expression (when it changes, the group changes) SUMMARY REPORT ONLY? only totals and no columns, yes or no. PAGE EJECT AFTER GROUP? form feed when the group changes, yes or no. SUB GROUP HEADER sub group title. SUB GROUP EXPRESSION the sub group expression. The second part: columns, requires the folliwing informations structured in table form: COLUMN HEADER column head description (it can contain 4 lines separated with a semicolon). CONTENT the column expression. WIDTH the column witdth. DEC. the decimal lengh for numeric columns. TOTALS totals to be calculated, yes or no (usefull only for numeric columns). To navigate and to edit the tabel use the following keys: [Up]/[Down]/[Left][Right] move the cursor one position (up, down, left or right); [PgUp] move to previous screen page; [PgDn] move to next screen page; [Ctrl]+[PgUp] move to top of table; [Ctrl]+[PgDn] move to bottom of table; [Ctrl]+[Home] move to first column; [Ctrl]+[End] move to last column; [Ctrl]+[Enter] append a new empty line; [Ctrl]+[F1] delete (cut) the current line and save a copy into the "clipboard"; [Ctrl]+[F2] copy current line into the table "clipboard"; [Ctrl]+[F3] insert (paste) the content of the "clipboard" in the current position; [Enter] start editing in the current position; [Esc] terminate; [...] any other key will be written in the current position. When the editing is terminated, press [Esc] and a dialog box will ask for the name to give to the report form file. <Menu Report> <The Menu System> <Index> ##REPORT - MODIFY REPORT## ................................................................ This function permits you to modify a standard report form file (.FRM under the dBaseIII standard). For more information see <Report - New Report>. <Menu Report> <The Menu System> <Index> ##REPORT - REPORT FORM## ................................................................ This function permits you to print a report form with the data provided by the active Alias. The following data is required. REPORT FORM FILENAME the label filename. WHILE the WHILE condition: the form printing goes on as long as this condition remain True. FOR the FOR condition: only the records from the active Alias that satisfy the condition are used for the report form print. <Menu Report> <The Menu System> <Index> ##REPORT - CREATE/MODIFY/PRINT TEXT## ................................................................ This function activates the text editor. See <Menu Doc> for more informations. <Menu Report> <The Menu System> <Index> ##MENU HTF## ---------------------------------------------------------------- The menu Htf helps on creating and accessing the "Help Text Files". This name, help text file, is just the name that I gived to it. A text (Ascii) file prepared like this manual may be transformed into a "Help Text File" that is a simple text with pointers. OPEN HELP TEXT FILE opens and browse a "help text file" (.DBF). NEW HELP TEXT FILE generates a new "help text file" (.DBF) from a Ascii file source. NEW HELP TEXT FILE generates a new HTML from a Ascii file source. <The Help Text File> <Index> <The Menu System> <Menu File> <Menu Edit> <Menu Report> <Menu Htf> <Menu Macro> <Menu Info> <Menu Doc> ##HTF - OPEN HELP TEXT FILE## ................................................................ This function permits to open a Help Text File and browse it. The Help Text File name is required. <Menu Htf> <The Menu System> <Index> ##HTF - NEW HELP TEXT FILE## ................................................................ This function permits to create a new "Help Text File" that is a help file under the nB style. The source is an Ascii file where three kind of information are available: Normal text, Indexes and pointers. Indexes and Pointers are word or phrases delimited with user defined delimiters; indexes are placed inside the text to indicate an argument, pointers are placed inside the text to indicate a reference to indexes. Inside this manual, indexes are delimited with ## and ##, so the titles are here indexes; pointers are delimited with < and >. Only one index per line is allowed, only one pointer per line is allowed. The Delimiters used do identify indexes and pointers are user defined; the _start_ identifyer symbol can be equal to the _end_ identifyer symbol. The symbols used for indexes cannot be used for the pointers. So, the informations riquired are: SOURCE TEXT FILENAME the filename of the text source file. DESTINATION FILENAME the filename of the destination Help Text File (suggested .HLP extention). INDEX START CODE the index start symbol; suggested ##. INDEX END CODE the index end symbol; suggested ##. POINTER START CODE the pointer start symbol; suggested <. POINTER END CODE the pointer end symbol; suggested >. <Menu Htf> <The Menu System> <Index> ##HTF - NEW HTML FILE## ................................................................ This function permits to create a new HTML file form a text file formatted to obtain a HTF file (See: <htf - new help text file>). The informations required are: SOURCE TEXT FILENAME the filename of the text source file. DESTINATION FILENAME the filename of the destination Help Text File (suggested .HLP extention). INDEX START CODE the index start symbol; suggested ##. INDEX END CODE the index end symbol; suggested ##. POINTER START CODE the pointer start symbol; suggested <. POINTER END CODE the pointer end symbol; suggested >. HTML TITLE the title for the html page. <Menu Htf> <The Menu System> <Index> ##MENU MACRO## ---------------------------------------------------------------- The menu Macro helps on creating macros (programs) with a macro recorder, a macro "compiler" and a macro executor. START|PAUSE RECORDING starts or pause the macro recorder. SAVE RECORDING save recorded macro on a macro file (Ascii). ERASE RECORDING erase the actual recording session. EDIT RECORDING edits the actual recording. MACRO "COMPILATION" compiles a Ascii macro into a compiled file. LOAD + EXECUTE MACRO loads a macro file and executes it: it doesn't matter if it is a "compiled" macro or a Ascii macro. The difference is the execution speed. <Macro> <Index> <The Menu System> <Menu File> <Menu Edit> <Menu Report> <Menu Htf> <Menu Macro> <Menu Info> <Menu Doc> ##MACRO - START RECORDING## ................................................................ This function simply starts or pause the macro recording. The menu items that end with "&", may be recorded by this macro recorder. <Menu Macro> <The Menu System> <Index> ##MACRO - SAVE RECORDING## ................................................................ A recorded macro may be saved into a ASCII file that may be later modifyed or simply used as it is. The filename is requested. <Menu Macro> <The Menu System> <Index> ##MACRO - ERASE RECORDING## ................................................................ While recording or when the macro recorder is paused, it is possible to erase all previous recording with this function. <Menu Macro> <The Menu System> <Index> ##MACRO - EDIT RECORDING## ................................................................ While recording or when the macro recorder is paused, it is possible to edit all previous recording, for example adding more comments or simply to see what the recorder does. <Menu Macro> <The Menu System> <Index> ##MACRO - MACRO COMPILATION## ................................................................ A macro file (a program) contained inside a ASCII file, may be compiled into a different file format to speed up execution. The source filename and the destination filename are requested. <Menu Macro> <The Menu System> <Index> ##MACRO - LOAD + EXECUTE MACRO## ................................................................ A macro file (a program) in ASCII form or compiled, may be executed. A macro file may require some parameters. This function asks for the macro filename to start and the possible parameter to pass to it. <Menu Macro> <The Menu System> <Index> ##MENU INFO## ---------------------------------------------------------------- The menu Info is the information menu. ABOUT a brief copyright notice. MANUAL BROWSE starts the browse of NB.HLP, the nB Help Text File manual if it is present in the current directory or it is found in the PATH (the Dos SET PATH). [F1] HELP [F1] reminder. [F3] ALIAS INFO [F3] reminder. It shows all the available information on the active Alias. [F5] SET OUTPUT TO [F5] reminder. It defines the output peripheral or file. <Copyright> <Index> <The Menu System> <Menu File> <Menu Edit> <Menu Report> <Menu Htf> <Menu Macro> <Menu Info> <Menu Doc> ##MENU DOC## ---------------------------------------------------------------- This menu actually appears only inside the DOC() function, the nB text editor. NEW empties the work area. OPEN opens a new text file. SAVE saves the text file in use. SAVE AS saves the file with a new name. SET OUTPUT TO changes the output peripheral or file. PRINT AS IT IS prints the text file without transforming the variables or executing print commands. PRINT WITH RPT() ONCE prints the text using Memvars and Fields from the actual record on the active Alias: it calls the RPT() functions. PRINT WITH RPT() STD prints the text using all logical records in the active Alias: it calls the RPT() functions. EXIT terminates the Doc() execution. <RPT - the nB print function> <The Text Editor DOC()> <Index> <The Menu System> <Menu File> <Menu Edit> <Menu Report> <Menu Htf> <Menu Macro> <Menu Info> <Menu Doc> ##DOC - NEW## ................................................................ It starts the editing of a new empty text. <Menu Doc> <The Menu System> <Index> ##DOC - OPEN## ................................................................ It opens for editing a new textfile. <Menu Doc> <The Menu System> <Index> ##DOC - SAVE## ................................................................ It saves the text file under editing. <Menu Doc> <The Menu System> <Index> ##DOC - SAVE AS## ................................................................ It saves the text file under editing asking for a new name. <Menu Doc> <The Menu System> <Index> ##DOC - SET OUTPUT TO## ................................................................ It permits to change the default output peripheral: the default is the screen. <Menu Doc> <The Menu System> <Index> ##DOC - PRINT AS IT IS## ................................................................ It prints on the output pheriperal the content of the text as it is. <Menu Doc> <The Menu System> <Index> ##DOC - PRINT WITH RPT() ONCE## ................................................................ It prints on the output pheriperal the content of the text only once replacing possible text variables. <Menu Doc> <The Menu System> <Index> ##DOC - PRINT WITH RPT() STD## ................................................................ It prints on the output pheriperal the content of the text repeating this print for every record contained inside the acrive Alias. <Menu Doc> <The Menu System> <Index> ##DOC - EXIT DOC()## ................................................................ Termitates the use of DOC() the text/document editing/print function. <Menu Doc> <The Menu System> <Index> ##THE TEXT EDITOR DOC()## ================================================================ The function Doc() activates a simple text editor usefull to build some simple reports. Inside this function a menu is available and is activated pressing [Alt]+[M] or [F10]. The Doc() menu is part of the nB menu system. DOC() may handle text files of a torical maximum of 64K. DOC() may be particularily usefull to create formatted text with variables identified by CHR(174) and CHR(175) delimiters: when an active Alias exists, [F2] gives a list of insertable fields. [Esc] Exit DOC(). [F1] Call the help. [F2] Field list. [up] / [Ctrl]+[E] Line up. [down] / [Ctrl]+[X] Line down. [left] / [Ctrl]+[S] Character left. [right] / [Ctrl]+[D] Character right. [Ctrl]+[right] / [Ctrl]+[A] Word left. [Ctrl]+[left] / [Ctrl]+[F] Word right. [Home] Line start. [End] Line end. [Ctrl]+[Home] Top window. [Ctrl]+[End] Bottom window. [PgUp] Previous window. [PgDn] Next window. [Ctrl]+[PgUp] Document start. [Ctrl]+[PgDn] End document. [Del] Delete character (right). [Backspace] Delete character Left. [Tab] Insert tab. [Ins] Toggle insert/overwrite. [Enter] Next line. [Ctrl]+[Y] Delete line. [Ctrl]+[T] Delete word right. [F10] / [Alt]+[M] DOC() menu. <The menu system> <Menu Doc> <RPT - the nB print function> <Index> ##THE HELP TEXT FILE## ================================================================ nB provides a basic hypertext system to build simple help files. A source text file with "indexes" and "pointers" to indexes is translated into a "help text file" (a .DBF file); then, this file is browsed by nB. The source file can have a maximum line width of 80 characters; each line can temrinate with CR or CR+LF. "Indexes" are string delimited by index delimiters (default "##"); "pointers" are string delimited by pointer delimiters (default "<" and ">") and refers to indexes. Inside a text, indexes must be unique; pointers can be repeated anywhere. A text can contain a maximum of 4000 indexes. Inside this manual, titles are delimited with "##" as they are indexes; strings delimited with "<" and ">" identify a reference to a title with the same string. To browse a previously created Help Text File, use the following keys: [Esc] Exit. [UpArrow] Move cursor up. [DownArrow] Move cursor down. [PgUp] Move cursor PageUp. [PgDn] Move cursor Pagedown. [Ctrl]+[PgUp] Move cursor Top. [Ctrl]+[PgDn] Move cursor Bottom. [Enter] Select a reference (pointer). [<-] Go to previous selected reference (pointer). [->] Go to next selected reference (pointer). [Shift]+[F3] Search for a new pattern. [F3] Repeat previous search. ##MACRO## ================================================================ nB can execute (run) macro files. There may be three kind of macro files: * ascii (usually with .& extention), * "compiled" (usually with .NB extention), * EXE files (compiled with CA-Clipper and linked). "Compiled" macro files are executed faster then the ascii source files. EXE macro files are the fastest. ##MACRO STATEMENTS## ---------------------------------------------------------------- The statemens recognised from nB are very similar to CA-Clipper, with some restrictions. Note that: * The FOR statement is not included; * there is no function declaration; * procedure calls cannot transfer variables; * only public variables are allowed. ##PROCEDURE## ................................................................ Procedures are the basic building blocks of a nB macro. Procedures are visible only inside the current macro file. The procedure structure is as follows: PROCEDURE <procedure name> <statements>... [RETURN] <statements>... ENDPROCEDURE A procedure definition begins with a PROCEDURE declaration followed with the <procedure name> and ends with ENDPROCEDURE. Inside the PROCEDURE - ENDPROCEDURE declaration are placed the executable <statements> which are executed when the procedure is called. Inside the PROCEDURE - ENDPROCEDURE declaration, the RETURN statement may appear. In this case, encountering this RETURN statement, the procedure execution is immediatly terminated and control is passed to the statement following the calling one. The procedure definition do not permit to receive parameters from the calling statement. ##DO PROCEDURE## ................................................................ There is only one way to call a procedure: DO PROCEDURE <procedure name> When the statement DO PROCEDURE is encountered, the control is passed to the begin of the called PROCEDURE. After the PROCEDURE execution, the control is returned to the statement following DO PROCEDURE. The procedure call do not permit to send parameters to the procedure. ##BEGIN SEQUENCE## ................................................................ The BEGIN SEQUENCE - END structure permits to define a sequence of operation that may be broken. Inside nB, this control structure is useful only because there is the possibility to break the execution and pass control over the end of it. This way, encountering BREAK means: "go to end". BEGIN SEQUENCE <statements>... [BREAK] <statements>... END Inside nB, error exeption handling is not supported. ##DO CASE## ................................................................ This is a control structure where only the statements following a True CASE condition are executed. When the DO CASE statement is encountered, the following CASE statements are tested. The first time that a condition returns True, the CASE's statemens are executed and then control is passed over the END case. That is: only one CASE is taken into consideration. If no condition is True, the statemens following OTHERWISE are executed. DO CASE CASE <lCondition1> <statements>... [CASE <lCondition2>] <statements>... [OTHERWISE] <statements>... END ##WHILE## ................................................................ The structure WHILE - END defines a loop based on a condition: the loop is repeated until the condition is True. The loop execution may be broken with the EXIT statement: it transfer control after the END while. The LOOP statement may be use to repeat the loop: it transfer the control to the beginninf of the loop. WHILE <lCondition> <statements>... [EXIT] <statements>... [LOOP] <statements>... END ##IF## ................................................................ The IF - END control structure executes a section of code if a specified condition is True. The structure can also specify alternative code to execute if the condition is False. IF <lCondition1> <statements>... [ELSE] <statements>... END ##VARIABLE DECLARATION## ---------------------------------------------------------------- Inside nB, variables are created using a specific function: MEMPUBLIC( <cVarName> ) For example, MEMPUBLIC( "Name" ) creates the variable Name. The scope of the created variable is global and there is no way to restrict the visibility of it. When a variable is no more needed or desired, it can be released: MEMRELEASE( "cVarName" ) The variable declaration do not defines the variable type. Every variable may receive any kind of data; that is that the type depends on the type of data contained. ##MACRO STRUCTURE## ---------------------------------------------------------------- A nB macro must be organised as follow. There may be two situations: Macros with procedures and macros without procedures. Macro with procedures: PROCEDURE <procedure name1> <statements>... [RETURN] <statements>... ENDPROCEDURE PROCEDURE <procedure name2> <statements>... [RETURN] <statements>... ENDPROCEDURE PROCEDURE <procedure name3> <statements>... [RETURN] <statements>... ENDPROCEDURE ... ... DO PROCEDURE <procedure name nth> Macro without procedures: <statements>... <statements>... <statements>... <statements>... <statements>... <statements>... <statements>... nB Macros may be compiled with CA-Clipper. To do so, the first structure example must be changed as follows: #INCLUDE MACRO.CH DO PROCEDURE <procedure name nth> ... PROCEDURE <procedure name1> <statements>... [RETURN] <statements>... ENDPROCEDURE PROCEDURE <procedure name2> <statements>... [RETURN] <statements>... ENDPROCEDURE PROCEDURE <procedure name3> <statements>... [RETURN] <statements>... ENDPROCEDURE ... ... To compile a macro with CA-Clipper, the macro file name can be changed into MACRO.PRG and RTLINK MACRO.RMK [Enter] should be started. ##MACRO COMMENTS## ---------------------------------------------------------------- A nB Macro source file can contain comments. only the "//" comment is recognised! This way: * and /*...*/ will generate errors! ATTENTION: to simplify the macro interpretation, lines such as this: qqout( "You can't do that // you can't do that!" ) will generate an error as the interpreter will read only: qqout( "You can't do that Sorry! ##MACRO LONG LINES SPLIT## ---------------------------------------------------------------- Inside a nB macro, long lines may be splitted using ";" (semicolon). * Lines can only be splitted and not joined! * A resulting command line cannot be longher then 254 characters. ##THE MACRO RECORDER## ---------------------------------------------------------------- Inside the functions ASSIST() and DOC() is available the Macro recorder menu. When a macro recording is started, a "&" appears on the left side of the status bar. It it blinks, the recording is active, if it is stable, the recording is paused. The macro recording is not exactly a step-by-step recording of all action taken, but a translation (as good as posible) of what you have done. The macro recorder is able to record only the menu functions that terminates with the "&" symbol and all what is inserted at the dot command line. The macro recording can be viewed and edited during the recording. The macro recording can be saved into a text file (a macro file). ##DATA TYPES## ================================================================ The data types supportd in the nB macro language are the same as CA-Clipper: * Array * Character * Code Block * Numeric * Date * Logical * Memo * NIL ##CHARACTER## ---------------------------------------------------------------- The character data type identifies character strings of a fixed length. The character set corresponds to: CHR(32) through CHR(255) and the null character, CHR(0). Valid character strings consist of zero or more characters with a teorical maximum of 65535 characters. The real maximum dimention depends on the available memory. Character string constants are formed by enclosing a valid string of characters within a designed pair of delimiters. There are three possible delimiter pairs: * two single quotes 'string constant' * two double quotes "string constant" * left and right square brackets [string constant] These three different kind of delimiters are available to resolve some possible problems: I don't want it -> "I don't want it" She said, "I love hin" -> 'She said, "I love hin"' He said, "I don't want it" -> [He said, "I don't want it"] The following table shows all operations available inside nB for character data types. These operations act on one or more character expressions and the result is not necessarily a character data type. + Concatenate. - Concatenate without intervening spaces. == Compare for exact equity. !=, <>, # Compare for inequity. < Compare for sorts before <= Compare for sorts before or same as. > Compare for sorts after. >= Compare for sorts after or same as. := In line assign. $ Test for substring existance. ALLTRIM() Remove leading and trailing spaces. ASC() Convert to numeric ASCII code equivalent. AT() Locate substring position. CTOD() Convert to date. DESCEND() Convert to complemented form. EMPTY() Test for null or blank string. ISALPHA() Test for initial letter. ISDIGIT() Test for initial digit. ISLOWER() Test for initial lowercase letter. ISUPPER() Test for initial uppercase letter. LEFT() Extract substring form the left. LEN() Compute string lenght in characters. LOWER() Convert letters to lowercase. LTRIM() Remove leading spaces. PADC() Pad with leading and trailing spaces. PADL() Pad with leading spaces. PADR() Pad with trailing spaces. RAT() Locate substring position starting from the right. RIGHT() Extract substring form the right. RTRIM() Remove trailing spaces. SOUNDEX() Convert to soundex equivalent. SPACE() Create a blank string of a defined length. STRTRAN() Search and replace substring. STUFF() Replace substring. SUBSTR() Extract substring. TRANSFORM() Convert to formatted string. UPPER() Convert letters to uppercase VAL() Convert to numeric. VALTYPE() Evaluates data type directly. ##MEMO## ---------------------------------------------------------------- The memo data type is used to represent variable length character data that can only exist in the form of a database field. Memo fields are not stored inside the main database file (.DBF) but inside a separate file (.DBT). A memo field can contain up to 65535 charaters, that is the same maximum dimension of character fields. In fact, originally xBases, couldn't have character string longher than 254 chacarters. As here memo fields are very similar to long character strings, you may forget that there is a difference. All the operations that may be applyed to character strings, may be used with memo fields; the following functions may be use epecially for memo fields or long character strings. HARDCR() Replace soft with hard carriage returns. MEMOEDIT() Edit contents. MEMOLINE() Extract a line of a text. MEMOREAD() Read form a disk text file. MEMOTRAN() Repace soft and hard carriage returns. MEMOWRIT() Write to disk text file. MLCOUNT() Count lines. MLPOS() Compute position. ##DATE## ---------------------------------------------------------------- The date data type is used to represent calendar dates. Supported dates are from 0100.01.01 to 2999.12.31 and null or blank date. The appearence of a date is controlled from SETVERB("DATEFORMAT"). The default is "dd/mm/yyyy" and it may easyly changed for example with SETVERB("DATEFORMAT", "MM/DD/YYYY") to the US standard. There is no way to represent date constants; these must be replaced with the CTOD() function. For example if the date 11/11/1995 is to be written, the right way is: CTOD( "11/11/1995" ) The character string "11/11/1995" must respect the date format defined as before explained. The function CTOD() will accept only valid dates, and null dates: CTOD( "" ) A null date is ever less than any other valid date. The following table shows all operations available inside nB for date data types. These operations act on one or more date expressions and the result is not necessarily a character data type. + Add a number of days to a date. - Subtract days to a date. == Compare for equity. !=, <>, # Compare for inequity. < Compare for earlier <= Compare for earlier or same as. > Compare for later. >= Compare for later or same as. := In line assign. CDOW() Compute day of week name. CMONTH() Compute month name. DAY() Extract day number. DESCEND() Convert to complemented form. DOW() Compute day of week. DTOC() Convert to character string with the format defined with SETVERB( "DATEFORMAT" ). DOTOS() Convert to character string in sorting format (YYYYMMDD). EMPTY() Test for null date. MONTH() Extract month number. VALTYPE() Evaluates data type directly. YEAR() Extract entire year number, including century. ##NUMERIC## ---------------------------------------------------------------- The numeric data type identifies real number. The teorical range is form 10^-308 to 10^308 but the numeric precision is guaranteed up to 16 significant digits, and formatting a numeric value for display is guaranteed up to a lenght of 32 (30 digits, a sign, and a decimal point). That is: numbers longher than 32 bytes may be displayed as asterisks, and digits other nhen most 16 significant ones are sisplayed as zeroes. Numeric constants are written without delimites. The following are valid constant numbers: 12345 12345.678 -156 +1256.789 -.789 If a numeric constant is delimited like character strings, it becames a character string. The following table shows all operations available inside nB for numeric data types. These operations act on one or more numeric expressions and the result is not necessarily a numeric data type. + Add or Unary Positive. - Subtract or Unary Negative. * Multipy. / Divide. % Modulus. ^, ** Exponentiate. == Compare for equity. !=, <>, # Compare for inequity. < Compare for less than. <= Compare for less than or equal. > Compare for greater than. >= Compare for greater than or equal. := In line assign. ABS() Compute absolute value. CHR() Convert to ASCII character equivalent. DESCEND() Convert to complemented form. EMPTY() Test for zero. EXP() Exponentiate with e as the base. INT() Convert to integer. LOG() Compute natural logarithm. MAX() Compute maximum. MIN() Compute minimun. ROUND() Round up or down() SQRT() Compute square root. STR() Convert to character. TRANSFORM() Convert to formatted string. VALTYPE() Evaluates data type directly. Number uppearence may be affected by SETVERB("FIXED") and consequently by SETVERB("DECIMALS"). If SETVERB("FIXED") is True, numbers are displayed with a fixed decimal position. The number of decimal positions is defined by SETVERB("DECIMALS"). For that reason, the default is SETVERB("FIXED", .F.) and SETVERB("DECIMALS", 2), that is, no fixed decimal position, but if they will be activated, the default is two decimal digits. ##LOGICAL## ---------------------------------------------------------------- The logical data type identifies Boolean values. Logical constants are: .T. True. .F. False. When editing a logical field, inputs may be: y, Y, t, T for True n, N, f, F for False The following table shows all operations available inside nB for logical data types. These operations act on one or more logical expressions and the result is not necessarily a logical data type. .AND. And. .OR. Or. .NOT. or ! Negate. == Compare for equity. !=, <>, or # Compare for inequity. Comparing two logical values, False (.F.) is always less than True (.T.). ##NIL## ---------------------------------------------------------------- NIL is not properly a data type, it represent the value of an uninitialised valiable. Inside nB (like what it happens inside CA-Clipper), variables are not declared with the data type that they will contain. This means that a variable can contain any kind of data. In fact, nB variables are pointer to data and a pointer to "nothing" is NIL. NIL may be used as constant for assignment or comparing purpose: NIL Fields (database fields) cannot contain NIL. The following table shows all operations available inside nB for the NIL data type. Except for these operations, attempting to operate on a NIL results in a runtime error. == Compare for equity. !=, <>, # Compare for inequity. < Compare for less than. <= Compare for less than or equal. > Compare for greater than. >= Compare for greater than or equal. := In line assign. EMPTY() Test for NIL. VALTYPE() Evaluates data type directly. For the purpose of comparison, NIL is the only value that is equal to NIL. All other values are greater than NIL. Variables are created inside nB with MEMPUBLIC(). This function creates variables which will be automatically initialised to NIL. ##ARRAY## ---------------------------------------------------------------- The array data type identifies a collection of related data items that share the same name. Each value in an array is referred to as an element. Array elements can be of any data type except memo (memo is available only inside database fields). For example the first element can be a character string, the second a number, the third a date and so on. Arrays can contain other arrays and code blocks as elements. The variable containing the array does not contains the entire array, but the reference to it. When the NIL type was described, it was cleared that variables doesn't contains real data, but pointer to data. But this happens in a transparent way, that is that when the a variable is assigned to another (for example A := B) the variable receiving the assignment will receive a pointer to a new copy of the source data. This is not the same with arrays: assigning to a variable an array, will assign to that variable a pointer to the same source array and not to a new copy of it. If arrays are to be duplicated, the ACLONE() function is to be used. An array constant may be expressed using curly brackets {}. See the examples below. A := { "first element", "second element", "third element" } With this example, the variable A contain the reference to an array with three element containig character string. A[1] == "first element" A[2] == "second element" A[3] == "third element" Arrays may contain also no element: empty array and may be expressed as: {} The array element is identifyed by a number enclosed with square brackets, following the variable name containing the reference to the array. The first array element is one. If an array contains arrays, we obtain a multidimentional array. For example: A := { { 1, 2 }, { 3, 4 }, { 5, 6 } } is equivalent to the following table. 1 2 3 4 5 6 With this example, the variable A contain the reference to a bidimentional array containing numbers. A[1,1] or A[1][1] contains 1 A[1,2] or A[1][2] contains 2 A[2,1] or A[2][1] contains 3 and so on. As arrays may contain mixed data, it is the user who have to handel correctly the element numbers. For example: A := { "hello", { 3, 4 }, 1234 } A[1] == "hello" A[2] == reference to { 3, 4 } A[3] == 1234 A[2,1] or A[2][1] contains 3 A[2,2] or A[2][2] contains 4 A[1,1] is an error! The following table shows all operations available inside nB for arrays. := In line assign. AADD() Add dinamically an element to an array. ACLONE() Create a copy of an array. ACOPY() Copy element by element an array to another. ADEL() Delete one element inside an array. AFILL() Fill all array elements with a value. AINS() Insert an element inside an array. ARRAY() Creates an array of empty elements. ASCAN() Scan the array elements. ASIZE() Resize an array. ASORT() Sort the array elements. EMPTY() Test for no elements. VALTYPE() Evaluates data type directly. ##CODE BLOCK## ---------------------------------------------------------------- The code block data type identifies a small piece of executable program code. A code block is something like a little user defined function where only a sequence of functions or assignments may appear: no loops, no IF ELSE END. A code block may receive argument and retun a value after execution, just like a function. The syntax is: { | [<argument list>] | <exp list> } That is: the <argument list> is optional; the <exp list> may contain one or more expressions separated with a comma. For example, calling the following code block will give the string "hello world" as reslut. { || "hello world" } The following code block require a numeric argument an returns the number passed as argument incremented: { | n | n+1 } The following code block requires two numeric arguments and returns the sum of the two square radix: { | nFirst, nSecond | SQRT(nFirst) + SQRT(nSecond) } But code blocks may contains more expressions and the result of the execution of the code block is the result of the last expression. The following code block executes in sequence some functions and give ever "hello world" as a result. { | a, b | functionOne(a), functionTwo(b), "hello world" } To start the execution of a code block a function is used: EVAL() For example, a code block is assigned to a variable and then executed. B := { || "hello world" } EVAL( B ) == "hello world" Another example with a parameter. B := { | n | n+1 } EVAL( B, 1 ) == 2 Another example with two parameters. B := { | nFirst, nSecond | SQRT(nFirst) + SQRT(nSecond) } EVAL( B, 2, 4 ) == 20 And so on. The following table shows some operations available inside nB for code blocks: many functions use code blocks as argument. := In line assign. AEVAL() Evaluate (execute) a code block for each element in an array. BCOMPILE() Convert (compile) a character string into a code block. DBEVAL() Evaluate (execute) a code block for each record in the active Alias. EVAL() Evaluate a code block once. VALTYPE() Evaluates data type directly. ##OPERATORS## ================================================================ Here is a list with a brief description of the operators available inside nB. <cString1> $ <cString2> Substring comparison. If <cString1> is contained inside <cString2> the result is true (.T.). <nNumber1> % <nNumber2> Modulus. The result is the remainder of <nNumber1> divided by <nNuber2>. () Function or grouping indicator. <nNumber1> * <nNumber2> Multiplication. <nNumber1> ** <nNumber2> <nNumber1> ^ <nNumber2> Exponentiation. <nNumber1> + <nNumber2> <dDate> + <nNumber> Addition, unary positive. <cString1> + <cString2> String concatenation. The result is the a string beguinning with the content fo <cString1> and following with the content of <cString2>. <nNumber1> - <nNumber2> <dDate1> - <dDate2> <dDate> - <nNumber> Subtraction, unary negative. <cString1> - <cString2> String concatenation. The result is a string containing <cString1> after trimming trailing blanks and <cString2>. <idAlias>-><idField> FIELD-><idVar> MEMVAR-><idVar> Alias assignment. The alias operator implicitly SELECTs the <idAlias> before evaluating <idField>. When the evaluation is complete, the original work area is SELECTed again. <lCondition1> .AND. <lCondition2> Logical AND. .NOT. <lCondition> Logical NOT. <lCondition1> .OR. <lCondition2> Logical OR. <nNumber1> / <nNumber2> Division. <object>:<message>[(argument list)] Send. <idVar> := <exp> Inline assign. <exp1> <= <exp2> Less than or equal. <exp1> <> <exp2> Not equal. <exp1> = <exp2> Equal. <exp1> == <exp2> Exactly equal. <exp1> > <exp2> Greater than. <exp1> >= <exp2> Greater than or equal. @<idVar> Pass-by-reference. [] <aArray>[<nSubscript>, ...] <aArray>[<nSubscript1>][<nSubscript2>] ... Array element indicator. ##DELIMITERS## ================================================================ Here is the delimiter list recognised from nB. { <exp list> } Literal array delimiters. { |<param list>| <exp list> } Code block delimiters. "<cString>" '<cString>' [<cString>] String delimiters. ##CODE BLOCKS## ================================================================ A code block is a sequence of function, assignments and constant like the following: sqrt(10) nResult := 10 * nIndex Suppose that the above sequence of operations has a meaning for you. We want to create a box containing this sequence of operation. This box is contained inside a variable: bBlackBox := { || sqrt(10), nResult := 10 * nIndex } Note the comma used as separator. Now <bBlackBox> contains the small sequence seen before. To execute this sequence, the function EVAL() is used: EVAL(bBlackBox) The execution of the code block gives a result: the value of the last operation contained inside the code block. In this case it is the result of 10*nIndex. For that reason, if the execution of the code block must give a fixed result, it can terminate with a constant. A code block may receive parameters working like a function. Try to imagine that we need to do the following. function multiply( nVar1, nVar2 ) return nVar * nVar2 endfunction A code block that does the same is: bMultiply := { | nVar1, nVar2 | nVar1 * nVar2 } To evaluate it, for example trying to multiply 10 * 5: nResult := EVAL( bMultiply, 10, 5 ) and <nResult> will contain 50. <code block> <eval()> <aeval()> <dbeval()> ##STANDARD FUNCTIONS## ================================================================ With nB All CA-Clipper standard functions may be used. Here follows a short description. ##AADD()## ---------------------------------------------------------------- Array ADD AADD(<aTarget>, <expValue>) --> Value <aTarget> is the array to add a new element to. <expValue> is the value assigned to the new element. It increases the actual length of the target array by one. The newly created array element is assigned the value specified by <expValue>. ##ABS()## ---------------------------------------------------------------- ABSolute ABS(<nExp>) --> nPositive <nExp> is the numeric expression to evaluate. ABS() returns a number representing the absolute value of its argument. ##ACLONE()## ---------------------------------------------------------------- Array CLONE ACLONE(<aSource>) --> aDuplicate <aSource> is the array to duplicate. ACLONE() returns a duplicate of <aSource>. ##ACOPY()## ---------------------------------------------------------------- Array COPY ACOPY(<aSource>, <aTarget>, [<nStart>], [<nCount>], [<nTargetPos>]) --> aTarget <aSource> is the array to copy elements from. <aTarget> is the array to copy elements to. <nStart> is the starting element position in the <aSource> array. If not specified, the default value is one. <nCount> is the number of elements to copy from the <aSource> array beginning at the <nStart> position. If <nCount> is not specified, all elements in <aSource> beginning with the starting element are copied. <nTargetPos> is the starting element position in the <aTarget> array to receive elements from <aSource>. If not specified, the default value is one. ACOPY() is an array function that copies elements from the <aSource> array to the <aTarget> array. The <aTarget> array must already exist and be large enough to hold the copied elements. ##ADEL()## ---------------------------------------------------------------- Array DELete ADEL(<aTarget>, <nPosition>) --> aTarget <aTarget> is the array to delete an element from. <nPosition> is the position of the target array element to delete. ADEL() is an array function that deletes an element from an array. The contents of the specified array element is lost, and all elements from that position to the end of the array are shifted up one element. The last element in the array becomes NIL. ##AEVAL()## ---------------------------------------------------------------- Array EVALuation AEVAL(<aArray>, <bBlock>, [<nStart>], [<nCount>]) --> aArray <aArray> is the array to be evaluated. <bBlock> is a code block to execute for each element encountered. <nStart> is the starting element. If not specified, the default is element one. <nCount> is the number of elements to process from <nStart>. If not specified, the default is all elements to the end of the array. AEVAL() is an array function that evaluates a code block once for each element of an array, passing the element value and the element index as block parameters. The return value of the block is ignored. All elements in <aArray> are processed unless either the <nStart> or the <nCount> argument is specified. ##AFILL()## ---------------------------------------------------------------- Array FILL AFILL(<aTarget>, <expValue>, [<nStart>], [<nCount>]) --> aTarget <aTarget> is the array to fill. <expValue> is the value to place in each array element. It can be an expression of any valid data type. <nStart> is the position of the first element to fill. If this argument is omitted, the default value is one. <nCount> is the number of elements to fill starting with element <nStart>. If this argument is omitted, elements are filled from the starting element position to the end of the array. AFILL() is an array function that fills the specified array with a single value of any data type (including an array, code block, or NIL) by assigning <expValue> to each array element in the specified range. ##AINS()## ---------------------------------------------------------------- Array INSert AINS(<aTarget>, <nPosition>) --> aTarget <aTarget> is the array into which a new element will be inserted. <nPosition> is the position at which the new element will be inserted. AINS() is an array function that inserts a new element into a specified array. The newly inserted element is NIL data type until a new value is assigned to it. After the insertion, the last element in the array is discarded, and all elements after the new element are shifted down one position. ##ALERT()## ---------------------------------------------------------------- ALERT( <cMessage>, [<aOptions>] ) --> nChoice <cMessage> is the message text displayed, centered, in the alert box. If the message contains one or more semicolons, the text after the semicolons is centered on succeeding lines in the dialog box. <aOptions> defines a list of up to 4 possible responses to the dialog box. ALERT() returns a numeric value indicating which option was chosen. If the Esc key is pressed, the value returned is zero. The ALERT() function creates a simple modal dialog. The user can respond by moving a highlight bar and pressing the Return or SpaceBar keys, or by pressing the key corresponding to the first letter of the option. If <aOptions> is not supplied, a single "Ok" option is presented. ##ALIAS()## ---------------------------------------------------------------- ALIAS([<nWorkArea>]) --> cAlias <nWorkArea> is any work area number. ALIAS() returns the alias of the specified work area as a character string. If <nWorkArea> is not specified, the alias of the current work area is returned. If there is no database file in USE for the specified work area, ALIAS() returns a null string (""). ##ALLTRIM()## ---------------------------------------------------------------- ALLTRIM(<cString>) --> cTrimmedString <cString> is the character expression to trim. ALLTRIM() returns a character string with leading and trailing spaces removed. ##ARRAY()## ---------------------------------------------------------------- ARRAY(<nElements> [, <nElements>...]) --> aArray <nElements> is the number of elements in the specified dimension. ARRAY() is an array function that returns an uninitialized array with the specified number of elements and dimensions. ##ASC()## ---------------------------------------------------------------- ASCii ASC(<cExp>) --> nCode <cExp> is the character expression to convert to a number. ASC() returns an integer numeric value in the range of zero to 255, representing the ASCII value of <cExp>. ##ASCAN()## ---------------------------------------------------------------- Array SCAN ASCAN(<aTarget>, <expSearch>, [<nStart>], [<nCount>]) --> nStoppedAt <aTarget> is the array to scan. <expSearch> is either a simple value to scan for, or a code block. If <expSearch> is a simple value it can be character, date, logical, or numeric type. <nStart> is the starting element of the scan. If this argument is not specified, the default starting position is one. <nCount> is the number of elements to scan from the starting position. If this argument is not specified, all elements from the starting element to the end of the array are scanned. ASCAN() returns a numeric value representing the array position of the last element scanned. If <expSearch> is a simple value, ASCAN() returns the position of the first matching element, or zero if a match is not found. If <expSearch> is a code block, ASCAN() returns the position of the element where the block returned true (.T.). ##ASIZE()## ---------------------------------------------------------------- Array SIZE ASIZE(<aTarget>, <nLength>) --> aTarget <aTarget> is the array to grow or shrink. <nLength> is the new size of the array. ASIZE() is an array function that changes the actual length of the <aTarget> array. The array is shortened or lengthened to match the specified length. If the array is shortened, elements at the end of the array are lost. If the array is lengthened, new elements are added to the end of the array and assigned NIL. ##ASORT()## ---------------------------------------------------------------- Array SORT ASORT(<aTarget>, [<nStart>], [<nCount>], [<bOrder>]) --> aTarget <aTarget> is the array to sort. <nStart> is the first element of the sort. If not specified, the default starting position is one. <nCount> is the number of elements to sort. If not specified, all elements in the array beginning with the starting element are sorted. <bOrder> is an optional code block used to determine sorting order. If not specified, the default order is ascending. ASORT() is an array function that sorts all or part of an array containing elements of a single data type. Data types that can be sorted include character, date, logical, and numeric. If the <bOrder> argument is not specified, the default order is ascending. Each time the block is evaluated, two elements from the target array are passed as block parameters. The block must return true (.T.) if the elements are in sorted order. ##AT()## ---------------------------------------------------------------- AT(<cSearch>, <cTarget>) --> nPosition <cSearch> is the character substring for which to search. <cTarget> is the character string to search. AT() returns the position of the first instance of <cSearch> within <cTarget> as an integer numeric value. If <cSearch> is not found, AT() returns zero. AT() is a character function used to determine the position of the first occurrence of a character substring within another string. ##ATAIL()## ---------------------------------------------------------------- Array TAIL ATAIL(<aArray>) --> Element <aArray> is the array. ATAIL() is an array function that returns the highest numbered element of an array. It can be used in applications as shorthand for <aArray>[LEN(<aArray>)] when you need to obtain the last element of an array. ##BIN2I()## ---------------------------------------------------------------- BINary to Integer BIN2I(<cSignedInt>) --> nNumber <cSignedInt> is a character string in the form of a 16-bit signed integer number--least significant byte first. BIN2I() returns an integer obtained converting the first two byte contained inside <cSignedInt>. ##BIN2L()## ---------------------------------------------------------------- BINary to Large BIN2L(<cSignedInt>) --> nNumber <cSignedInt> is a character string in the form of a 32-bit signed integer number--least significant byte first. BIN2L() returns an integer obtained from the first tour characters contained in <cSignedInt>. ##BIN2W()## ---------------------------------------------------------------- BINary to Word BIN2W(<cUnsignedInt>) --> nNumber <cUnsignedInt> is a character string in the form of a 16-bit unsigned integer number--least significant byte first. BIN2W() returns an integer obtained from the first two characters contained in <cSignedInt>. ##BOF()## ---------------------------------------------------------------- Begin Of File BOF() --> lBoundary BOF() returns true (.T.) after an attempt to SKIP backward beyond the first logical record in a database file; otherwise, it returns false (.F.). If there is no database file open in the current work area, BOF() returns false (.F.). If the current database file contains no records, BOF() returns true (.T.). ##CDOW()## ---------------------------------------------------------------- Character Day Of Week CDOW(<dExp>) --> cDayName <dExp> is the date value to convert. CDOW() returns the name of the day of the week as a character string. The first letter is uppercase and the rest of the string is lowercase. For a null date value, CDOW() returns a null string (""). ##CHR()## ---------------------------------------------------------------- CHaRacter CHR(<nCode>) --> cChar <nCode> is an ASCII code in the range of zero to 255. CHR() returns a single character value whose ASCII code is specified by <nCode>. ##CMONTH()## ---------------------------------------------------------------- Character MONTH CMONTH(<dDate>) --> cMonth <dDate> is the date value to convert. CMONTH() returns the name of the month as a character string from a date value with the first letter uppercase and the rest of the string lowercase. For a null date value, CMONTH() returns a null string (""). ##COL()## ---------------------------------------------------------------- COLumn COL() --> nCol COL() is a screen function that returns the current column position of the cursor. The value of COL() changes whenever the cursor position changes on the screen. ##COLORSELECT()## ---------------------------------------------------------------- COLORSELECT(<nColorIndex>) --> NIL <nColorIndex> is a number corresponding to the oridnal positions in the current list of color attributes, as set by SETCOLOR(). COLORSELECT() activates the specified color pair from the current list of color attributes (established by SETCOLOR()). ##CTOD()## ---------------------------------------------------------------- Character To Date CTOD(<cDate>) --> dDate <cDate> is a character string consisting of numbers representing the month, day, and year separated by any character other than a number. The month, day, and year digits must be specified in accordance with the SET DATE format. If the century digits are not specified, the century is determined by the rules of SET EPOCH. CTOD() returns a date value. If <cDate> is not a valid date, CTOD() returns an empty date. ##CURDIR()## ---------------------------------------------------------------- CURrent DIRectory CURDIR([<cDrivespec>]) --> cDirectory <cDrivespec> specifies the letter of the disk drive to query. If not specified, the default is the current DOS drive. CURDIR() returns the current DOS directory of the drive specified by <cDrivespec> as a character string without either leading or trailing backslash (\) characters. ##DATE()## ---------------------------------------------------------------- DATE() --> dSystemDate DATE() returns the system date as a date value. ##DAY()## ---------------------------------------------------------------- DAY(<dDate>) --> nDay <dDate> is a date value to convert. DAY() returns the day number from <dDate>. ##DBAPPEND()## ---------------------------------------------------------------- DBAPPEND([<lReleaseRecLocks>]) --> NIL <lReleaseRecLocks> is a logical data type that if true (.T.), clears all pending record locks, then appends the next record. If <lReleaseRecLocks> is false (.F.), all pending record locks are maintained and the new record is added to the end of the Lock List. The default value of <lReleaseRecLocks> is true (.T.). DBAPPEND() adds a new empty record to the active Alias. ##DBCLEARFILTER()## ---------------------------------------------------------------- DBCLEARFILTER() --> NIL DBCLEARFILTER() clears the logical filter condition, if any, for the current work area. ##DBCLEARINDEX()## ---------------------------------------------------------------- DBCLEARINDEX() --> NIL DBCLEARINDEX() closes any active indexes for the active Alias. ##DBCLEARRELATION()## ---------------------------------------------------------------- DBCLEARRELATION() --> NIL DBCLEARRELATION() clears any active relations for the active Alias. ##DBCLOSEALL()## ---------------------------------------------------------------- DBCLOSEALL() --> NIL DBCLOSEALL() releases all occupied work areas from use. It is equivalent to calling DBCLOSEAREA() on every occupied work area. Attention: DBCLOSEALL() cannot be used inside a "compiled" macro as this will stop the macro execution. In substitution, DBCLOSE() should be used. ##DBCLOSEAREA()## ---------------------------------------------------------------- DBCLOSEAREA() --> NIL DBCLOSEAREA() releases the current work area from use. ##DBCOMMIT()## ---------------------------------------------------------------- DBCOMMIT() --> NIL DBCOMMIT() causes all updates to the current work area to be written to disk. All updated database and index buffers are written to DOS and a DOS COMMIT request is issued for the database (.dbf) file and any index files associated with the work area. Inside a network environment, DBCOMMIT() makes database updates visible to other processes. To insure data integrity, issue DBCOMMIT() before an UNLOCK operation. ##DBCOMMITALL()## ---------------------------------------------------------------- DBCOMMITALL() --> NIL DBCOMMITALL() causes all pending updates to all work areas to be written to disk. It is equivalent to calling DBCOMMIT() for every occupied work area. ##DBCREATE()## ---------------------------------------------------------------- DBCREATE(<cDatabase>, <aStruct>, [<cDriver>]) --> NIL <cDatabase> is the name of the new database file, with an optional drive and directory, specified as a character string. If specified without an extension (.dbf) is assumed. <aStruct> is an array that contains the structure of <cDatabase> as a series of subarrays, one per field. Each subarray contains the definition of each field's attributes and has the following structure: <aStruct[n][1]> cName <aStruct[n][2]> cType <aStruct[n][3]> nLength <aStruct[n][4]> nDecimals <cDriver> specifies the replaceable database driver (RDD) to use to process the current work area. <cDriver> is name of the RDD specified as a character expression. DBCREATE() is a database function that creates a database file from an array containing the structure of the file. ##DBCREATEINDEX()## ---------------------------------------------------------------- DBCREATEINDEX(<cIndexName>, <cKeyExpr>, <bKeyExpr>, [<lUnique>]) --> NIL <cIndexName> is a character value that specifies the filename of the index file (order bag) to be created. <cKeyExpr> is a character value that expresses the index key expression in textual form. <bKeyExpr> is a code block that expresses the index key expression in executable form. <lUnique> is an optional logical value that specifies whether a unique index is to be created. If <lUnique> is omitted, the current global _SET_UNIQUE setting is used. DBCREATEINDEX() creates an index for the active Alias. If the Alias has active indexes, they are closed. ##DBDELETE()## ---------------------------------------------------------------- DBDELETE() --> NIL DBDELETE() marks the current record as deleted (*). Records marked for deletion can be filtered using SET DELETED or removed from the file using the PACK command. ##DBEVAL()## ---------------------------------------------------------------- DB EVALuate DBEVAL(<bBlock>, [<bForCondition>], [<bWhileCondition>], [<nNextRecords>], [<nRecord>], [<lRest>]) --> NIL <bBlock> is a code block to execute for each record processed. <bForCondition> the FOR condition expressed as code block. <bWhileCondition> the WHILE condition expressed as code block. <nNextRecords> is an optional number that specifies the number of records to process starting with the current record. It is the same as the NEXT clause. <nRecord> is an optional record number to process. If this argument is specified, <bBlock> will be evaluated for the specified record. This argument is the same as the RECORD clause. <lRest> is an optional logical value that determines whether the scope of DBEVAL() is all records, or, starting with the current record, all records to the end of file. DBEVAL() is a database function that evaluates a single block for each record within the active Alias. ##DBFILTER()## ---------------------------------------------------------------- DBFILTER() --> cFilter BFILTER() returns the filter condition defined in the current work area as a character string. If no FILTER has been SET, DBFILTER() returns a null string (""). ##DBGOBOTTOM()## ---------------------------------------------------------------- DBGOBOTTOM() --> NIL DBGOBOTTOM() moves to last logical record in the active Alias. ##DBGOTO()## ---------------------------------------------------------------- DBGOTO(<nRecordNumber>) --> NIL <nRecordNumber> is a numeric value that specifies the record number of the desired record. DBGOTO() moves to the record whose record number is equal to <nRecordNumber>. If no such record exists, the work area is positioned to LASTREC() + 1 and both EOF() and BOF() return true (.T.). ##DBGOTOP()## ---------------------------------------------------------------- DBGOTOP() --> NIL DBGOTOP() moves to the first logical record in the current work area. ##DBRECALL()## ---------------------------------------------------------------- DBRECALL() --> NIL DBRECALL() causes the current record to be reinstated if it is marked for deletion. ##DBREINDEX()## ---------------------------------------------------------------- DBREINDEX() --> NIL DBREINDEX() rebuilds all active indexes associated with the active Alias. ##DBRELATION()## ---------------------------------------------------------------- DBRELATION(<nRelation>) --> cLinkExp <nRelation> is the position of the desired relation in the list of activr Alias relations. DBRELATION() returns a character string containing the linking expression of the relation specified by <nRelation>. If there is no RELATION SET for <nRelation>, DBRELATION() returns a null string (""). ##DBRLOCK()## ---------------------------------------------------------------- DB Record LOCK DBRLOCK([<nRecNo>]) --> lSuccess <nRecNo> is the record number to be locked. The default is the current record. DBRLOCK() is a database function that locks the record identified by <nRecNo> or the current record. ##DBRLOCKLIST()## ---------------------------------------------------------------- DBRLOCKLIST() --> aRecordLocks DBRLOCKLIST() returns a one-dimensional array of the locked records in the active Alias. ##DBRSELECT()## ---------------------------------------------------------------- DB Relation SELECT DBRSELECT(<nRelation>) --> nWorkArea <nRelation> is the position of the desired relation in the list of current work area relations. DBRSELECT() returns the work area number of the relation specified by <nRelation> as an integer numeric value. If there is no RELATION SET for <nRelation>, DBRSELECT() returns zero. ##DBRUNLOCK()## ---------------------------------------------------------------- DBRUNLOCK([<nRecNo>]) --> NIL <nRecNo> is the record number to be unlocked. The default is all previously locked records. DBRUNLOCK() is a database function that unlocks the record identified by <nRecNo> or all locked records. ##DBSEEK()## ---------------------------------------------------------------- DBSEEK(<expKey>, [<lSoftSeek>]) --> lFound <expKey> is a value of any type that specifies the key value associated with the desired record. <lSoftSeek> is an optional logical value that specifies whether a soft seek is to be performed. This determines how the work area is positioned if the specified key value is not found. If <lSoftSeek> is omitted, the current global _SET_SOFTSEEK setting is used. DBSEEK() returns true (.T.) if the specified key value was found; otherwise, it returns false (.F.). ##DBSELECTAREA()## ---------------------------------------------------------------- DBSELECTAREA(<nArea> | <cAlias>) --> NIL <nArea> is a numeric value between zero and 250, inclusive, that specifies the work area being selected. <cAlias> is a character value that specifies the alias of a currently occupied work area being selected. DBSELECTAREA() causes the specified work area to become the current work area. All subsequent database operations will apply to this work area unless another work area is explicitly specified for an operation. ##DBSETDRIVER()## ---------------------------------------------------------------- DBSETDRIVER([<cDriver>]) --> cCurrentDriver <cDriver> is an optional character value that specifies the name of the database driver that should be used to activate and manage new work areas when no driver is explicitly specified. DBSETDRIVER() returns the name of the current default driver. ##DBSETFILTER()## ---------------------------------------------------------------- DBSETFILTER(<bCondition>, [<cCondition>]) --> NIL <bCondition> is a code block that expresses the filter condition in executable form. <cCondition> is a character value that expresses the filter condition in textual form. If <cCondition> is omitted, the DBSETFILTER() function will return an empty string for the work area. DBSETFILTER() sets a logical filter condition for the current work area. When a filter is set, records which do not meet the filter condition are not logically visible. That is, database operations which act on logical records will not consider these records. The filter expression supplied to DBSETFILTER() evaluates to true (.T.) if the current record meets the filter condition; otherwise, it should evaluate to false (.F.). ##DBSETINDEX()## ---------------------------------------------------------------- DBSETINDEX(<cOrderBagName>) --> NIL <cOrderBagName> is a character value that specifies the filename of the index file (index bag) to be opened. DBSETINDEX() is a database function that adds the contents of an Order Bag into the Order List of the current work area. Any Orders already associated with the work area continue to be active. If the newly opened Order Bag is the only Order associated with the work area, it becomes the controlling Order; otherwise, the controlling Order remains unchanged. If the Order Bag contains more than one Order, and there are no other Orders associated with the work area, the first Order in the new Order Bag becomes the controlling Order. ##DBSETORDER()## ---------------------------------------------------------------- DBSETORDER(<nOrderNum>) --> NIL <nOrderNum> is a numeric value that specifies which of the active indexes is to be the controlling index. DBSETORDER() controls which of the active Alias' active indexes is the controlling index. ##DBSETRELATION()## ---------------------------------------------------------------- DBSETRELATION(<nArea> | <cAlias>, <bExpr>, [<cExpr>]) --> NIL <nArea> is a numeric value that specifies the work area number of the child work area. <cAlias> is a character value that specifies the alias of the child work area. <bExpr> is a code block that expresses the relational expression in executable form. <cExpr> is an optional character value that expresses the relational expression in textual form. If <cExpr> is omitted, the DBRELATION() function returns an empty string for the relation. DBSETRELATION() relates the work area specified by <nArea> or <cAlias> (the child work area), to the current work area (the parent work area). Any existing relations remain active. ##DBSKIP()## ---------------------------------------------------------------- DBSKIP([<nRecords>]) --> NIL <nRecords> is the number of logical records to move, relative to the current record. A positive value means to skip forward, and a negative value means to skip backward. If <nRecords> is omitted, a value of 1 is assumed. DBSKIP() moves either forward or backward relative to the current record. Attempting to skip forward beyond the last record positions the work area to LASTREC() + 1 and EOF() returns true (.T.). Attempting to skip backward beyond the first record positions the work area to the first record and BOF() returns true (.T.). ##DBSTRUCT()## ---------------------------------------------------------------- DBSTRUCT() --> aStruct DBSTRUCT() returns the structure of the current database file in an array whose length is equal to the number of fields in the database file. Each element of the array is a subarray containing information for one field. The subarrays have the following format: <aStruct[n][1]> cName <aStruct[n][2]> cType <aStruct[n][3]> nLength <aStruct[n][4]> nDecimals If there is no database file in USE in the current work area, DBSTRUCT() returns an empty array ({}). ##DBUNLOCK()## ---------------------------------------------------------------- DBUNLOCK() --> NIL DBUNLOCK() releases any record or file locks obtained by the current process for the current work area. DBUNLOCK() is only meaningful on a shared database in a network environment. ##DBUNLOCKALL()## ---------------------------------------------------------------- DBUNLOCKALL() --> NIL DBUNLOCKALL() releases any record or file locks obtained by the current process for any work area. DBUNLOCKALL() is only meaningful on a shared database in a network environment. ##DBUSEAREA()## ---------------------------------------------------------------- DBUSEAREA( [<lNewArea>], [<cDriver>], <cName>, [<xcAlias>], [<lShared>], [<lReadonly>]) --> NIL <lNewArea> is an optional logical value. A value of true (.T.) selects the lowest numbered unoccupied work area as the current work area before the use operation. If <lNewArea> is false (.F.) or omitted, the current work area is used; if the work area is occupied, it is closed first. <cDriver> is an optional character value. If present, it specifies the name of the database driver which will service the work area. If <cDriver> is omitted, the current default driver is used. <cName> specifies the name of the database (.dbf) file to be opened. <xcAlias> is an optional character value. If present, it specifies the alias to be associated with the work area. The alias must constitute a valid identifier. A valid <xcAlias> may be any legal identifier (i.e., it must begin with an alphabetic character and may contain numeric or alphabetic characters and the underscore). If <xcAlias> is omitted, a default alias is constructed from <cName>. <lShared> is an optional logical value. If present, it specifies whether the database (.dbf) file should be accessible to other processes on a network. A value of true (.T.) specifies that other processes should be allowed access; a value of false (.F.) specifies that the current process is to have exclusive access. If <lShared> is omitted, the current global _SET_EXCLUSIVE setting determines whether shared access is allowed. <lReadonly> is an optional logical value that specifies whether updates to the work area are prohibited. A value of true (.T.) prohibits updates; a value of false (.F.) permits updates. A value of true (.T.) also permits read-only access to the specified database (.dbf) file. If <lReadonly> is omitted, the default value is false (.F.). DBUSEAREA() opens the specified database (.dbf). ##DBDELETE()## ---------------------------------------------------------------- DELETED() --> lDeleted DELETED() returns true (.T.) if the current record is marked for deletion; otherwise, it returns false (.F.). If there is no database file in USE in the current work area, DELETED() returns false (.F.). ##DESCEND()## ---------------------------------------------------------------- DESCEND(<exp>) --> ValueInverted <exp> is any valid expression of character, date, logical, or numeric type. DESCEND() returns an inverted expression of the same data type as the <exp>, except for dates which return a numeric value. A DESCEND() of CHR(0) always returns CHR(0). ##DEVOUT()## ---------------------------------------------------------------- DEVice OUTput DEVOUT(<exp>, [<cColorString>]) --> NIL <exp> is the value to display. <cColorString> is an optional argument that defines the display color of <exp>. DEVOUT() is a full-screen display function that writes the value of a single expression to the current device at the current cursor or printhead position. ##DEVOUTPICT()## ---------------------------------------------------------------- DEVice OUTput PICTure DEVOUTPICT(<exp>, <cPicture>, [<cColorString>]) --> NIL <exp> is the value to display. <cPicture> defines the formatting control for the display of <exp>. <cColorString> is an optional argument that defines the display color of <exp>. DEVOUTPICT() is a full-screen display function that writes the value of a single expression to the current device at the current cursor or printhead position. ##DEVPOS()## ---------------------------------------------------------------- DEVice POSition DEVPOS(<nRow>, <nCol>) --> NIL <nRow>, <nCol> are the new row and column positions of the cursor or printhead. DEVPOS() is an environment function that moves the screen or printhead depending on the current DEVICE. ##DIRECTORY()## ---------------------------------------------------------------- DIRECTORY(<cDirSpec>, [<cAttributes>]) --> aDirectory <cDirSpec> identifies the drive, directory and file specification for the directory search. Wildcards are allowed in the file specification. If <cDirSpec> is omitted, the default value is *.*. <cAttributes> specifies inclusion of files with special attributes in the returned information. <cAttributes> is a string containing one or more of the following characters: H Include hidden files S Include system files D Include directories V Search for the DOS volume label only Normal files are always included in the search, unless you specify V. DIRECTORY() returns an array of subarrays, with each subarray containing information about each file matching <cDirSpec>. The subarray has the following structure: <aDirectory[N][1]> cName <aDirectory[N][2]> cSize <aDirectory[N][3]> dDate <aDirectory[N][4]> cTime <aDirectory[N][5]> cAttributes If no files are found matching <cDirSpec> or if <cDirSpec> is an illegal path or file specification, DIRECTORY() returns an empty ({}) array. ##DISKSPACE()## ---------------------------------------------------------------- DISKSPACE([<nDrive>]) --> nBytes <nDrive> is the number of the drive to query, where one is drive A, two is B, three is C, etc. The default is the current DOS drive if <nDrive> is omitted or specified as zero. DISKSPACE() returns the number of bytes of empty space on the specified disk drive as an integer numeric value. ##DISPBOX()## ---------------------------------------------------------------- DISPlay BOX DISPBOX(<nTop>, <nLeft>, <nBottom>, <nRight>, [<cnBoxString>], [<cColorString>]) --> NIL <nTop>, <nLeft>, <nBottom>, <nRight> define the coordinates of the box. <cnBoxString> is a numeric or character expression that defines the border characters of the box. If specified as a numeric expression, a value of 1 displays a single-line box and a value of 2 displays a double-line box. All other numeric values display a single-line box. If <cnBoxString> is a character expression, it specifies the characters to be used in drawing the box. This is a string of eight border characters and a fill character. <cColorString> defines the display color of the box that is drawn. DISPBOX() is a screen function that draws a box at the specified display coordinates in the specified color. ##DISPOUT()## ---------------------------------------------------------------- DISPlay OUT DISPOUT(<exp>, [<cColorString>]) --> NIL <exp> is the value to display. <cColorString> is an optional argument that defines the display color of <exp>. <cColorString> is a character expression containing the standard color setting. DISPOUT() is a simple output function that writes the value of a single expression to the display at the current cursor position. This function ignores the SET DEVICE setting; output always goes to the screen. ##DOW()## ---------------------------------------------------------------- Day Of Week DOW(<dDate>) --> nDay <dDate> is a date value to convert. DOW() returns the day of the week as a number between zero and seven. The first day of the week is one (Sunday) and the last day is seven (Saturday). If <dDate> is empty, DOW() returns zero. ##DTOC()## ---------------------------------------------------------------- Dat TO Character DTOC(<dDate>) --> cDate <dDate> is the date value to convert. DTOC() returns a character string representation of a date value. The return value is formatted in the current date format. A null date returns a string of spaces equal in length to the current date format. ##DTOS()## ---------------------------------------------------------------- Dat TO Sort DTOS(<dDate>) --> cDate <dDate> is the date value to convert. DTOS() returns a character string eight characters long in the form, yyyymmdd. When <dDate> is a null date (CTOD("")), DTOS() returns a string of eight spaces. ##EMPTY()## ---------------------------------------------------------------- EMPTY(<exp>) --> lEmpty <exp> is an expression of any data type. EMPTY() returns true (.T.) if the expression results in an empty value; otherwise, it returns false (.F.): Array {} Character/Memo Spaces, tabs, CR/LF, or "" Numeric 0 Date CTOD("") Logical .F. NIL NIL ##EOF()## ---------------------------------------------------------------- End Of File EOF() --> lBoundary EOF() returns true (.T.) when an attempt is made to move the record pointer beyond the last logical record in a database file; otherwise, it returns false (.F.). If there is no database file open in the current work area, EOF() returns false (.F.). If the current database file contains no records, EOF() returns true (.T.). ##EVAL()## ---------------------------------------------------------------- code block EVALuation EVAL(<bBlock>, [<BlockArg list>]) --> LastBlockValue <bBlock> is the code block to evaluate. <BlockArg list> is a list of arguments to send to the code block before it is evaluated. To execute or evaluate a code block, call EVAL() with the block value and any parameters. The parameters are supplied to the block when it is executed. Code blocks may be a series of expressions separated by commas. When a code block is evaluated, the returned value is the value of the last expression in the block. ##EXP()## ---------------------------------------------------------------- EXPonent EXP(<nExponent>) --> nAntilogarithm <nExponent> is the natural logarithm for which a numeric value is to be calculated. EXP() returns a numeric value that is equivalent to the value e raised to the specified power. ##FCLOSE()## ---------------------------------------------------------------- File CLOSE FCLOSE(<nHandle>) --> lError <nHandle> is the file handle obtained previously from FOPEN() or FCREATE(). FCLOSE() is a low-level file function that closes binary files and forces the associated DOS buffers to be written to disk. If the operation fails, FCLOSE() returns false (.F.). FERROR() can then be used to determine the reason for the failure. ##FCOUNT()## ---------------------------------------------------------------- Field COUNT FCOUNT() --> nFields FCOUNT() returns the number of fields in the database file in the active Alias as an integer numeric value. If there is no database file open, FCOUNT() returns zero. ##FCREATE()## ---------------------------------------------------------------- Field CREATE FCREATE(<cFile>, [<nAttribute>]) --> nHandle <cFile> is the name of the file to create. If the file already exists, its length is truncated to zero without warning. <nAttribute> is the binary file attribute, the default value is zero. <nAttribute> = 0 Normal (default) <nAttribute> = 1 Read-only <nAttribute> = 2 Hidden <nAttribute> = 4 System FCREATE() returns the DOS file handle number of the new binary file in the range of zero to 65,535. If an error occurs, FCREATE() returns -1 and FERROR() is set to indicate an error code. ##FERASE()## ---------------------------------------------------------------- File ERASE FERASE(<cFile>) --> nSuccess <cFile> is the name (with or without path) of the file to be deleted from disk. FERASE() is a file function that deletes a specified file from disk. FERASE() returns -1 if the operation fails and zero if it succeeds. ##FERROR()## ---------------------------------------------------------------- File ERROR FERROR() --> nErrorCode FERROR() returns the DOS error from the last file operation as an integer numeric value. If there is no error, FERROR() returns zero. <nErrorCode> = 0 Successful <nErrorCode> = 2 File not found <nErrorCode> = 3 Path not found <nErrorCode> = 4 Too many files open <nErrorCode> = 5 Access denied <nErrorCode> = 6 Invalid handle <nErrorCode> = 8 Insufficient memory <nErrorCode> = 15 Invalid drive specified <nErrorCode> = 19 Attempted to write to a write-protected disk <nErrorCode> = 21 Drive not ready <nErrorCode> = 23 Data CRC error <nErrorCode> = 29 Write fault <nErrorCode> = 30 Read fault <nErrorCode> = 32 Sharing violation <nErrorCode> = 33 Lock Violation FERROR() is a low-level file function that indicates a DOS error after a file function is used. ##FIELDBLOCK()## ---------------------------------------------------------------- FIELDBLOCK(<cFieldName>) --> bFieldBlock <cFieldName> is the name of the field to which the set-get block will refer. FIELDBLOCK() returns a code block that, when evaluated, sets (assigns) or gets (retrieves) the value of the given field. If <cFieldName> does not exist in the current work area, FIELDBLOCK() returns NIL. ##FIELDGET()## ---------------------------------------------------------------- FIELDGET(<nField>) --> ValueField <nField> is the ordinal position of the field in the record structure for the current work area. FIELDGET() returns the value of the specified field. If <nField> does not correspond to the position of any field in the current database file, FIELDGET() returns NIL. ##FIELDNAME()## ---------------------------------------------------------------- FIELDNAME(<nPosition>) --> cFieldName <nPosition> is the position of a field in the database file structure. FIELDNAME() returns the name of the specified field as a character string. If <nPosition> does not correspond to an existing field in the current database file or if no database file is open in the current work area, FIELDNAME() returns a null string (""). ##FIELDPOS()## ---------------------------------------------------------------- FIELD POSition FIELDPOS(<cFieldName>) --> nFieldPos <cFieldName> is the name of a field in the current or specified work area. FIELDPOS() returns the position of the specified field within the list of fields associated with the current or specified work area. If the current work area has no field with the specified name, FIELDPOS() returns zero. ##FIELDPUT()## ---------------------------------------------------------------- FIELDPUT(<nField>, <expAssign>) --> ValueAssigned <nField> is the ordinal position of the field in the current database file. <expAssign> is the value to assign to the given field. The data type of this expression must match the data type of the designated field variable. FIELDPUT() is a database function that assigns <expAssign> to the field at ordinal position <nField> in the current work area. This function allows you to set the value of a field using its position within the database file structure rather than its field name. ##FIELDWBLOCK()## ---------------------------------------------------------------- FIELD Work area BLOCK FIELDWBLOCK(<cFieldName>, <nWorkArea>) --> bFieldWBlock <cFieldName> is the name of the field specified as a character string. <nWorkArea> is the work area number where the field resides specified as a numeric value. FIELDWBLOCK() returns a code block that, when evaluated, sets (assigns) or gets (retrieves) the value of <cFieldName> in the work area designated by <nWorkArea>. If <cFieldName> does not exist in the specified work area, FIELDWBLOCK() returns NIL. ##FILE()## ---------------------------------------------------------------- FILE(<cFilespec>) --> lExists <cFilespec> is in the current default directory and path. It is a standard file specification that can include the wildcard characters * and ? as well as a drive and path reference. FILE() returns true (.T.) if there is a match for any file matching the <cFilespec> pattern; otherwise, it returns false (.F.). ##FLOCK()## ---------------------------------------------------------------- File LOCK FLOCK() --> lSuccess FLOCK() tries to lock the active Alias and returns true (.T.) if it succeeds; otherwise, it returns false (.F.). ##FOPEN()## ---------------------------------------------------------------- File OPEN FOPEN(<cFile>, [<nMode>]) --> nHandle <cFile> is the name of the file to open including the path if there is one. <nMode> is the requested DOS open mode indicating how the opened file is to be accessed. The open mode is composed of the sum of two elements: the Open mode and the Sharing mode. Open mode: 0 Open for reading (default) 1 Open for writing 2 Open for reading or writing Sharing Mode: 0 Compatibility mode (default) 16 Exclusive use 32 Prevent others from writing 48 Prevent others from reading 64 Allow others to read or write FOPEN() returns the file handle of the opened file in the range of zero to 65,535. If an error occurs, FOPEN() returns -1. ##FOUND()## ---------------------------------------------------------------- FOUND() --> lSuccess FOUND() returns true (.T.) if the last search command was successful; otherwise, it returns false (.F.). ##FREAD()## ---------------------------------------------------------------- File READ FREAD(<nHandle>, @<cBufferVar>, <nBytes>) --> nBytes <nHandle> is the file handle obtained from FOPEN(), FCREATE(), or predefined by DOS. <cBufferVar> is the name of an existing and initialized character variable used to store data read from the specified file. The length of this variable must be greater than or equal to <nBytes>. <cBufferVar> must be passed by reference and, therefore, must be prefaced by the pass-by-reference operator (@). <nBytes> is the number of bytes to read into the buffer. FREAD() tries to read <nBytes> of the binary file <nHandle> inside <cBufferVar>. It returns the number of bytes successfully read as an integer numeric value. A return value less than <nBytes> or zero indicates end of file or some other read error. ##FREADSTR()## ---------------------------------------------------------------- File READ STRing FREADSTR(<nHandle>, <nBytes>) --> cString <nHandle> is the file handle obtained from FOPEN(), FCREATE(), or predefined by DOS. <nBytes> is the number of bytes to read, beginning at the current DOS file pointer position. FREADSTR() returns a character string up to 65,535 (64K) bytes. A null return value ("") indicates an error or end of file. FREADSTR() is a low-level file function that reads characters from an open binary file beginning with the current DOS file pointer position. Characters are read up to <nBytes> or until a null character (CHR(0)) is encountered. All characters are read including control characters except for CHR(0). The file pointer is then moved forward <nBytes>. If <nBytes> is greater than the number of bytes from the pointer position to the end of the file, the file pointer is positioned to the last byte in the file. ##FRENAME()## ---------------------------------------------------------------- File RENANE FRENAME(<cOldFile>, <cNewFile>) --> nSuccess <cOldFile> is the name of the file to rename, including the file extension. A drive letter and/or path name may also be included as part of the filename. <cNewFile> is the new name of the file, including the file extension. A drive letter and/or path name may also be included as part of the name. FRENAME() returns -1 if the operation fails and zero if it succeeds. ##FSEEK()## ---------------------------------------------------------------- File SEEK FSEEK(<nHandle>, <nOffset>, [<nOrigin>]) --> nPosition <nHandle> is the file handle obtained from FOPEN(), FCREATE(), or predefined by DOS. <nOffset> is the number of bytes to move the file pointer from the position defined by <nOrigin>. It can be a positive or negative number. A positive number moves the pointer forward, and a negative number moves the pointer backward in the file. <nOrigin> defines the starting location of the file pointer before FSEEK() is executed. The default value is zero, representing the beginning of file. If <nOrigin> is the end of file, <nOffset> must be zero or negative. <nOrigin> = 0 Seek from beginning of file <nOrigin> = 1 Seek from the current pointer position <nOrigin> = 2 Seek from end of file FSEEK() returns the new position of the file pointer relative to the beginning of file (position 0) as an integer numeric value. This value is without regard to the original position of the file pointer. FSEEK() is a low-level file function that moves the file pointer forward or backward in an open binary file without actually reading the contents of the specified file. The beginning position and offset are specified as function arguments, and the new file position is returned. ##FWRITE()## ---------------------------------------------------------------- File WRITE FWRITE(<nHandle>, <cBuffer>, [<nBytes>]) --> nBytesWritten <nHandle> is the file handle obtained from FOPEN(), FCREATE(), or predefined by DOS. <cBuffer> is the character string to write to the specified file. <nBytes> indicates the number of bytes to write beginning at the current file pointer position. If omitted, the entire content of <cBuffer> is written. FWRITE() returns the number of bytes written as an integer numeric value. If the value returned is equal to <nBytes>, the operation was successful. If the return value is less than <nBytes> or zero, either the disk is full or another error has occurred. ##GETENV()## ---------------------------------------------------------------- GET ENVironment GETENV(<cEnvironmentVariable>) --> cString <cEnvironmentVariable> is the name of the DOS environment variable. When specifying this argument, you can use any combination of upper and lowercase letters; GETENV() is not case- sensitive. GETENV() returns the contents of the specified DOS environment variable as a character string. If the variable cannot be found, GETENV() returns a null string (""). ##HARDCR()## ---------------------------------------------------------------- HARD Carriage Return HARDCR(<cString>) --> cConvertedString <cString> is the character string or memo field to convert. HARDCR() is a memo function that replaces all soft carriage returns (CHR(141)) with hard carriage returns (CHR(13)). It is used to display long character strings and memo fields containing soft carriage returns with console commands. ##HEADER()## ---------------------------------------------------------------- HEADER() --> nBytes HEADER() returns the number of bytes in the header of the current database file as an integer numeric value. If no database file is in use, HEADER() returns a zero (0). ##I2BIN()## ---------------------------------------------------------------- Integer to BINary I2BIN(<nInteger>) --> cBinaryInteger <nInteger> is an integer numeric value to convert. Decimal digits are truncated. I2BIN() returns a two-byte character string containing a 16-bit binary integer. ##IF()## ---------------------------------------------------------------- [I]IF(<lCondition>, <expTrue>, <expFalse>) --> Value <lCondition> is a logical expression to be evaluated. <expTrue> is the value, a condition-expression, of any data type, returned if <lCondition> is true (.T.). <expFalse> is the value, of any date type, returned if <lCondition> is false (.F.). This argument need not be the same data type as <expTrue>. IF() returns the evaluation of <expTrue> if <lCondition> evaluates to true (.T.) and <expFalse> if it evaluates to false (.F.). ##INDEXEXT()## ---------------------------------------------------------------- INDEX EXTention INDEXEXT() --> cExtension INDEXEXT() returns the default index file extension by determining which database driver is currently linked. ##INDEXKEY()## ---------------------------------------------------------------- INDEXKEY(<nOrder>) --> cKeyExp <nOrder> is the ordinal position of the index in the list of index files opened by the last USE...INDEX or SET INDEX TO command for the current work area. A zero value specifies the controlling index, without regard to its actual position in the list. INDEXKEY() returns the key expression of the specified index as a character string. If there is no corresponding index or if no database file is open, INDEXKEY() returns a null string (""). ##INDEXORD()## ---------------------------------------------------------------- INDEX ORDer INDEXORD() --> nOrder INDEXORD() returns an integer numeric value. The value returned is equal to the position of the controlling index in the list of open indexes for the current work area. A value of zero indicates that there is no controlling index and records are being accessed in natural order. If no database file is open, INDEXORD() will also return a zero. ##INKEY()## ---------------------------------------------------------------- INput KEY INKEY([<nSeconds>]) --> nInkeyCode <nSeconds> specifies the number of seconds INKEY() waits for a keypress. You can specify the value in increments as small as one-tenth of a second. Specifying zero halts the program until a key is pressed. If <nSeconds> is omitted, INKEY() does not wait for a keypress. INKEY() returns an integer numeric value from -39 to 386, identifying the key extracted from the keyboard buffer. If the keyboard buffer is empty, INKEY() returns zero. INKEY() returns values for all ASCII characters, function, Alt-function, Ctrl- function, Alt-letter, and Ctrl-letter key combinations. <nInkeyCode> = 5 [Up arrow], [Ctrl]+E <nInkeyCode> = 24 [Down arrow], [Ctrl]+X <nInkeyCode> = 19 [Left arrow], [Ctrl]+S <nInkeyCode> = 4 [Right arrow], [Ctrl]+D <nInkeyCode> = 1 [Home], [Ctrl]+A <nInkeyCode> = 6 [End], [Ctrl]+F <nInkeyCode> = 18 [PgUp], [Ctrl]+R <nInkeyCode> = 3 [PgDn], [Ctrl]+C <nInkeyCode> = 397 [Ctrl]+[Up arrow] <nInkeyCode> = 401 [Ctrl]+[Down arrow] <nInkeyCode> = 26 [Ctrl]+[Left arrow], [Ctrl]+Z <nInkeyCode> = 2 [Ctrl]+[Right arrow], [Ctrl]+B <nInkeyCode> = 29 [Ctrl]+[Home], [Ctrl]+] <nInkeyCode> = 23 [Ctrl]+[End], [Ctrl]+W <nInkeyCode> = 31 [Ctrl]+[PgUp], [Ctrl]+Hyphen <nInkeyCode> = 30 [Ctrl]+[PgDn], [Ctrl]+^ <nInkeyCode> = 408 [Alt]+[Up arrow] <nInkeyCode> = 416 [Alt]+[Down arrow] <nInkeyCode> = 411 [Alt]+[Left arrow] <nInkeyCode> = 413 [Alt]+[Right arrow] <nInkeyCode> = 407 [Alt]+[Home] <nInkeyCode> = 415 [Alt]+[End] <nInkeyCode> = 409 [Alt]+[PgUp] <nInkeyCode> = 417 [Alt]+[PgDn] <nInkeyCode> = 13 [Enter], [Ctrl]+M <nInkeyCode> = 32 Space bar <nInkeyCode> = 27 Esc, [Ctrl]+[ <nInkeyCode> = 10 [Ctrl]+[Enter] <nInkeyCode> = 379 [Ctrl]+Print Screen <nInkeyCode> = 309 [Ctrl]+? <nInkeyCode> = 284 [Alt]+[Enter] <nInkeyCode> = 387 [Alt]+Equals <nInkeyCode> = 257 [Alt]+Esc <nInkeyCode> = 422 Keypad [Alt]+[Enter] <nInkeyCode> = 399 Keypad [Ctrl]+5 <nInkeyCode> = 405 Keypad [Ctrl]+/ <nInkeyCode> = 406 Keypad [Ctrl]+* <nInkeyCode> = 398 Keypad [Ctrl]+- <nInkeyCode> = 400 Keypad [Ctrl]++ <nInkeyCode> = 5 Keypad [Alt]+5 <nInkeyCode> = 420 Keypad [Alt]+/ <nInkeyCode> = 311 Keypad [Alt]+* <nInkeyCode> = 330 Keypad [Alt]+- <nInkeyCode> = 334 Keypad [Alt]++ <nInkeyCode> = 22 [Ins], [Ctrl]+V <nInkeyCode> = 7 [Del], [Ctrl]+G <nInkeyCode> = 8 [Backspace], [Ctrl]+H <nInkeyCode> = 9 [Tab], [Ctrl]+I <nInkeyCode> = 271 [Shift]+[Tab] <nInkeyCode> = 402 [Ctrl]+[Ins] <nInkeyCode> = 403 [Ctrl]+[Del] <nInkeyCode> = 127 [Ctrl]+[Backspace] <nInkeyCode> = 404 [Ctrl]+[Tab] <nInkeyCode> = 418 [Alt]+[Ins] <nInkeyCode> = 419 [Alt]+[Del] <nInkeyCode> = 270 [Alt]+[Backspace] <nInkeyCode> = 421 [Alt]+[Tab] <nInkeyCode> = 1 [Ctrl]+A, [Home] <nInkeyCode> = 2 [Ctrl]+B, [Ctrl]+[Right arrow] <nInkeyCode> = 3 [Ctrl]+C, [PgDn], [Ctrl]+[ScrollLock] <nInkeyCode> = 4 [Ctrl]+D, [Right arrow] <nInkeyCode> = 5 [Ctrl]+E, [Up arrow] <nInkeyCode> = 6 [Ctrl]+F, [End] <nInkeyCode> = 7 [Ctrl]+G, [Del] <nInkeyCode> = 8 [Ctrl]+H, [Backspace] <nInkeyCode> = 9 [Ctrl]+I, [Tab] <nInkeyCode> = 10 [Ctrl]+J <nInkeyCode> = 11 [Ctrl]+K <nInkeyCode> = 12 [Ctrl]+L <nInkeyCode> = 13 [Ctrl]+M, Return <nInkeyCode> = 14 [Ctrl]+N <nInkeyCode> = 15 [Ctrl]+O <nInkeyCode> = 16 [Ctrl]+P <nInkeyCode> = 17 [Ctrl]+Q <nInkeyCode> = 18 [Ctrl]+R, [PgUp] <nInkeyCode> = 19 [Ctrl]+S, [Left arrow] <nInkeyCode> = 20 [Ctrl]+T <nInkeyCode> = 21 [Ctrl]+U <nInkeyCode> = 22 [Ctrl]+V, [Ins] <nInkeyCode> = 23 [Ctrl]+W, [Ctrl]+[End] <nInkeyCode> = 24 [Ctrl]+X, [Down arrow] <nInkeyCode> = 25 [Ctrl]+Y <nInkeyCode> = 26 [Ctrl]+Z, [Ctrl]+[Left arrow] <nInkeyCode> = 286 [Alt]+A <nInkeyCode> = 304 [Alt]+B <nInkeyCode> = 302 [Alt]+C <nInkeyCode> = 288 [Alt]+D <nInkeyCode> = 274 [Alt]+E <nInkeyCode> = 289 [Alt]+F <nInkeyCode> = 290 [Alt]+G <nInkeyCode> = 291 [Alt]+H <nInkeyCode> = 279 [Alt]+I <nInkeyCode> = 292 [Alt]+J <nInkeyCode> = 293 [Alt]+K <nInkeyCode> = 294 [Alt]+L <nInkeyCode> = 306 [Alt]+M <nInkeyCode> = 305 [Alt]+N <nInkeyCode> = 280 [Alt]+O <nInkeyCode> = 281 [Alt]+P <nInkeyCode> = 272 [Alt]+Q <nInkeyCode> = 275 [Alt]+R <nInkeyCode> = 287 [Alt]+S <nInkeyCode> = 276 [Alt]+T <nInkeyCode> = 278 [Alt]+U <nInkeyCode> = 303 [Alt]+V <nInkeyCode> = 273 [Alt]+W <nInkeyCode> = 301 [Alt]+X <nInkeyCode> = 277 [Alt]+Y <nInkeyCode> = 300 [Alt]+Z <nInkeyCode> = 376 [Alt]+1 <nInkeyCode> = 377 [Alt]+2 <nInkeyCode> = 378 [Alt]+3 <nInkeyCode> = 379 [Alt]+4 <nInkeyCode> = 380 [Alt]+5 <nInkeyCode> = 381 [Alt]+6 <nInkeyCode> = 382 [Alt]+7 <nInkeyCode> = 383 [Alt]+8 <nInkeyCode> = 384 [Alt]+9 <nInkeyCode> = 385 [Alt]+0 <nInkeyCode> = 28 F1, [Ctrl]+[Backslash] <nInkeyCode> = -1 F2 <nInkeyCode> = -2 F3 <nInkeyCode> = -3 F4 <nInkeyCode> = -4 F5 <nInkeyCode> = -5 F6 <nInkeyCode> = -6 F7 <nInkeyCode> = -7 F8 <nInkeyCode> = -8 F9 <nInkeyCode> = -9 F10 <nInkeyCode> = -40 F11 <nInkeyCode> = -41 F12 <nInkeyCode> = -20 [Ctrl]+F1 <nInkeyCode> = -21 [Ctrl]+F2 <nInkeyCode> = -22 [Ctrl]+F4 <nInkeyCode> = -23 [Ctrl]+F3 <nInkeyCode> = -24 [Ctrl]+F5 <nInkeyCode> = -25 [Ctrl]+F6 <nInkeyCode> = -26 [Ctrl]+F7 <nInkeyCode> = -27 [Ctrl]+F8 <nInkeyCode> = -28 [Ctrl]+F9 <nInkeyCode> = -29 [Ctrl]+F10 <nInkeyCode> = -44 [Ctrl]+F11 <nInkeyCode> = -45 [Ctrl]+F12 <nInkeyCode> = -30 [Alt]+F1 <nInkeyCode> = -31 [Alt]+F2 <nInkeyCode> = -32 [Alt]+F3 <nInkeyCode> = -33 [Alt]+F4 <nInkeyCode> = -34 [Alt]+F5 <nInkeyCode> = -35 [Alt]+F6 <nInkeyCode> = -36 [Alt]+F7 <nInkeyCode> = -37 [Alt]+F8 <nInkeyCode> = -38 [Alt]+F9 <nInkeyCode> = -39 [Alt]+F10 <nInkeyCode> = -46 [Alt]+F11 <nInkeyCode> = -47 [Alt]+F12 <nInkeyCode> = -10 [Shift]+F1 <nInkeyCode> = -11 [Shift]+F2 <nInkeyCode> = -12 [Shift]+F3 <nInkeyCode> = -13 [Shift]+F4 <nInkeyCode> = -14 [Shift]+F5 <nInkeyCode> = -15 [Shift]+F6 <nInkeyCode> = -16 [Shift]+F7 <nInkeyCode> = -17 [Shift]+F8 <nInkeyCode> = -18 [Shift]+F9 <nInkeyCode> = -19 [Shift]+F10 <nInkeyCode> = -42 [Shift]+F11 <nInkeyCode> = -43 [Shift]+F12 ##INT()## ---------------------------------------------------------------- INTeger INT(<nExp>) --> nInteger <nExp> is a numeric expression to convert to an integer. INT() is a numeric function that converts a numeric value to an integer by truncating all digits to the right of the decimal point. INT() is useful in operations where the decimal portion of a number is not needed. ##ISALPHA()## ---------------------------------------------------------------- ISALPHA(<cString>) --> lBoolean <cString> is the character string to examine. ISALPHA() returns true (.T.) if the first character in <cString> is alphabetic; otherwise, it returns false (.F.). ##ISCOLOR()## ---------------------------------------------------------------- ISCOLOR() | ISCOLOUR() --> lBoolean ISCOLOR() returns true (.T.) if there is a color graphics card installed; otherwise, it returns false (.F.). ##ISDIGIT()## ---------------------------------------------------------------- ISDIGIT(<cString>) --> lBoolean <cString> is the character string to examine. ISDIGIT() returns true (.T.) if the first character of the character string is a digit between zero and nine; otherwise, it returns false (.F.). ##ISLOWER()## ---------------------------------------------------------------- ISLOWER(<cString>) --> lBoolean <cString> is the character string to examine. ISLOWER() returns true (.T.) if the first character of the character string is a lowercase letter; otherwise, it returns false (.F.). ##ISPRINTER()## ---------------------------------------------------------------- ISPRINTER() --> lReady ISPRINTER() returns true (.T.) if LPT1 is ready; otherwise, it returns false (.F.). ##ISUPPER()## ---------------------------------------------------------------- ISUPPER(<cString>) --> lBoolean <cString> is the character string to examine. ISUPPER() returns true (.T.) if the first character is an uppercase letter; otherwise, it returns false (.F.). ##L2BIN()## ---------------------------------------------------------------- Long to BINary L2BIN(<nExp>) --> cBinaryInteger <nExp> is the numeric value to convert. Decimal digits are truncated. L2BIN() returns a four-byte character string formatted as a 32- bit binary integer. ##LASTKEY()## ---------------------------------------------------------------- LASTKEY() --> nInkeyCode LASTKEY() is a keyboard function that reports the INKEY() value of the last key fetched from the keyboard buffer by the INKEY() function, or a wait state. LASTKEY() retains its current value until another key is fetched from the keyboard buffer. See also: <inkey()> ##LASTREC()## ---------------------------------------------------------------- LAST RECord LASTREC() --> nRecords LASTREC() returns the number of physical records in the active Alias as an integer numeric value. ##LEFT()## ---------------------------------------------------------------- LEFT(<cString>, <nCount>) --> cSubString <cString> is a character string from which to extract characters. <nCount> is the number of characters to extract. LEFT() returns the leftmost <nCount> characters of <cString> as a character string. If <nCount> is negative or zero, LEFT() returns a null string (""). If <nCount> is larger than the length of the character string, LEFT() returns the entire string. ##LEN()## ---------------------------------------------------------------- LENgth LEN(<cString> | <aTarget>) --> nCount <cString> is the character string to count. <aTarget> is the array to count. LEN() returns the length of a character string or the number of elements in an array as an integer numeric value. ##LOG()## ---------------------------------------------------------------- LOG(<nExp>) --> nNaturalLog <nExp> is a numeric value greater than zero to convert to its natural logarithm. LOG() returns the natural logarithm as a numeric value. If <nExp> is less than or equal to zero, LOG() returns a numeric overflow (displayed as a row of asterisks). ##LOWER()## ---------------------------------------------------------------- LOWER(<cString>) --> cLowerString <cString> is a character string to convert to lowercase. LOWER() returns a copy of <cString> with all alphabetic characters converted to lowercase. ##LTRIM()## ---------------------------------------------------------------- Left TRIM LTRIM(<cString>) --> cTrimString <cString> is the character string to copy without leading spaces. LTRIM() returns a copy of <cString> with the leading spaces removed. ##LUPDATE()## ---------------------------------------------------------------- Last UPDATE LUPDATE() --> dModification LUPDATE() returns the date of last change to the open database file in the current work area. ##MAX()## ---------------------------------------------------------------- MAX(<nExp1>, <nExp2>) --> nLarger MAX(<dExp1>, <dExp2>) --> dLarger <nExp1>, nExp2> are the numeric values to compare. <dExp1>,<dExp2> are the date values to compare. MAX() returns the larger of the two arguments. The value returned is the same type as the arguments. ##MAXCOL()## ---------------------------------------------------------------- MAX COLumn MAXCOL() --> nColumn MAXCOL() returns the column number of the rightmost visible column for display purposes. ##MAXROW()## ---------------------------------------------------------------- MAXROW() --> nRow MAXROW() returns the row number of the bottommost visible row for display purposes. ##MEMOEDIT()## ---------------------------------------------------------------- MEMOEDIT([<cString>], [<nTop>], [<nLeft>], [<nBottom>], [<nRight>], [<lEditMode>], [<cUserFunction>], [<nLineLength>], [<nTabSize>], [<nTextBufferRow>], [<nTextBufferColumn>], [<nWindowRow>], [<nWindowColumn>]) --> cTextBuffer <cString> is the character string or memo field to copy to the MEMOEDIT() text buffer. <nTop>, <nLeft>, <nBottom>, <nRight> are window coordinates. The default coordinates are 0, 0, MAXROW(), and MAXCOL(). <lEditMode> determines whether the text buffer can be edited or merely displayed. If not specified, the default value is true (.T.). <cUserFunction> is the name of a user-defined function that executes when the user presses a key not recognized by MEMOEDIT() and when no keys are pending in the keyboard buffer. <nLineLength> determines the length of lines displayed in the MEMOEDIT() window. If a line is greater than <nLineLength>, it is word wrapped to the next line in the MEMOEDIT() window. The default line length is (<nRight> - <nLeft>). <nTabSize> determines the size of a tab character to insert when the user presses Tab. The default is four. <nTextBufferRow>, <nTextBufferColumn> define the display position of the cursor within the text buffer when MEMOEDIT() is invoked. <nTextBufferRow> begins with one and <nTextBufferColumn> begins with zero. Default is the beginning of MEMOEDIT() window. <nWindowRow>, <nWindowColumn> define the initial position of the cursor within the MEMOEDIT() window. Row and column positions begin with zero. If these arguments are not specified, the initial window position is row zero and the current cursor column position. MEMOEDIT() is a user interface and general purpose text editing function that edits memo fields and long character strings. Editing occurs within a specified window region placed anywhere on the screen. [Uparrow]/[Ctrl]+E Move up one line [Dnarrow]/[Ctrl]+X Move down one line [Leftarrow]/[Ctrl]+S Move left one character [Rightarrow]/[Ctrl]+D Move right one character [Ctrl]-[Leftarrow]/[Ctrl]+A Move left one word [Ctrl]-[Rightarrow]/[Ctrl]+F Move right one word [Home] Move to beginning of current line [End] Move to end of current line [Ctrl]+[Home] Move to beginning of current window [Ctrl]+[End] Move to end of current window [PgUp] Move to previous edit window [PgDn] Move to next edit window [Ctrl]+[PgUp] Move to beginning of memo [Ctrl]+[PgDn] Move to end of memo [Return] Move to beginning of next line [Delete] Delete character at cursor [Backspace] Delete character to left of cursor [Tab] Insert tab character or spaces Printable characters Insert character [Ctrl]+Y Delete the current line [Ctrl]+T Delete word right [Ctrl]+B Reform paragraph [Ctrl]+V/[Ins] Toggle insert mode [Ctrl]+W Finish editing with save [Esc] Abort edit and return original ##MEMOLINE()## ---------------------------------------------------------------- MEMOLINE(<cString>, [<nLineLength>], [<nLineNumber>], [<nTabSize>], [<lWrap>]) --> cLine <cString> is the memo field or character string from which to extract a line of text. <nLineLength> specifies the number of characters per line and can be between four and 254. If not specified, the default line length is 79. <nLineNumber> is the line number to extract. If not specified, the default value is one. <nTabSize> defines the tab size. If not specified, the default value is four. <lWrap> toggles word wrap on and off. Specifying true (.T.) toggles word wrap on; false (.F.) toggles it off. If not specified, the default value is true (.T.). MEMOLINE() returns the line of text specified by <nLineNumber> in <cString> as a character string. If the line has fewer characters than the indicated length, the return value is padded with blanks. If the line number is greater than the total number of lines in <cString>, MEMOLINE() returns a null string (""). If <lWrap> is true (.T.) and the indicated line length breaks the line in the middle of a word, that word is not included as part of the return value but shows up at the beginning of the next line extracted with MEMOLINE(). If <lWrap> is false (.F.), MEMOLINE() returns only the number of characters specified by the line length. The next line extracted by MEMOLINE() begins with the character following the next hard carriage return, and all intervening characters are not processed. ##MEMOREAD()## ---------------------------------------------------------------- MEMOREAD(<cFile>) --> cString <cFile> is the name of the file to read from disk. It must include an extension if there is one, and can optionally include a path. MEMOREAD() returns the contents of a text file as a character string. ##MEMORY()## ---------------------------------------------------------------- MEMORY(<nExp>) --> nKbytes <nExp> is a numeric value that determines the type of value MEMORY() returns. MEMORY() returns an integer numeric value representing the amount of memory available. MEMORY(0) --> Estimated total space available for character values MEMORY(1) --> Largest contiguous block available for character values MEMORY(2) --> Area available for RUN commands ##MEMOTRAN()## ---------------------------------------------------------------- MEMO TRANslate MEMOTRAN(<cString>, [<cReplaceHardCR>], [<cReplaceSoftCR>]) --> cNewString <cString> is the character string or memo field to search. <cReplaceHardCR> is the character to replace a hard carriage return/linefeed pair with. If not specified, the default value is a semicolon (;). <cReplaceSoftCR> is the character to replace a soft carriage return/linefeed pair with. If not specified, the default value is a space. MEMOTRAN() returns a copy of <cString> with the specified carriage return/linefeed pairs replaced. ##MEMOWRIT()## ---------------------------------------------------------------- MEMO WRITe MEMOWRIT(<cFile>, <cString>) --> lSuccess <cFile> is the name of the target disk file including the file extension and optional path and drive designator. <cString> is the character string or memo field to write to <cFile>. MEMOWRIT() is a memo function that writes a character string or memo field to a disk file. If a path is not specified, MEMOWRIT() writes <cFile> to the current DOS directory and not the current DEFAULT directory. If <cFile> already exists, it is overwritten. MEMOWRIT() returns true (.T.) if the writing operation is successful; otherwise, it returns false (.F.). ##MEMVARBLOCK()## ---------------------------------------------------------------- MEMVARBLOCK(<cMemvarName>) --> bMemvarBlock <cMemvarName> is the name of the variable referred to by the set-get block, specified as a character string. MEMVARBLOCK() returns a code block that when evaluated sets (assigns) or gets (retrieves) the value of the given memory variable. If <cMemvarName> does not exist, MEMVARBLOCK() returns NIL. ##MIN()## ---------------------------------------------------------------- MIN(<nExp1>, <nExp2>) --> nSmaller MIN(<dExp1>, <dExp2>) --> dSmaller <nExp1>, <nExp2> are the numeric values to compare. <dExp1>, <dExp2> are the date values to compare. MIN() returns the smaller of the two arguments. The value returned is the same data type as the arguments. ##MLCOUNT()## ---------------------------------------------------------------- Memo Line COUNT MLCOUNT(<cString>, [<nLineLength>], [<nTabSize>], [<lWrap>]) --> nLines <cString> is the character string or memo field to count. <nLineLength> specifies the number of characters per line and can range from four to 254. If not specified, the default line length is 79. <nTabSize> defines the tab size. If not specified, the default value is four. <lWrap> toggles word wrap on and off. Specifying true (.T.) toggles word wrap on; false (.F.) toggles it off. If not specified, the default value is true (.T.). MLCOUNT() returns the number of lines in <cString> depending on the <nLineLength>, the <nTabSize>, and whether word wrapping is on or off. ##MLCTOPOS()## ---------------------------------------------------------------- Memo Line Column TO POSition MLCTOPOS(<cText>, <nWidth>, <nLine>, <nCol>, [<nTabSize>], [<lWrap>]) --> nPosition <cText> is the text string to scan. <nWidth> is the line length formatting width. <nLine> is the line number counting from 1. <nCol> is the column number counting from 0. <nTabSize> is the number of columns between tab stops. If not specified, the default is 4. <lWrap> is the word wrap flag. If not specified, the default is true (.T.). MLCTOPOS() returns the byte position within <cText> counting from 1. ##MLPOS()## ---------------------------------------------------------------- Memo Line POSition MLPOS(<cString>, <nLineLength>, <nLine>, [<nTabSize>], [<lWrap>]) --> nPosition <cString> is a character string or memo field. <nLineLength> specifies the number of characters per line. <nLine> specifies the line number. <nTabSize> defines the tab size. The default is four. <lWrap> toggles word wrap on and off. Specifying true (.T.) toggles word wrap on, and false (.F.) toggles it off. The default is true (.T.). MLPOS() returns the character position of <nLine> in <cString> as an integer numeric value. If <nLine> is greater than the number of lines in <cString>, MLPOS() returns the length of <cString>. ##MONTH()## ---------------------------------------------------------------- MONTH(<dDate>) --> nMonth <dDate> is the date value to convert. MONTH() returns an integer numeric value in the range of zero to 12. Specifying a null date (CTOD("")) returns zero. ##MPOSTOLC()## ---------------------------------------------------------------- Memo POSition TO Line Column MPOSTOLC(<cText>, <nWidth>, <nPos>, [<nTabSize>], [<lWrap>]) --> aLineColumn <cText> is a text string. <nWidth> is the length of the formatted line. <nPos> is the byte position within text counting from one. <nTabSize> is the number of columns between tab stops. If not specified, the default is four. <lWrap> is the word wrap flag. If not specified, the default is true (.T.). MPOSTOLC() returns an array containing the line and the column values for the specified byte position, <nPos>. MPOSTOLC() is a memo function that determines the formatted line and column corresponding to a particular byte position within <cText>. Note that the line number returned is one-relative, the column number is zero-relative. This is compatible with MEMOEDIT(). <nPos> is one-relative, compatible with AT(), RAT(), and other string functions. ##NETERR()## ---------------------------------------------------------------- NRT ERRor NETERR([<lNewError>]) --> lError <lNewError> if specified sets the value returned by NETERR() to the specified status. <lNewError> can be either true (.T.) or false (.F.). Setting NETERR() to a specified value allows the runtime error handler to control the way certain file errors are handled. NETERR() returns true (.T.) if a USE or APPEND BLANK fails. The initial value of NETERR() is false (.F.). If the current process is not running under a network operating system, NETERR() always returns false (.F.). ##NETNAME()## ---------------------------------------------------------------- NETNAME() --> cWorkstationName NETNAME() returns the workstation identification as a character string up to 15 characters in length. If the workstation identification was never set or the application is not operating under the IBM PC Network, it returns a null string (""). ##NEXTKEY()## ---------------------------------------------------------------- NEXTKEY() --> nInkeyCode NEXTKEY() returns an integer numeric value ranging from -39 to 386. If the keyboard buffer is empty, NEXTKEY() returns zero. If SET TYPEAHEAD is zero, NEXTKEY() always returns zero. NEXTKEY() is like the INKEY() function, but differs in one fundamental respect. INKEY() removes the pending key from the keyboard buffer and updates LASTKEY() with the value of the key. NEXTKEY(), by contrast, reads, but does not remove the key from the keyboard buffer and does not update LASTKEY(). See also: <inkey()> ##NOSNOW()## ---------------------------------------------------------------- NOSNOW(<lToggle>) --> NIL <lToggle> is a logical value that toggles the current state of snow suppression. A value of true (.T.) enables the snow suppression on, while a value of false (.F.) disables snow suppression. NOSNOW() is used to suppress snow on CGA monitors. ##ORDBAGEXT()## ---------------------------------------------------------------- ORDBAGEXT() --> cBagExt ORDBAGEXT() returns a character expression that is the default Order Bag extension of the current work area. cBagExt is determined by the RDD active in the current work area. ##ORDBAGNAME()## ---------------------------------------------------------------- ORDBAGNAME(<nOrder> | <cOrderName>) --> cOrderBagName <nOrder> is an integer that identifies the position in the Order List of the target Order whose Order Bag name is sought. <cOrderName> is a character string that represents the name of the target Order whose Order Bag name is sought. ORDBAGNAME() returns a character string, the Order Bag name of the specific Order. ##ORDCREATE()## ---------------------------------------------------------------- ORDCREATE(<cOrderBagName>,[<cOrderName>], <cExpKey>, [<bExpKey>], [<lUnique>]) --> NIL <cOrderBagName> is the name of a disk file containing one or more Orders. <cOrderName> is the name of the Order to be created. <cExpKey> is an expression that returns the key value to place in the Order for each record in the current work area. The maximum length of the index key expression is determined by the database driver. <bExpKey> is a code block that evaluates to a key value that is placed in the Order for each record in the current work area. <lUnique> specifies whether a unique Order is to be created. Default is the current global _SET_UNIQUE setting. ORDCREATE() is an Order management function that creates an Order in the current work area. It works like DBCREATEINDEX() except that it lets you create Orders in RDDs that recognize multiple- Order Bags. ##ORDDESTROY()## ---------------------------------------------------------------- ORDDESTROY(<cOrderName> [, <cOrderBagName> ]) --> NIL <cOrderName> is the name of the Order to be removed from the current or specified work area. <cOrderBagName> is the name of a disk file containing one or more Orders. ORDDESTROY() is an Order management function that removes a specified Order from multiple-Order Bags. ORDDESTROY() is not supported for DBFNDX and DBFNTX. ##ORDFOR()## ---------------------------------------------------------------- ORDFOR(<cOrderName> | <nOrder> [, <cOrderBagName>]) --> cForExp <cOrderName> is the name of the target Order, whose cForExp is sought. <nOrder> is an integer that identifies the position in the Order List of the target Order whose cForExp is sought. <cOrderBagName> is the name of an Order Bag containing one or more Orders. ORDFOR() returns a character expression, cForExp, that represents the FOR condition of the specified Order. If the Order was not created using the FOR clause the return value will be an empty string (""). If the database driver does not support the FOR condition, it may either return an empty string ("") or raise an "unsupported function" error, depending on the driver. ##ORDKEY()## ---------------------------------------------------------------- ORDKEY(<cOrderName> | <nOrder> [, <cOrderBagName>]) --> cExpKey <cOrderName> is the name of an Order, a logical ordering of a database. <nOrder> is an integer that identifies the position in the Order List of the target Order whose cExpKey is sought. <cOrderBagName> is the name of a disk file containing one or more Orders. ORDKEY() is an Order management function that returns a character expression, cExpKey, that represents the key expression of the specified Order. ##ORDLISTADD()## ---------------------------------------------------------------- ORDLISTADD(<cOrderBagName> [, <cOrderName>]) --> NIL <cOrderBagName> is the name of a disk file containing one or more Orders. <cOrderName> the name of the specific Order from the Order Bag to be added to the Order List of the current work area. If you do not specify <cOrderName>, all orders in the Order Bag are added to the Order List of the current work area. ORDLISTADD() is an Order management function that adds the contents of an Order Bag , or a single Order in an Order Bag, to the Order List. Any Orders already associated with the work area continue to be active. If the newly opened Order Bag contains the only Order associated with the work area, it becomes the controlling Order; otherwise, the controlling Order remains unchanged. ##ORDLISTCLEAR()## ---------------------------------------------------------------- ORDLISTCLEAR() --> NIL ORDLISTCLEAR() is an Order management function that removes all Orders from the Order List for the current work area. ##ORDLISTREBUILD()## ---------------------------------------------------------------- ORDLISTREBUILD() --> NIL ORDLISTREBUILD() is an Order management function that rebuilds all the orders in the current Order List. ##ORDNAME()## ---------------------------------------------------------------- ORDNAME(<nOrder>[,<cOrderBagName>]) --> cOrderName <nOrder> is an integer that identifies the position in the Order List of the target Order whose database name is sought. <cOrderBagName> is the name of a disk file containing one or more Orders. ORDNAME() returns the name of the specified Order in the current Order List or the specified Order Bag if opened in the Current Order list. ##ORDNUMBER()## ---------------------------------------------------------------- ORDNUMBER(<cOrderName> [, <cOrderBagName>]) --> nOrderNo <cOrderName> the name of the specific Order whose position in the Order List is sought. <cOrderBagName> is the name of a disk file containing one or more Orders. ORDNUMBER() returns nOrderNo, an integer that represents the position of the specified Order in the Order List. ##ORDSETFOCUS()## ---------------------------------------------------------------- ORDSETFOCUS([<cOrderName> | <nOrder>] [,<cOrderBagName>]) --> cPrevOrderNameInFocus <cOrderName> is the name of the selected Order, a logical ordering of a database. <nOrder> is a number representing the position in the Order List of the selected Order. <cOrderBagName> is the name of a disk file containing one or more Orders. ORDSETFOCUS() is an Order management function that returns the Order Name of the previous controlling Order and optionally sets the focus to an new Order. ##OS()## ---------------------------------------------------------------- OS() --> cOsName OS() returns the operating system name as a character string. ##OUTERR()## ---------------------------------------------------------------- OUTput ERRor OUTERR(<exp list>) --> NIL <exp list> is a list of values to display and can consist of any combination of data types including memo. OUTERR() is identical to OUTSTD() except that it writes to the standard error device rather than the standard output device. Output sent to the standard error device bypasses the console and output devices as well as any DOS redirection. It is typically used to log error messages in a manner that will not interfere with the standard screen or printer output. ##OUTSTD()## ---------------------------------------------------------------- OUTput STanDard OUTSTD(<exp list>) --> NIL <exp list> is a list of values to display and can consist of any combination of data types including memo. OUTSTD() is a simple output function similar to QOUT(), except that it writes to the STDOUT device (instead of to the console output stream). ##PAD?()## ---------------------------------------------------------------- PADL(<exp>, <nLength>, [<cFillChar>]) --> cPaddedString PADC(<exp>, <nLength>, [<cFillChar>]) --> cPaddedString PADR(<exp>, <nLength>, [<cFillChar>]) --> cPaddedString <exp> is a character, numeric, or date value to pad with a fill character. <nLength> is the length of the character string to return. <cFillChar> is the character to pad <exp> with. If not specified, the default is a space character. PADC(), PADL(), and PADR() are character functions that pad character, date, and numeric values with a fill character to create a new character string of a specified length. PADC() centers <exp> within <nLength> adding fill characters to the left and right sides; PADL() adds fill characters on the left side; and PADR() adds fill characters on the right side. ##PCOL()## ---------------------------------------------------------------- Printed COLumn PCOL() --> nColumn PCOL() returns an integer numeric value representing the last printed column position, plus one. The beginning column position is zero. ##PROW()## ---------------------------------------------------------------- Printed ROW PROW() --> nRow PROW() returns an integer numeric value that represents the number of the current line sent to the printer. The beginning row position is zero. ##QOUT()## ---------------------------------------------------------------- QOUT([<exp list>]) --> NIL QQOUT([<exp list>]) --> NIL <exp list> is a comma-separated list of expressions (of any data type other than array or block) to display to the console. If no argument is specified and QOUT() is specified, a carriage return/linefeed pair is displayed. If QQOUT() is specified without arguments, nothing displays. QOUT() and QQOUT() are console functions. They display the results of one or more expressions to the console. QOUT() outputs carriage return and linefeed characters before displaying the results of <exp list>. QQOUT() displays the results of <exp list> at the current ROW() and COL() position. When QOUT() and QQOUT() display to the console, ROW() and COL() are updated. ##RAT()## ---------------------------------------------------------------- Right AT RAT(<cSearch>, <cTarget>) --> nPosition <cSearch> is the character string to locate. <cTarget> is the character string to search. RAT() returns the position of <cSearch> within <cTarget> as an integer numeric value, starting the search from the right. If <cSearch> is not found, RAT() returns zero. ##RDDLIST()## ---------------------------------------------------------------- RDDLIST([<nRDDType>]) --> aRDDList <nRDDType> is an integer that represents the type of the RDD you wish to list. <nRDDType> = 1 Full RDD implementation <nRDDType> = 2 Import/Export only driver. RDDLIST() returns a one-dimensional array of the RDD names registered with the application as <nRDDType>. ##RDDNAME()## ---------------------------------------------------------------- RDDNAME() --> cRDDName RDDNAME() returns a character string, cRDDName, the registered name of the active RDD in the current or specified work area. ##RDDSETDEFAULT()## ---------------------------------------------------------------- RDDSETDEFAULT([<cNewDefaultRDD>]) --> cPreviousDefaultRDD <cNewDefaultRDD> is a character string, the name of the RDD that is to be made the new default RDD in the application. RDDSETDEFAULT() is an RDD function that sets or returns the name of the previous default RDD driver and, optionally, sets the current driver to the new RDD driver specified by cNewDefaultRDD. ##READINSERT()## ---------------------------------------------------------------- READINSERT([<lToggle>]) --> lCurrentMode <lToggle> toggles the insert mode on or off. True (.T.) turns insert on, while false (.F.) turns insert off. The default is false (.F.) or the last user- selected mode in READ or MEMOEDIT(). READINSERT() returns the current insert mode state as a logical value. ##READMODAL()## ---------------------------------------------------------------- READMODAL(<aGetList>) --> NIL <aGetList> is an array containing a list of Get objects to edit. READMODAL() is like the READ command, but takes a GetList array as an argument and does not reinitialize the GetList array when it terminates. The GET system is implemented using a public array called GetList. Each time an @...GET command executes, it creates a Get object and adds to the currently visible GetList array. The standard READ command is preprocessed into a call to READMODAL() using the GetList array as its argument. ##READVAR()## ---------------------------------------------------------------- READVAR() --> cVarName READVAR() returns the name of the variable associated with the current Get object or the variable being assigned by the current MENU TO command as an uppercase character string. ##RECNO()## ---------------------------------------------------------------- RECord Number RECNO() --> nRecord RECNO() returns the current record number as an integer numeric value. If the work area contains a database file with zero records, RECNO() returns one, BOF() and EOF() both return true (.T.), and LASTREC() returns zero. If the record pointer is moved past the last record, RECNO() returns LASTREC() + 1 and EOF() returns true (.T.). If an attempt is made to move before the first record, RECNO() returns the record number of the first logical record in the database file and BOF() returns true (.T.). If no database file is open, RECNO() will return a zero. ##RECSIZE()## ---------------------------------------------------------------- RECord SIZE RECSIZE() --> nBytes RECSIZE() returns, as a numeric value, the record length, in bytes, of the database file open in the current work area. RECSIZE() returns zero if no database file is open. ##REPLICATE()## ---------------------------------------------------------------- REPLICATE(<cString>, <nCount>) --> cRepeatedString <cString> is the character string to repeat. <nCount> is the number of times to repeat <cString>. REPLICATE() returns a character string. Specifying a zero as the <nCount> argument returns a null string (""). ##RESTSCREEN()## ---------------------------------------------------------------- RESTore SCREEN RESTSCREEN([<nTop>], [<nLeft>], [<nBottom>], [<nRight>], <cScreen>) --> NIL <nTop>, <nLeft>, <nBottom>, <nRight> define the coordinates of the screen information contained in <cScreen>. If the <cScreen> was saved without coordinates to preserve the entire screen, no screen coordinates are necessary with RESTSCREEN(). <cScreen> is a character string containing the saved screen region. RESTSCREEN() is a screen function that redisplays a screen region saved with SAVESCREEN(). The target screen location may be the same as or different than the original location when the screen region was saved. ##RIGHT()## ---------------------------------------------------------------- RIGHT(<cString>, <nCount>) --> cSubString <cString> is the character string from which to extract characters. <nCount> is the number of characters to extract. RIGHT() returns the rightmost <nCount> characters of <cString>. If <nCount> is zero, RIGHT() returns a null string (""). If <nCount> is negative or larger than the length of the character string, RIGHT() returns <cString>. ##RLOCK()## ---------------------------------------------------------------- Record LOCK RLOCK() --> lSuccess RLOCK() is a network function that locks the current record, preventing other users from updating the record until the lock is released. RLOCK() provides a shared lock, allowing other users read-only access to the locked record while allowing only the current user to modify it. A record lock remains until another record is locked, an UNLOCK is executed, the current database file is closed, or an FLOCK() is obtained on the current database file. ##ROUND()## ---------------------------------------------------------------- ROUND(<nNumber>, <nDecimals>) --> nRounded <nNumber> is the numeric value to round. <nDecimals> defines the number of decimal places to retain. Specifying a negative <nDecimals> value rounds whole number digits. ROUND() is a numeric function that rounds <nNumber> to the number of places specified by <nDecimals>. Specifying a zero or negative value for <nDecimals> allows rounding of whole numbers. A negative <nDecimals> indicates the number of digits to the left of the decimal point to round. Digits between five to nine, inclusive, are rounded up. Digits below five are rounded down. ##ROW()## ---------------------------------------------------------------- ROW() --> nRow ROW() returns the cursor row position as an integer numeric value. The range of the return value is zero to MAXROW(). ##RTRIM()## ---------------------------------------------------------------- Right TRIM [R]TRIM(<cString>) --> cTrimString <cString> is the character string to copy without trailing spaces. RTRIM() returns a copy of <cString> with the trailing spaces removed. If <cString> is a null string ("") or all spaces, RTRIM() returns a null string (""). ##SAVESCREEN()## ---------------------------------------------------------------- SAVESCREEN([<nTop>], [<nLeft>], [<nBottom>], [<nRight>]) --> cScreen <nTop>, <nLeft>, <nBottom>, <nRight> define the coordinates of the screen region to save. Default is the entire screen. SAVESCREEN() returns the specified screen region as a character string. ##SCROLL()## ---------------------------------------------------------------- SCROLL([<nTop>], [<nLeft>], [<nBottom>], [<nRight>], [<nVert>] [<nHoriz>]) --> NIL <nTop>, <nLeft>, <nBottom>, <nRight> define the scroll region coordinates. <nVert> defines the number of rows to scroll, vertically. A positive value scrolls up the specified number of rows. A negative value scrolls down the specified number of rows. A value of zero disables vertical scrolling. If <nVert> is not specified, zero is assumed. <nHoriz> defines the number of rows to scroll horizontally. A positive value scrolls left the specified number of columns. A negative value scrolls right the specified number of columns. A value of zero disables horizontal scrolling. If <nHoriz> is not specified, zero is assumed. If you supply neither <nVert> or <nHoriz> parameters to SCROLL(), the area specified by the first four parameters will be blanked. SCROLL() is a screen function that scrolls a screen region up or down a specified number of rows. When a screen scrolls up, the first line of the region is erased, all other lines are moved up, and a blank line is displayed in the current standard color on the bottom line of the specified region. If the region scrolls down, the operation is reversed. If the screen region is scrolled more than one line, this process is repeated. ##SECONDS()## ---------------------------------------------------------------- SECONDS() --> nSeconds SECONDS() returns the system time as a numeric value in the form seconds.hundredths. The numeric value returned is the number of seconds elapsed since midnight, and is based on a twenty-four hour clock in a range from zero to 86399. ##SELECT()## ---------------------------------------------------------------- SELECT([<cAlias>]) --> nWorkArea <cAlias> is the target work area alias name. SELECT() returns the work area of the specified alias as a integer numeric value. ##SET()## ---------------------------------------------------------------- SET(<nSpecifier>, [<expNewSetting>], [<lOpenMode>]) --> CurrentSetting <nSpecifier> is a numeric value that identifies the setting to be inspected or changed. <expNewSetting> is an optional argument that specifies a new value for the <nSpecifier>. The type of <expNewSetting> depends on <nSpecifier>. <lOpenMode> is a logical value that indicates whether or not files are opened for some settings. A value of false (.F.) means the file should be truncated. A value of true (.T.) means the file should be opened in append mode. In either case, if the file does not exist, it is created. If this argument is not specified, the default is append mode. SET() returns the current value of the specified setting. Inside nB, the function SET() is not so easy to use as inside the CA-Clipper environment. This because nB cannot support manifest constants and a numeric specifier <nSpecifier> is not easy to manage. Instead SET() you can use SETVERB(). <setverb()> ##SETBLINK()## ---------------------------------------------------------------- SETBLINK([<lToggle>]) --> lCurrentSetting <lToggle> changes the meaning of the asterisk (*) character when it is encountered in a SETCOLOR() string. Specifying true (.T.) sets character blinking on and false (.F.) sets background intensity. The default is true (.T.). SETBLINK() returns the current setting as a logical value. ##SETCANCEL()## ---------------------------------------------------------------- SETCANCEL([<lToggle>]) --> lCurrentSetting <lToggle> changes the availability of Alt-C and Ctrl-Break as termination keys. Specifying true (.T.) allows either of these keys to terminate an application and false (.F.) disables both keys. The default is true (.T.). SETCANCEL() returns the current setting as a logical value. ##SETCOLOR()## ---------------------------------------------------------------- SETCOLOR([<cColorString>]) --> cColorString <cColorString> is a character string containing a list of color attribute settings for subsequent screen painting. ##SETCURSOR()## ---------------------------------------------------------------- SETCURSOR([<nCursorShape>]) --> nCurrentSetting <nCursorShape> is a number indicating the shape of the cursor. <nCursorShape> = 0 None <nCursorShape> = 1 Underline <nCursorShape> = 2 Lower half block <nCursorShape> = 3 Full block <nCursorShape> = 4 Upper half block SETCURSOR() returns the current cursor shape as a numeric value. ##SETKEY()## ---------------------------------------------------------------- SETKEY(<nInkeyCode>, [<bAction>]) --> bCurrentAction <nInkeyCode> is the INKEY() value of the key to be associated or queried. <bAction> specifies a code block that is automatically executed whenever the specified key is pressed during a wait state. SETKEY() returns the action block currently associated with the specified key, or NIL if the specified key is not currently associated with a block. ##SETMODE()## ---------------------------------------------------------------- SETMODE(<nRows>, <nCols>) --> lSuccess <nRows> is the number of rows in the desired display mode. <nCols> is the number of columns in the desired display mode. SETMODE() is an environment function that attempts to change the mode of the display hardware to match the number of rows and columns specified. The change in screen size is reflected in the values returned by MAXROW() and MAXCOL(). ##SETPOS()## ---------------------------------------------------------------- SET POSition SETPOS(<nRow>, <nCol>) --> NIL <nRow>, <nCol> define the new screen position of the cursor. These values may range from 0, 0 to MAXROW(), MAXCOL(). SETPOS() is an environment function that moves the cursor to a new position on the screen. After the cursor is positioned, ROW() and COL() are updated accordingly. ##SETPRC()## ---------------------------------------------------------------- SET Printer Row Column SETPRC(<nRow>, <nCol>) --> NIL <nRow> is the new PROW() value. <nCol> is the new PCOL() value. SETPRC() is a printer function that sends control codes to the printer without changing the tracking of the printhead position. ##SOUNDEX()## ---------------------------------------------------------------- SOUNDEX(<cString>) --> cSoundexString <cString> is the character string to convert. SOUNDEX() returns a four-digit character string in the form A999. ##SPACE()## ---------------------------------------------------------------- SPACE(<nCount>) --> cSpaces <nCount> is the number of spaces to return. SPACE() returns a character string. If <nCount> is zero, SPACE() returns a null string (""). ##SQRT()## ---------------------------------------------------------------- SQRT(<nNumber>) --> nRoot <nNumber> is a positive number to take the square root of. SQRT() returns a numeric value calculated to double precision. The number of decimal places displayed is determined solely by SET DECIMALS regardless of SET FIXED. A negative <nNumber> returns zero. ##STR()## ---------------------------------------------------------------- STRing STR(<nNumber>, [<nLength>], [<nDecimals>]) --> cNumber <nNumber> is the numeric expression to convert to a character string. <nLength> is the length of the character string to return, including decimal digits, decimal point, and sign. <nDecimals> is the number of decimal places to return. STR() returns <nNumber> formatted as a character string. ##STRTRAN()## ---------------------------------------------------------------- STRTRAN(<cString>, <cSearch>, [<cReplace>], [<nStart>], [<nCount>]) --> cNewString <cString> is the character string or memo field to search. <cSearch> is the sequence of characters to locate. <cReplace> is the sequence of characters with which to replace <cSearch>. If this argument is not specified, the specified instances of the search argument are replaced with a null string (""). <nStart> is the first occurrence that will be replaced. If this argument is omitted, the default is one. <nCount> is the number of occurrences to replace. If this argument is not specified, the default is all. STRTRAN() returns a new character string with the specified instances of <cSearch> replaced with <cReplace>. ##STUFF()## ---------------------------------------------------------------- STUFF(<cString>, <nStart>, <nDelete>, <cInsert>) --> cNewString <cString> is the target character string into which characters are inserted and deleted. <nStart> is the starting position in the target string where the insertion/deletion occurs. <nDelete> is the number of characters to delete. <cInsert> is the string to insert. STUFF() returns a copy of <cString> with the specified characters deleted and with <cInsert> inserted. ##SUBSTR()## ---------------------------------------------------------------- SUB STRing SUBSTR(<cString>, <nStart>, [<nCount>]) --> cSubstring <cString> is the character string from which to extract a substring. <nStart> is the starting position in <cString>. If <nStart> is positive, it is relative to the leftmost character in <cString>. If <nStart> is negative, it is relative to the rightmost character in the <cString>. <nCount> is the number of characters to extract. If omitted, the substring begins at <nStart> and continues to the end of the string. If <nCount> is greater than the number of characters from <nStart> to the end of <cString>, the extra is ignored. SUBSTR() is a character function that extracts a substring from another character string or memo field. ##TIME()## ---------------------------------------------------------------- TIME() --> cTimeString TIME() returns the system time as a character string in the form hh:mm:ss. hh is hours in 24-hour format, mm is minutes, and ss is seconds. TIME() is a time function that displays the system time on the screen or prints it on a report. ##TONE()## ---------------------------------------------------------------- TONE(<nFrequency>, <nDuration>) --> NIL <nFrequency> is a positive numeric value indicating the frequency of the tone to sound. <nDuration> is a positive numeric value indicating the duration of the tone measured in increments of 1/18 of a second. For example, an <nDuration> value of 18 represents one second. For both arguments, noninteger values are truncated (not rounded) to their integer portion. ##TRANSFORM()## ---------------------------------------------------------------- TRANSFORM(<exp>, <cSayPicture>) --> cFormatString <exp> is the value to format. This expression can be any valid data type except array, code block, and NIL. <cSayPicture> is a string of picture and template characters that describes the format of the returned character string. TRANSFORM() converts <exp> to a formatted character string as defined by <cSayPicture>. ##TYPE()## ---------------------------------------------------------------- TYPE(<cExp>) --> cType <cExp> is a character expression whose type is to be determined. <cExp> can be a field, with or without the alias, a private or public variable, or an expression of any type. TYPE() returns one of the following characters: A Array B Block C Character D Date L Logical M Memo N Numeric O Object U NIL, local, or static UE Error syntactical UI Error indeterminate TYPE() is a system function that returns the type of the specified expression. TYPE() is like VALTYPE() but uses the macro operator (&) to determine the type of the argument. VALTYPE(), by contrast, evaluates an expression and determines the data type of the return value. ##UPDATED()## ---------------------------------------------------------------- UPDATED() --> lChange UPDATED() returns true (.T.) if data in a GET is added or changed; otherwise, it returns false (.F.). ##UPPER()## ---------------------------------------------------------------- UPPER(<cString>) --> cUpperString <cString> is the character string to convert. UPPER() returns a copy of <cString> with all alphabetical characters converted to uppercase. All other characters remain the same as in the original string. ##USED()## ---------------------------------------------------------------- USED() --> lDbfOpen USED() returns true (.T.) if there is a database file in USE in the current work area; otherwise, it returns false (.F.). ##VAL()## ---------------------------------------------------------------- VALue VAL(<cNumber>) --> nNumber <cNumber> is the character expression to convert. VAL() is a character conversion function that converts a character string containing numeric digits to a numeric value. When VAL() is executed, it evaluates <cNumber> until a second decimal point, the first non-numeric character, or the end of the expression is encountered. ##VALTYPE()## ---------------------------------------------------------------- VALue TYPE VALTYPE(<exp>) --> cType <exp> is an expression of any type. VALTYPE() returns a single character representing the data type returned by <exp>. VALTYPE() returns one of the following characters: A Array B Block C Character D Date L Logical M Memo N Numeric O Object U NIL VALTYPE() is a system function that takes a single argument, evaluates it, and returns a one character string describing the data type of the return value. ##YEAR()## ---------------------------------------------------------------- YEAR(<dDate>) --> nYear <dDate> is the date value to convert. YEAR() returns the year of the specified date value including the century digits as a four-digit numeric value. The value returned is not affected by the current DATE or CENTURY format. Specifying a null date (CTOD("")) returns zero. ##nB FUNCTIONS## ================================================================ Some functions made into nB are available for macro use. Not all available functions are here documented. ##ACCEPT()## ---------------------------------------------------------------- ACCEPT( <Field>, [<cMessage>], [<cHeader>] ) --> updatedField|NIL It is a prompt function that shows <cMessage> asking to type something into <Field>. It returns the updated data or NIL if [Esc] was pressed. The string <cHeader> is showed centered at the top window. ##ACHOICE()## ---------------------------------------------------------------- ACHOICE(<nTop>, <nLeft>, <nBottom>, <nRight>, <acMenuItems>, [<alSelectableItems>], [<nInitialItem>], [<lButtons> | <aButtons>]) --> nPosition <nTop>, <nLeft>, <nBottom>, <nRight> are the window coordinates. <acMenuItems> is an array of character strings to display as the menu items. <alSelectableItems> is a parallel array of logical values (one element for each item in <acMenuItems>) that specify the selectable menu items. Elements can be logical values or character strings. If the element is a character string, it is evaluated as a macro expression which should evaluate to a logical data type. A value of false (.F.) means that the corresponding menu item is not available, and a value of true (.T.) means that it is available. By default, all menu items are available for selection. <nInitialItem> is the position in the <acMenuItems> array of the item that will be highlighted when the menu is initially displayed. <lButtons> if True means that default buttons will appear. <aButtons> is an array of buttons. aButtons[n][1] N, the nth button row position; aButtons[n][2] N, the nth button column position; aButtons[n][3] C, the nth button text; aButtons[n][4] B, the nth button code block. ACHOICE() returns the numeric position in the <acMenuItems> array of the menu item selected. If no choice is made, ACHOICE() returns zero. ##ACHOICEWINDOW()## ---------------------------------------------------------------- ACHOICEWINDOW( <acMenuItems>, [<cDescription>], <nTop>, <nLeft>, <nBottom>, <nRight>, [<alSelectableItems>], [<nInitialItem>] ) --> nPosition <acMenuItems> is an array of character strings to display as the menu items. <cDescription> is a header to be shown at the top of window. <nTop>, <nLeft>, <nBottom>, <nRight> are the window coordinates. <alSelectableItems> is a parallel array of logical values (one element for each item in <acMenuItems>) that specify the selectable menu items. Elements can be logical values or character strings. If the element is a character string, it is evaluated as a macro expression which should evaluate to a logical data type. A value of false (.F.) means that the corresponding menu item is not available, and a value of true (.T.) means that it is available. By default, all menu items are available for selection. <nInitialItem> is the position in the <acMenuItems> array of the item that will be highlighted when the menu is initially displayed. ACHOICEWINDOW() calls ACHOICE() with a window border around the ACHOICE() screen area. ##ALERTBOX()## ---------------------------------------------------------------- ALERTBOX( <cMessage>, [<aOptions>] ) --> nChoice <cMessage> is the message text displayed, centered, in the alert box. If the message contains one or more semicolons, the text after the semicolons is centered on succeeding lines in the dialog box. <aOptions> defines a list of up to 4 possible responses to the dialog box. ALERTBOX() returns a numeric value indicating which option was chosen. If the [Esc] key is pressed, the value returned is zero. The ALERTBOX() function creates a simple modal dialog. The user can respond by moving a highlight bar and pressing the Return or SpaceBar keys, or by pressing the key corresponding to the first letter of the option. If <aOptions> is not supplied, a single "Ok" option is presented. ALERTBOX() is similar to ALERT() but it accept mouse imput. ##ATB()## ---------------------------------------------------------------- ATB( [<nTop>], [<nLeft>], [<nBottom>], [<nRight>], <aArray>, [<nSubscript>], [<acColSayPic>], [<acColTopSep>], [<acColBodySep>], [<acColBotSep>], [<acColHead>], [<acColFoot>], [<abColValid>], [<abColMsg>], [<cColor>], [<abColColors>], [<lModify>], [<lButtons> | <aButtons>] ) --> NIL <nTop>, <nLeft>, <nBottom>, <nRight> defines the screen area where browse have to take place. <aArray> bidimentional array to be browsed. <nSubscript> starting array position. <acColSayPic> is the picture array. <acColTopSep> is the top separation array: default is chr(194)+chr(196). <acColBodySep> is the body sepatation array: default is chr(179). <acColBotSep> is the bottom separation array: default is chr(193)+chr(196). <acColHead> is the header array for every column. <acColFoot> is the footer array for every column. <abColValid> is the validation array that specify when a field is properly filled. The condition must be specifyed in code block format. <abColMsg> is the message array that permits to show information at the bottom of browse area. The array must be composed with code blocks whitch result with a character string. <cColor> is the color string: it may be longer than the usal 5 elements. <abColColors> is the color code block array. The code block receive as parameter the value contained inside the field and must return an array containing two numbers: they correspond to the two color couple from <cColor>. <lModify> indicates whether the browse can modify data. <lButtons> if True, default buttons are displayed. <aButtons> array of buttons. aButtons[n][1] N, the nth button row position; aButtons[n][2] N, the nth button column position; aButtons[n][3] C, the nth button text; aButtons[n][4] B, the nth button code block. This function starts the browse of a bidimentional array. Only arrays containing monodimentional array containing the same kind of editable data are allowed. At the moment the function can handle a maximum of 61 columns. ##BCOMPILE()## ---------------------------------------------------------------- BCOMPILE( <cString> ) --> bBlock Compiles the string <cString> and returns the code block <bBlock> ##BUTTON()## ---------------------------------------------------------------- BUTTON( @<aButtons>, [<nRow>], [<nCol>], [<cText>], [<cColor>], [<bAction>] ) --> NIL <aButtons> the array of buttons to be increased with a new button array. <nRow> and <nCol> is the row and column starting position for the button string. <cText> is the text that make up the button. <cColor> is the color string. <bAction> is the code block associated to the button. This function adds to <aButtons> a new button array. Please note that the button array added is compatible only with the READ() funcion and not the other function using array of buttons: the others do not have a color string. ##COLORARRAY()## ---------------------------------------------------------------- COLORARRAY( <cColor> ) --> aColors <cColors> a color string to be translated into a color array. This function tranform a color string into a color array. The array has as many elements as the colors contained inside <cColor> string. ##COORDINATE()## ---------------------------------------------------------------- COORDINATE( @<nTop>, @<nLeft>], @<nBottom>, @<nRight>, [<cHorizontal>], [<cVertical>] ) --> NIL <nTop>, <nLeft>, <nBottom> and <nRight> are the starting position of a window that is to be differently aligned. <cHorozontal> determinates the horizontal alignment: "L" all left; "l" middle left; "C" center; "c" center; "R" all right; "r" middle right. <cVertical> determinate the vertical alignment: "T" top; "t" up; "C" center; "c" center; "B" bottom; "b" down. This function helps with the windows alignment recalculating and modifying <nTop>, <nLeft>, <nBottom> and <nRight> in the way to obtain the desired alignment. ##COPYFILE()## ---------------------------------------------------------------- COPYFILE( <cSourceFile>, <cTargetFile>|<cDevice> ) --> NIL <cSourceFile> the source filename. <cTargetFile> the target filename. <cDevice> the target devicename. This function copyes the <cSourceFile> to <cTargetFile> or to <cDevice>. ##DBAPP()## ---------------------------------------------------------------- DBAPP( <cFileName>, [<acFields>], [<bForCondition>], [<bWhileCondition>], [<nNextRecords>], [<nRecord>], [<lRest>], [<cDriver>] ) --> NIL <cFileName> the filename containing data to append to the active Alias. <acFields> array of fieldnames indicating the fields that should be updated on the active Alias (default is all). <bForCondition> a codeblock containing the FOR condition to respect for the data append. Will be appended data that makes the evaluation of this code block True. <bWhileCondition> a codeblock containing the WHILE condition to respect for the data append. Will be appended data as long as the evaluation of this code block is True: the first time it becames False, the data appending is terminated. <nNextRecord> If used, means that only the first <nNextRecords> will be appended. <nRecord> If used, means that that only the record <nRecord> will be appended. <lRest> this option is not available here also if the function saves a place for it. <cDriver> is the optional driver name to use to open the <cFileName> file. This function is used to append data to the active Alias using data from the <cFileName> file, that in this case is a .DBF file. ##DBCLOSE()## ---------------------------------------------------------------- DBCLOSE() --> NIL It is a substitution function of DBCLOSEALL() to use inside "compiled" macros, as a true DBCLOSEALL() will close the macro file too. ##DBCONTINUE()## ---------------------------------------------------------------- DBCONTINUE() --> NIL This function resumes a pending DBLOCATE(). ##DBCOPY()## ---------------------------------------------------------------- DBCOPY( <cFileName>, [<acFields>], [<bForCondition>], [<bWhileCondition>], [<nNextRecords>], [<nRecord>], [<lRest>], [<cDriver>] ) --> NIL <cFileName> the target filename for the data contained inside the active Alias. <acFields> array of fieldnames indicating the fields that should be used from the active Alias (default is all). <bForCondition> a codeblock containing the FOR condition to respect for the data copy. Will be copyed the data that makes the evaluation of this code block True. <bWhileCondition> a codeblock containing the WHILE condition to respect for the data copy. Will be copyed data as long as the evaluation of this code block is True: the first time it becames False, the data copying is terminated. <nNextRecord> if used, means that only the first <nNextRecords> will be copyed. <nRecord> if used, means that that only the record <nRecord> will be copyed. <lRest> if used means that only the remaining records inside the active Alias are copyed. <cDriver> is the optional driver name to use to open the <cFileName> file. This function is used to copy data to <cFileName> form the active Alias. ##DBCOPYSTRUCT()## ---------------------------------------------------------------- DBCOPYSTRUCT( <cDatabase>, [<acFields>] ) --> NIL <cDatabase> is a structure .DBF file that will be filled with structure information about the active Alias. <acFields> is an array of fieldnames that should be taken into consideration. This function creates a structure .DBF file copying the structure of the active Alias. ##DBCOPYXSTRUCT()## ---------------------------------------------------------------- DBCOPYXSTRUCT( <cExtendedDatabase> ) --> NIL <cExtendedDatabase> is a structure .DBF file that will be filled with structure information about the active Alias, accepting extended structure informations. This function creates a structure .DBF file copying the structure of the active Alias. This function accept non-standard structure, tath is, the extended structure availabel inside Clipper. ##DBDELIM()## ---------------------------------------------------------------- DBDELIM( <lCopyTo>, <cFileName>, [<cDelimiter>], [<acFields>], [<bForCondition>], [<bWhileCondition>], [<nNextRecords>], [<nRecord>], [<lRest>] ) --> NIL <lCopyTo> if True the function work copying data to <cFileName> from the active Alias, if False the function work appending data from <cFileName> to the active Alias. <cFileName> the filename containing data to append to the active Alias or to use as the target of the data copy from tha active Alias. <cDelimiter> the delimiter string (or character) used to separate fields inside <cFileName>. <acFields> array of fieldnames indicating the fields of the active Alias that should be taken into consideration (default is all). <bForCondition> a codeblock containing the FOR condition to respect. The operation will be made for all records that respect the condition. <bWhileCondition> a codeblock containing the WHILE condition to respect. The first time it becames False, the operation is terminated. <nNextRecord> if used, means that only the first <nNextRecords> will be appended/copyed. <nRecord> if used, means that that only the record <nRecord> will be appended/copied. <lRest> if used means that only the remaining records will be taken into consideration. This function is used to append data to the active Alias using data from the <cFileName> file or to copy data into <cFileName> using the active Alias as the source. <cFileName> is a delimited ASCII file. ##DBISTATUS()## ---------------------------------------------------------------- DBISTATUS() --> cDBInformations This function returns the informations on the active Alias in a text form. ##DBISTRUCTURE()## ---------------------------------------------------------------- DBISTRUCTURE() --> cTextStructure | NIL This function returns the struture information on the active Alias in a text form. ##DBJOIN()## ---------------------------------------------------------------- DBJOIN( <cAlias>, <cDatabase>, [<acFields>], [<bForCondition>] ) --> NIL <cAlias> the name of the Alias to use to merge with records from the active Alias. <cDatabase> the target .DBF filename. <acFields> the array of fieldnames which represent the projection of fields form both Aliases into the new .DBF file. If not specified, all fields from the primary work area are included in the target .DBF file. This function creates a new database file by merging selected records and fields form two work areas (Aliases) based on a general condition. It works by making a complete pass through the secondary work area <cAlias> for each record in the primary work area (the active Alias), evaluating the condition for each record in the secondary work area. When <bForCondition> is evaluated True, a new record is created in the target database file <cDatabase> using the fields specified from both work areas inside <acFields>. ##DBLABELFORM()## ---------------------------------------------------------------- DBLABELFORM( <cLabel>, [<lToPrinter>], [<cFile>], [<lNoConsole>], [<bForCondition>], [<bWhileCondition>], [<nNextRecords>], [<nRecord>], [<lRest>], [<lSample>] ) --> NIL el> is the name of the label file (.LBL) that contains the label format definition. rinter> if True, the output is copyed to printer (LPT1). e> if present, it is the name of a ASCII file where the output is copyed. onsole> if True, the output is not sent to the console.. Condition> a codeblock containing the FOR condition to respect for label print. Only the records contained inside the active Alias that respect the condition will be used for labels. leCondition> a codeblock containing the WHILE condition to respect for the label print. The first time that the condition is False, the label print terminates. tRecord> if used, means that only the first <nNextRecords> will be used. ord> if used, means that that only the record <nRecord> will be used. t> if used means that only the remaining records inside the active Alias will be used. ple> if True displays test labels as rows of asterisks. This function prints labels to the console. ##DBLIST()## ---------------------------------------------------------------- DBLIST( [<lToDisplay>], <abListColumns>, [<lAll>], [<bForCondition>], [<bWhileCondition>], [<nNextRecords>], [<nRecord>], [<lRest>], [<lToPrinter>], [<cFileName>] ) isplay> if True the printout is sent to the console screen. stColumns> is an array of columns expressions to list. > if True prints all the records contained inside the active Alias. Condition> a codeblock containing the FOR condition to respect. Only the records contained inside the active Alias that respect the condition will be used for list. leCondition> a codeblock containing the WHILE condition to respect. The first time that the condition is False, the list terminates. tRecord> if used, means that only the first <nNextRecords> will be used. ord> if used, means that that only the record <nRecord> will be used. t> if used means that only the remaining records inside the active Alias will be used. rinter> if True, the output is copyed to printer (LPT1). eName> if present, it is the name of a ASCII file where the output is copyed. This function prints a list of records to the console. ##DBLOCATE()## ---------------------------------------------------------------- DBLOCATE( [<bForCondition>], [<bWhileCondition>], [<nNextRecords>], [<nRecord>], [<lRest>] ) --> NIL Condition> a codeblock containing the FOR condition to respect. Only the records contained inside the active Alias that respect the condition will be taken into consideration. leCondition> a codeblock containing the WHILE condition to respect. The first time that the condition is False, the locate terminates. tRecord> if used, means that only the first <nNextRecords> will be used. ord> if used, means that that only the record <nRecord> will be used. t> if used means that only the remaining records inside the active Alias will be used. This function searches sequentially for the first record matching the FOR and WHILE conditions. Once a DBLOCATE() has been issued you can resume the search from the current record pointer position with DBCONTINUE(). The WHILE condition and the scope (<nNextRecord>, <nRecord> and <lRest>) apply only to the initial DBLOCATE() and are not operational for any subsequent DBCONTINUE() call. <DBCONTINUE()> ##DBOLDCREATE()## ---------------------------------------------------------------- DBOLDCREATE( <cDatabase>, <cExtendedDatabase>, [<cDriver>], [<lNew>], [<cAlias>] ) --> NIL <cDatabase> is the name of the new database file, with an optional drive and directory, specified as a character string. If specified without an extension (.dbf) is assumed. <cExtendedDatabase> is a .DBF file containing the structure information of the file to create. <cDriver> specifies the replaceable database driver (RDD) to use to process the current work area. <cDriver> is the name of the RDD specified as a character expression. <lNew> if Ture the newly created .DBF file is opened using the next available work area making it the current work area (the active Alias). <cAlias> if <lNew> is set to True, this is the Alias name to use to open the file. This function is a a old database function (superseeded form DBCREATE() ) that creates a database file from the structure information contained inside a structure file. ##DBPACK()## ---------------------------------------------------------------- DBPACK() --> NIL This function eliminates definetly the active Alias records previously signed for deletion. It works only if the active Alias is opened in exclusive mode. ##DBSDF()## ---------------------------------------------------------------- DBSDF( <lCopyTo>, <cFileName>, [<acFields>], [<bForCondition>], [<bWhileCondition>], [<nNextRecords>], [<nRecord>], [<lRest>] ) --> NIL yTo> if True the function works copying data to <cFileName> from the active Alias, if False the function work appending data from <cFileName> to the active Alias. eName> the filename containing data to append to the active Alias or to use as the target of the data copy from tha active Alias. elds> array of fieldnames indicating the fields of the active Alias that should be taken into consideration (default is all). Condition> a codeblock containing the FOR condition to respect. The operation will be made for all records that respect the condition. leCondition> a codeblock containing the WHILE condition to respect. The first time it becames False, the operation is terminated. tRecord> if used, means that only the first <nNextRecords> will be appended/copyed. ord> if used, means that that only the record <nRecord> will be appended/copied. t> if used means that only the remaining records will be taken into consideration. This function is used to append data to the active Alias using data from the <cFileName> file or to copy data into <cFileName> using the active Alias as the source. <cFileName> is a SDF ASCII file. ##DBSORT()## ---------------------------------------------------------------- DBSORT( <cDatabase>, [<acFields>], [<bForCondition>], [<bWhileCondition>], [<nNextRecords>], [<nRecord>], [<lRest>] ) --> NIL abase> the .DBF file to create. elds> the array of fields to be used to create the new sorted <cDatabase> file. Condition> a codeblock containing the FOR condition to respect. Only the records contained inside the active Alias that respect the condition will be taken into consideration. leCondition> a codeblock containing the WHILE condition to respect. The first time that the condition is False, the sort terminates. tRecord> if used, means that only the first <nNextRecords> inside the active Alias will be used. ord> if used, means that that only the record <nRecord> will be used. t> if used means that only the remaining records inside the active Alias will be used. Copy the active Alias to a .DBF file in sorted order. ##DBTOTAL()## ---------------------------------------------------------------- DBTOTAL( <cDatabase>, <bKey>, [<acFields>, [<bForCondition>], [<bWhileCondition>], [<nNextRecords>], [<nRecord>], [<lRest> ) --> NIL abase> the .DBF file to create that will contain the copy of summarised records. > the code block key expression that should correspond to the key expression of the active index of the active Alias. elds> the array of fields to be used to create the new <cDatabase> file. Condition> a codeblock containing the FOR condition to respect. Only the records contained inside the active Alias that respect the condition will be taken into consideration. leCondition> a codeblock containing the WHILE condition to respect. The first time that the condition is False, the sort terminates. tRecord> if used, means that only the first <nNextRecords> inside the active Alias will be used. ord> if used, means that that only the record <nRecord> will be used. t> if used means that only the remaining records inside the active Alias will be used. This function summerises records by key value to a .DBF file. It sequentially process the active Alias scanning the specified scope of records. Records with the same key will be summerised inside the destination .DBF file. The value of numeric fields of records with the same key are added. ##DBUPDATE()## ---------------------------------------------------------------- DBUPDATE( <cAlias>, <bKey>, [<lRandom>], [<bReplacement>] ) as> is the Alias containing data to be used to update the active Alias. > is a code block expression using information form the <cAlias> to obtain a key to refer to the active Alias. dom> if True, allows record in the <cAlias> to be in any order. In this case, the active Alias must be indexe with the same key as <bKey>. lacement> is the code block that will be executed when records matches: it should contains the criteria for data update. This function updates the active Alias with data from another .DBF file. Example: dbUpdate( "INVOICE", {|| LAST}, .T.,; {|| FIELD->TOTAL1 := INVOICE->SUM1,; FIELD->TOTAL2 := INVOICE->SUM2 } ) ##DBZAP()## ---------------------------------------------------------------- DBZAP() --> NIL This function erases immediatly all the records contained inside the active Alias. ##DISPBOXCOLOR()## ---------------------------------------------------------------- DISPBOXCOLOR( [<nColorNumber>], [<cBaseColor>] ) --> cColor <nColorNumber> may be 1 or 2 and are the two color used to create shadowed borders. 1 is usually used for the left and top line; 2 is used for the right and bottom line. <cBaseColor> is the starting color string. The default is the actual color. This function return a color string used for DISPBOXSHADOW() the function that create a shadowed border around a screen window. ##DISPBOXSHADOW()## ---------------------------------------------------------------- DISPBOXSHADOW( <nTop>, <nLeft>], <nBottom>, <nRight>, [<cBoxString>], [<cColor1>], [<cColor2>] ) --> NIL <nTop>, <nLeft>], <nBottom> and <nRight> are the screen coordinate where the box is to be displayed. <cBoxString> is the box string containing the character to use to build the box. Default is a single line box. <cColor1> is the color string to use for the left and top side of the box. <cColor2> is the color string to use for the right and bottom side of the box. This function drows a screen box like DISPBOX() but allowing the variation of colors around the border to simulate a sort of shadow. ##DIR()## ---------------------------------------------------------------- DIR( [<cFileSpec>], [<lDrives>], [<lDirs>], [<lFiles>], [<lNoDirReturn>], [<nSortColumn>] ) --> cPathname <cFileSpec> the filename or Pathname, also with wildcards, to be searched. <lDrives> true (.t.) means: include drives letters. <lDirs> true (.t.) means: include directory names. <lFiles> true (.t.) means: include file names. <lNoRirReturn> true (.t.) means: do not return the shown directory if [Esc] is used to exit. <nSortColumn> the column number to use to sort the list. The columns are: Name = 1, Size = 2, Date = 3, Time = 4, Attribute = 5. It is not possible to sort for extention. It is a window function usefull to search a file or a directory. The complete pathname of the selected file is returned. ##DOC()## ---------------------------------------------------------------- DOC( [<cTextFileName> ) --> NIL <cTextFileName> can contain the text file to open and edit; if empty, the editing of UNTITLED.TXT will start. It is the nB Text editor usefull for small text files (less then 64K) and contains a complete menu that can be started with [F10]. ATTENTION: doc() should not be used inside macros. ##DOTLINE()## ---------------------------------------------------------------- dotLine() --> NIL This function is a "dot" command line usefull for calculations resolution. The dot-line content may be passed to the keyboard buffer. ##DTEMONTH()## ---------------------------------------------------------------- dteMonth( <nMonth>, <cLanguage> ) --> cMonth <nMonth> the month number. <cLanguage> the language name. This function translates the <nMonth> number into the month name translated using the <cLanguage> language. ##DTEWEEK()## ---------------------------------------------------------------- DTEWEEK( <nWeek>, <cLanguage> ) --> cWeek <nWeek> is the week number (1 is sunday, 7 is saturday) to be translated into text. <cLanguage> is the language name into whitch the week must be expressed. At the moment it works only for italian, so <cLanguage> can only contain "ITALIANO". This function translates the week number into the week name translated using the <cLanguage> language. ##EX()## ---------------------------------------------------------------- EX( <cFileMacro> ) --> nExitCode Executes the macro file <cFileName>. The extention must be specified. <cFileMacro> may be the name of a "compiled" macro or a text macro file. ##GET()## ---------------------------------------------------------------- GET( @<aGetList>, [<nTop>], [<nLeft>], { |x| iif( pcount() > 0, <Var> := x, <Var> ) } [<cGetPicture>], [<cColorString>], [<bPreExpression>], [<bValid>] ) List> is the get list array that will be increased with this get(). > and <nLeft> define the starting position of this get object on the screen. is the variable that is to be edited with this get. <Var> is in fact sent to the GET() function using a code block. Picture> is the get picture to use for <Var>. orString> is the color string to use for the get. Expression> is a code block that will be evaluated before the get object will became active. It must result True to obtain that the get object became active. id> is a code block that will be evaluated after the get object is edited. It must result True to obtain that the get object may become inactive. create screen editing masks. <SAY()> <BUTTON()> <READ()> ##GVADD()## ---------------------------------------------------------------- GVADD( @<cField>, <cAdd> ) --> .T. <cField> the field to fill with more data. <cAdd> is the string to be added to the content of <cField>. This function is to be used inside GETs for pre/post validation, when a the content of a field should be added with more data. <cField> is returned with the same length as before to avoid troubles with current and future GETs. ##GVDEFAULT()## ---------------------------------------------------------------- GVDEFAULT( @<cField>, <cDefault> ) --> .T. <@cField> the field to check and if empty correct with <cDefault>. <cDefault> is the default value to be used to replace <cField>. This function is to be used inside GETs for pre/post validation, when a field should have a default value. <cField> is returned with the same length as before to avoid troubles with current and future GETs. ##GVFILEDIR()## ---------------------------------------------------------------- GVFILEDIR( @<cWildName> ) --> .T. <cWildName> is the file name taken from the current get to be used for search with DIR(). This function is to be used inside GETs for pre validation: the <cWildName> is a file name with wild cards that can be searched with the DIR() function after that a specific key is pressed. <cWildName> is returned with the same length as before to avoid troubles with current and future GETs. ##GVFILEEXIST()## ---------------------------------------------------------------- GVFILEEXIST( @<cNameToTest>, [<cExtention>] ) --> lSuccess <@cNameToTest> is the file name taken from the current get to test for existance. <cExtention> is the normal extention of the file. This function is to be used inside GETs for post validation: the file name have to exist. <cNameToTest> is returned with the same length as before to avoid troubles with current and future GETs. ##GVFILEEXTENTION()## ---------------------------------------------------------------- GVFILEEXTENTION( @<cName>, <cExt> ) --> .T. <@cName> the file name to be eventually corrected with file extention. <cExt> the file extention to use as default. This function is to use inside GETs for pre/post validation, when the content of a field should contain a file name that should be corrected adding a default extention if not given from the user. ##GVSUBST()## ---------------------------------------------------------------- GVSUBST( @<cField>, <cSubst> ) --> .T. <@cField> the field to be replaced with <cSubst>. <cSubst> is the string to be used to replace the content of <cField>. This function is to use inside GETs for pre/post validation, when the content of a field should be replaced with other data. <cField> is returned with the same length as before to avoid troubles with current and future GETs. ##HTF()## ---------------------------------------------------------------- HTF( [<nInitialRecord>] ) --> NIL <nInitialRecord> is the record number where to start the Help Text File browse. Default is the actual record pointer. This function browse a Help Text File that must be already opened and be the active Alias. ##ISFILE()## ---------------------------------------------------------------- ISFILE( <cName> ) --> lFileExists <cName> is the file name (with or without path) to be checked for existance. This function returns true (.T.) if the file <cName> exists. The difference between this function and the standard FILE() function is that ISFILE() checks for wildcards before. If <cName> contains wildcards, the result is false (.F.). ##ISWILD()## ---------------------------------------------------------------- ISWILD( <cName> ) --> lIsWild <cName> is the file name (with or without path) to be checked for wildcards presence. This function returns true (.T.) if <cName> contains wildcards. ##ISMEMVAR()## ---------------------------------------------------------------- ISMEMVAR( <cName> ) --> lIsMemvar <cName> is the name of a possible memvar. This function returns true (.T.) if the <cName> is a declared Memvar. ##ISCONSOLEON()## ---------------------------------------------------------------- ISCONSOLEON() --> lConsoleIsOn This function returns true (.T.) if the console will show the result of QOUT() and QQOUT(). ##ISPRINTERON()## ---------------------------------------------------------------- ISPRINTERON() --> lPrinterIsOn This function returns true (.T.) if the default printer will report the the result of QOUT() and QQOUT(). The default printer is PRN or LPT1. If SET ALTERNATE TO is configured to send outputs to LPT2 or another printer, the function will report false (.F.). ##KEYBOARD()## ---------------------------------------------------------------- KEYBOARD( [<cString>] ) --> NIL This function stuff a string into the keyboard buffer. ##LISTWINDOW()## ---------------------------------------------------------------- listWindow( <acMenuItem>, [<cDescription>], [<nTop>], [<nLeft>], [<nBottom>], [<nRight>], [<cColorTop>], [<cColorBody>] ) --> nPosition <acMenuItem> is the character array containing the list of choices. <cDescription> is the header to be shown at the top window. <nTop>, <nLeft>, <nBottom>, <nRight> are the window coordinates. <cColorTop> is the color to use for window header and footer. <cColorBody> is the color to use for the window body that is the space where the text appears. This function is an similar to achoice(), but it shows a header and footer, and it saves the screen, acting like a window. ##MEMOWINDOW()## ---------------------------------------------------------------- memoWindow( <cVar>, [<cDescription>], [<nTop>], [<nLeft>], [<nBottom>], [<nRight>], [<cColorTop>], [<cColorBody>], [<lEditMode>], [<nLineLength>], [<nTabSize>] ) --> cVar <cVar> is the character field (variable) to be edited. <cDescription> is the header to be shown at the top window. <nTop>, <nLeft>, <nBottom>, <nRight> are the window coordinates. <cColorTop> is the color to use for window header and footer. <cColorBody> is the color to use for the window body that is the space where the text appears. <lEditMode> is equivalent to memoedit(). <nLineLenght> is equivalent to memoedit(). <nTabSize> is equivalent to memoedit(). This function lets you easyly edit a long character field (memo) defining automatically a simple window and providing a simple help. ##MEMPUBLIC()## ---------------------------------------------------------------- MEMPUBLIC( <cMemvarName>|<acMemvarNames> ) --> NIL varName> is the name of the PUBLIC variable to create (max 10 characters). mvarNames> is an array of PUBLIC variable names to create (max 10 characters). Creates a PUBLIC variables or a group of variables. ##MEMRELEASE()## ---------------------------------------------------------------- MEMRELEASE( <cMemvarName>|<acMemvarNames> ) --> NIL varName> is the name of the PUBLIC variable to be released. mvarNames> is an array of PUBLIC variable names to be released. This function releases a previously created PUBLIC variables or a group of variables. ##MEMRESTORE()## ---------------------------------------------------------------- MEMRESTORE( <cMemFileName>, [<lAdditive> ) --> NIL FileName> the memory file (.MEM) to load from disk. itive> if Ture causes memory variables loaded from the memory fiel to be added to the existing pool of memory variables. If False, the existing memory variables are automatically released. Retrive memory variables form a memory file (.MEM). ##MEMSAVE()## ---------------------------------------------------------------- MEMSAVE( <cMemFileName>, [<cSkeleton>], [<lLike>] ) --> NIL FileName> the memory file (.MEM) where public variables should be saved. leton> the skeleton mask for defining a group of variables. Whildcard characters may be used: _*_ and _?_. e> if True, the variables grouped with <cSkeleton> are saved, else only the other variables are saved. Saves memory variables to a memory file (.MEM). ##MENUPROMPT()## ---------------------------------------------------------------- MENUPROMPT( @<aoGet>, [<nRow>], [<nCol>], [<cPrompt>], [<bBlock>] ) --> NIL <aoGet> is an array of get objects where a new get is added by MENUPROMPT(). These gets are read only. [<nRow>] and [<nCol>] are the screen coordinates where the menu prompt will appear. [<cPrompt>] is the menu prompt string. [<bBlock>] is the code block to execute when the cursor is on the current menu prompt. It is usually a code block that shows a message somewhere on the screen. This founction shuld substitute the @...PROMPT command and handle the mouse. ##MENUTO()## ---------------------------------------------------------------- MENUTO( <aoGet>, <nPos> ) --> nChoice <aoGet> array of get objects. <nPos> starting position to be edited. Like MENU TO. It returns the selected menu item created with MENUPROMPT(). It supports the mouse. ##MESSAGELINE()## ---------------------------------------------------------------- MESSAGELINE( [<cMessage>], [<cColor>], [<nPosTop>], [<nPosLeft>] ) --> NIL <aMessage> the message to be displayed. <cColor> the color string. <nPosTop> and <nPosLeft> the starting position where the string message whould appear on the screen. Default values are resplectly ROW() and COL(). MESSAGELINE() is a function that display a message on the screen on the selected position. If <cMessage> is NIL, the message is eliminated from screen restoring the previous screen content. ##MOUSESCRSAVE()## ---------------------------------------------------------------- MOUSESCRSAVE( [<nTop>], [<nLeft>], [<nBottom>], [<nRight>] ) --> cSavedScreen <nTop>, <nLeft>, <nBottom> and <nRight> are the screen coordinates that will be to save the screen. This function works line SAVESCREEN() but it hide the mouse cursor before a screen save is made. ##MOUSESCRRESTORE()## ---------------------------------------------------------------- MOUSESCRRESTORE( [<nTop>], [<nLeft>], [<nBottom>], [<nRight>], [<cScreen>] ) --> cSavedScreen <nTop>, <nLeft>, <nBottom> and <nRight> are the screen coordinates where the saved screen will be restored. <cScreen> is the previously saved screen to restore. This function works line RESTSCREEN() but it hide the mouse cursor before a screen restore is made. ##PICCHRMAX()## ---------------------------------------------------------------- PICCHRMAX( [<nCol>], [<nMaxCol>] ) --> cPictureString <nCol> is the starting position on the screen for the get field. <nMaxCol> is the end position on the screen of the get field. This function is usefull when a character field is to be used on a get object. The generated picture will be the of the maximum possible extention, eventually with scroll. ##QUIT()## ---------------------------------------------------------------- QUIT() --> NIL Terminates program execution. ##READ()## ---------------------------------------------------------------- READ( <aoGet>, [<nPos>], [<aButtons>], [<lReadOnly>] ) --> lUpdated <aoGet> is the array of get objects. <nPos> is the starting position. <aButtons> is the array of buttons. <lReadOnly> if True, get fields cannot be modifyed; the default value is False. This function is made to substitute the READMODAL() allowing the use of the mouse. The array <aButtons> is made with the help of the function BUTTON(). see also: <BUTTON()> ##RF()## ---------------------------------------------------------------- RF( <cFRMName>, [<bForCondition>], [<bWhileCondition>], [<nNext>], [<nRecord>], [<lRest>], [<lPlain>], [<cbHeading>], [<lBeforeEject>], [<lSummary>], [<lDate>], [<acExtra>] ) --> NIL <cFRMName> the form (.FRM) file to use to print the active Alias. <bForCondition> code block for the FOR condition. <bWhileCondition> code block for the WHILE condition. <nNext> see REPORT FORM. <nRecord> see REPORT FORM <lRest> see REPORT FORM <lPlain> if true (.T.), force the print in a simple way. <cbHeading> additional header in character or code block form. If a code block is sent, the final result must be a character string. <lBeforeEject> if true (.T.), force a form feed before the print. <lSummary> if true (.T.), force a summary print only. <lDate> if false (.F.), force the print without date at the top of page. <acExtra> a character array that may be used for translating standard printed report form words and to add vertical and horizontal separations. The default value of acExtra is: acExtra[1] "Page No." acExtra[2] "** Subtotal **" acExtra[3] "* Subsubtotal *" acExtra[4] "*** Total ***" acExtra[5] " " vertical column separation axExtra[6] "" horizontal separation: no separation. This function does the same work of REPORT FORM or __ReportForm or dbReportForm, but it prints where qout() and qqout() print. ##RPT()## ---------------------------------------------------------------- RPT( <cText> ) --> NIL This function prints the text contained into <cText> using print commands. This function accepts other parameters here not described, as they are not to be used for macro purpose. The printing is made using QOUT() and QQOUT(), this way it is sensible to the "alternate" file definition. ##RPTMANY()## ---------------------------------------------------------------- RPTMANY( <cText>, [<bWhileCondition>], [<bForCondition>] ) --> NIL This function prints the text contained into <cText> many times: one for every record contained into the active Alias. <cText> is the text to be printed. <bWhileCondition> is a code block for a WHILE condition to respect for the records to print. <bForCondition> is a code block for a FOR condition to respect for the records to print. ##RPTTRANSLATE()## ---------------------------------------------------------------- RPTTRANSLATE( <cText> ) --> cTranslatedText This function translates once <cText> replacing variables with memvars or Fields. ##RUN()## ---------------------------------------------------------------- RUN( <cCommand> ) --> NIL This function start execution of <cCommand> in a DOS session. It works only if there is enough available memory. ##SAY()## ---------------------------------------------------------------- SAY( <nTop>, <nLeft>, <Expr>, [<cSayPicture>], [<cColorString>] ) --> NIL > and <nLeft> define the starting position on the screen where the <Expr> should be displayed. > is an expression that will be solved and displayed. Picture> is the picture to use to display <Expr>. orString> is the color string to use. This function displays the result of <Expr> on the screen on the desired position. <GET()> <BUTTON()> <READ()> ##SETCOLORSTANDARD()## ---------------------------------------------------------------- SETCOLORSTANDARD( [<nColor>], [<cColor>|<acColor>] ) --> cPreviousColor|acPreviousColor <nColor> is the color number to take into consideration: 0 All colors 1 Base 2 Menu 3 Head 4 Body (Say - Get) 5 Button (Mouse buttons) 6 Message 7 Alert <cColor> the color string to be associated with <nColor>. <acColor> it the color array This function is a way to handle colors inside the application. The functions that display something use a default color depending on what they does. These colors may be changed with SETCOLORSTANDARD(), all toogether or only one. ##SETFUNCTION()## ---------------------------------------------------------------- SETFUNCTION( <nFunctionKey>, <cString> ) --> NIL ctionKey> the number of the function key ( 1=F1, 12=F12) to be assigned. ing> the character string. This function assigns a character string to a function key (obsolete). ##SETMOUSE()## ---------------------------------------------------------------- SETMOUSE( [<lShow>] )--> lPrevious <lShow> True shows the mouse cursor, False hide the mouse cursor, NIL reports only the status. This function is made to show, hide or report only the mouse cursor status. ##SETOUTPUT()## ---------------------------------------------------------------- SETOUTPUT( [<cPeriperal>|<aPeripheral>] ) --> aPrevious_Output_Peripherals <cPeripheral> is the new output peripheral for qout() and qqout() functions. <aPeripheral> are the new output peripherals configurations for qout() and qqout() functions. nB is organised in the way to have only one output peripheral at the time. This function help to make order inside SET CONSOLE, SET PRINTER and SET ALTERNATE. If <cPeripheral> contains: "CON" SET CONSOLE is set to ON, SET PRINTER is set to OFF, SET ALTERNATE is set to OFF; "PRN" SET CONSOLE is set to OFF, SET PRINTER is set to ON, SET ALTERNATE is set to OFF; "LPT1" same as "PRN" otherwise SET CONSOLE is set to OFF, SET PRINTER is set to OFF, SET ALTERNATE is set to ON, SET ALTERNATE TO is set to <cPeripheral>. <aPeripheral> is organised this way: aPeripheral[1] = _SET_CONSOLE aPeripheral[2] = _SET_PRINTER aPeripheral[3] = _SET_ALTERNATE aPeripheral[4] = _SET_ALTFILE aPeripheral[5] = _SET_EXTRA aPeripheral[6] = _SET_EXTRAFILE This function is necessary becase SET ALTERNATE alone is not enough to print on the screen when the peripheral name is "CON" or to print on the printer when the peripheral name is "PRN" or "LPT1". In fact, in the first case, ROW() and COL() will not be updated, in the second case, PROW() and PCOL() will not be updated. This function returns an array organised in the same way as <aPeripheral> is, that shows the active output configuration. ##SETRPTEJECT()## ---------------------------------------------------------------- SETRPTEJECT( [<lbEject>] ) --> lPreviousEjectMode This function is used to set the eject mode after every page print for RPT(). If single sheet paper is used, then SETRPTEJECT(.T.) must be set; for continuous paper, SETRPTEJECT(.F.) is correct. The default value is .F.. <lbEject> logical or codeblock, is the eject mode to set. Default is no change, the starting value is .F. ##SETRPTLINES()## ---------------------------------------------------------------- SETRPTLINES() --> nRemainingLines This function is used to report the number of lines available before the completion of the page print for RPT(). See: <RPT()> ##SETVERB()## ---------------------------------------------------------------- SETVERB( <cSpecifier>, [<xNewSetting>], [<lOpenMode>] ) --> xPreviousValueSet <cSpecifier> a word that defines the kind of set is going to be considered. <xNewSetting> is the new value to set up. <lOpenMode> used only for some kind of set. This function is analogue to SET() but it uses a character string (with <cSpecifier>) and not a number to select the set. This is made to make easyer the work with macros. <cSpecifier> may contain: "EXACT" "FIXED" "DECIMALS" "DATEFORMAT" "EPOCH" "PATH" "DEFAULT" "EXCLUSIVE" "SOFTSEEK" "UNIQUE" "DELETED" "CANCEL" "TYPEAHEAD" "COLOR" "CURSOR" "CONSOLE" "ALTERNATE" "ALTFILE" "DEVICE" "EXTRA" "EXTRAFILE" "PRINTER" "PRINTFILE" "MARGIN" "BELL" "CONFIRM" "ESCAPE" "INSERT" "EXIT" "INTENSITY" "SCOREBOARD" "DELIMITERS" "DELIMCHARS" "WRAP" "MESSAGE" "MCENTER" ##SETVERB("EXACT")## ................................................................ obsolete SETVERB( "EXACT", [<lExact>] ) --> lPrevious If <lExact> is True, it forces exact comparison of character strings, including length. If it is False, character strings are compared until the left string length is exausted; that is that "" (the null string) is equal to any other string. Please note that the == operator is a comparison operator for exact match and using it, SETVERB("EXACT", .F.) will not work. The starting value is True. The recommanded value is True. ##SETVERB("FIXED")## ................................................................ SETVERB( "FIXED", [<lFixed>] ) --> lPrevious If <lFixed> contains True, numeric values are displayed ever with a fixed number of decimal digits, depending on the value set by SETVERB("DECIMALS"). The starting value is False. The recommended value is False: if you have to display a fixed number of decimal digits it is better to define a good display picture. ##SETVERB("DECIMALS")## ................................................................ SETVERB( "DECIMALS", [<nDecimals>] ) --> nPrevious <nDecimals> is the number of digits to display after the decimal position. This set is enabled of disabled with SETVERB("FIXED"). The starting value is 8. ##SETVERB("DATEFORMAT")## ................................................................ SETVERB( "DATEFORMAT", [<cDateFormat>] ) --> cPrevious <cDateFormat> is a character expression that specifies the date format. The starting value is "dd/mm/yyyy". Some date format examples: AMERICAN "mm/dd/yyyy" ANSI "yyyy.mm.dd" BRITISH "dd/mm/yyyy" FRENCH "dd/mm/yyyy" GERMAN "dd.mm.yyyy" ITALIAN "dd-mm-yyyy" JAPAN "yyyy/mm/dd" USA "mm-dd-yyyy" ##SETVERB("EPOCH")## ................................................................ SETVERB( "EPOCH", [<nYear>] ) --> nPrevious <nYear> specifies the base year of 100-year period in which all dates containing only twho year digits are assumed to fall. The starting value is 1900. ##SETVERB("PATH")## ................................................................ SETVERB( "PATH", [<cPath>] ) --> cPrevious <cPath> identifies the paths that nB uses when searching for a file not found in the current directory. The list of paths can be separated by commas or semicolons. The starting value is "". ##SETVERB("DEFAULT")## ................................................................ SETVERB( "DEFAULT", [<cPath>] ) --> cPrevious <cPath> identifies the default disk drive and directory. The starting value is "". ##SETVERB("EXCLUSIVE")## ................................................................ SETVERB( "EXCLUSIVE", [<lExclusive>] ) --> lPrevious If <lPath> is True, the default database (.DBF) file open is made in exclusive mode; in the other case, in shared mode. The starting value is True. ##SETVERB("SOFTSEEK")## ................................................................ SETVERB( "SOFTSEEK", [<lSoftSeek>] ) --> lPrevious If <lSoftSeek> is True, if a DBSEEK() index search fails, the record pointer is moved to the next record with a higher key. If it is False, in case of a DBSEEK() index search failure, the record pointer is moved at EOF(). The starting value is False. ##SETVERB("UNIQUE")## ................................................................ obsolete SETVERB( "UNIQUE", [<lUnique>] ) --> lPrevious If <lUnique> is True, during creation or update of .DBF indexes, if two or more records are found with the same key, only the first record will be inlcuded inside the index. If <lUnique> is False, duplicated record keys are allowed. The starting value is False. ##SETVERB("DELETED")## ................................................................ SETVERB( "DELETED", [<lDeleted>] ) --> lPrevious If <lDeleted> is True, record signed for deletion are not filtered, that is, these are still normally visible as they were not deleted. In the other case, they hare (in most cases) hidden to the user. The starting value is False. ##SETVERB("CANCEL")## ................................................................ SETVERB( "CANCEL", [<lCancel>] ) --> lPrevious If <lCancel> is True, enables [Alt]+[C] and [Ctrl]+[Break] as termination keys. In the other case, not. The starting value is True. ##SETVERB("TYPEAHEAD")## ................................................................ SETVERB( "TYPEAHEAD", [<nTypeAhead>] ) --> nPrevious <nTypeAhead> is the number of keystrokes the keyboard buffer can hold from a minimum of zero to a maximum of 4096. The starting value is 15. ##SETVERB("COLOR")## ................................................................ SETVERB( "TYPEAHEAD", [<cColorString>] ) --> cPrevious <nColorString> defines the normal screen colors. There are five couple of colors, but only three are really operative: standard This is the standard color used for screen output. enhanced This is the color used for highlighted screen output. border Normally unused. background Normally unused. unselected This is the color used for GET fields without focus. The default color string is "BG+/B,N/W,N/N,N/N,W/N" that is: standard bright Cyan on Blue enhanced Black on White border Black on Black background Black on Black unselected White on Black The following table explains the use of letters inside the color string. Note that the plus sign (+) means high intensity, the star (*) means blink and that + and * can be allyed only to the first letter inside a couple. Color Letter Monocrome Black N, Space Black Blue B Underline Green G White Cyan BG White Red R White Magenta RB White Brown GR White White W White Gray N+ Black Bright Blue B+ Bright Underline Bright Green G+ Bright White Bright Cyan BG+ Bright White Bright Red R+ Bright White Bright Magenta RB+ Bright White Bright Brown GR+ Bright White Bright White W+ Bright White Black U Underline Inverse Video I Inverse Video Blank X Blank ##SETVERB("CURSOR")## ................................................................ SETVERB( "CURSOR", [<lCursor>] ) --> lPrevious If <lCursor> is True, the cursor is showed, else it is hidden. The starting value is True. ##SETVERB("CONSOLE")## ................................................................ SETVERB( "CONSOLE", [<lConsole>] ) --> lPrevious If <lConsole> is True, the output of console commands is displayed on the screen, else it is not. The starting value is True. ##SETVERB("ALTERNATE")## ................................................................ SETVERB( "ALTERNATE", [<lAlternate>] ) --> lPrevious If <lAlternate> is True, the output of console commands is send also to a standard ASCII text file. The starting value is False. <setverb("altfile")> ##SETVERB("ALTFILE")## ................................................................ SETVERB( "ALTFILE", [<cAlternateFilename>], [<lAdditive>] ) --> cPrevious If SETVERB("ALTERNATE") is True, the output of the console is send also to <cAlternateFilename>, a standard ASCII file. If <lAdditive> is True, the output is appended to the ASCII file if it already exists, else it is erased first. <setverb("alternate")> ##SETVERB("DEVICE")## ................................................................ SETVERB( "DEVICE", [<cDevice>] ) --> cPrevious <cDevice> is the name of the device where SAY() will display its output. The starting value is "SCREEN", the alternative is "PRINTER". The recommended value is "SCREEN". ##SETVERB("EXTRA")## ................................................................ SETVERB( "EXTRA", [<lExtra>] ) --> lPrevious If <lExtra> is True, the output of console commands is send also to a standard ASCII text file. The starting value is False. <setverb("extrafile")> ##SETVERB("EXTRAFILE")## ................................................................ SETVERB( "EXTRAFILE", [<cExtraFilename>], [<lAdditive>] ) --> cPrevious If SETVERB("EXTRA") is True, the output of the console is send also to <cExtraFilename>, a standard ASCII file. If <lAdditive> is True, the output is appended to the ASCII file if it already exists, else it is erased first. <setverb("extra")> ##SETVERB("PRINTER")## ................................................................ SETVERB( "PRINTER", [<lPrinter>] ) --> lPrevious If <lPrinter> is True, the output of console commands is also printed, else it is not. The starting value is False. ##SETVERB("PRINTFILE")## ................................................................ SETVERB( "PRINTFILE", [<cPrintFileName>] ) --> cPrevious <cPrintFileName> is the name of the printer peripheral name. The starting value is "" (null string). ##SETVERB("MARGIN")## ................................................................ SETVERB( "MARGIN", [<nPageOffset>] ) --> nPrevious <nPageOffset> is the positive number of column to be used as a left margin for all printer output. The starting value is 0. ##SETVERB("BELL")## ................................................................ SETVERB( "BELL", [<lBell>] ) --> lPrevious If <lBell> is True, the sound of the bell is used to get the attention of the user when some wrong actions are made. The starting value is False. ##SETVERB("CONFIRM")## ................................................................ SETVERB( "CONFIRM", [<lConfirm>] ) --> lPrevious If <lConfirm> is False, the GET is simply terminated typing over the end of the get field; in the other case (True), the GET is terminated only pressing an "exit key". The starting value is True. ##SETVERB("ESCAPE")## ................................................................ SETVERB( "ESCAPE", [<lEscape>] ) --> lPrevious If <lEscape> is True, the [Esc] key is enabled to be a READ exit key, in the other case not. The starting value is True. The recommanded value is True. ##SETVERB("INSERT")## ................................................................ SETVERB( "INSERT", [<lInsert>] ) --> lPrevious If <lInsert> is True, the data editing is in INSERT mode, in the other case, it is in OVERWRITE mode. The starting value is True. ##SETVERB("EXIT")## ................................................................ SETVERB( "EXIT", [<lExit>] ) --> lPrevious If <lExit> is True, [Up] and [Down] key may be used as exit key when the cursor is (respectively) on the first or on the last GET field. In the other case not. The starting value is False. The recommanded value is False. ##SETVERB("INTENSITY")## ................................................................ SETVERB( "INTENSITY", [<lIntensity>] ) --> lPrevious If <lIntensitiy> is True, the display of standard and enhanced display colors are enabled. In the other case, only standard colors are enabled. The starting value is True. The recommanded value is True. ##SETVERB("SCOREBOARD")## ................................................................ SETVERB( "SCOREBOARD", [<lScoreboard>] ) --> lPrevious If <lScoreboard> is True, the display of messages from READ() and MEMOREAD() is allowed; in the order case not. The starting value is Fase. The recommanded value is Fase: nB do not support scoreborad. ##SETVERB("DELIMITERS")## ................................................................ SETVERB( "DELIMITERS", [<lDelimiters>] ) --> lPrevious If <lDelimiters> is True, GET variables appear on the screen delimited with the delimiter symbols. In the other case, GET variables are not delimitd this way, but only with the use of different colors. The starting value is Fase. The recommanded value is Fase: the use of delimiters creates one more truble when designing a screen mask. ##SETVERB("DELIMCHARS")## ................................................................ SETVERB( "DELIMCHARS", [<cDelimterCharacters>] ) --> cPrevious <cDelimterCharacters> are the delimiter characters used to delimit a GET field when SETVERB("DELIMITERS") is True. The starting value is "::". ##SETVERB("WRAP")## ................................................................ SETVERB( "WRAP", [<lWrap>] ) --> lPrevious If <lWrap> is True, the wrapping of the highlight in MENUs should be active, but this option is actually not active and all works as it is False. The starting value is Fase. ##SETVERB("MESSAGE")## ................................................................ SETVERB( "MESSAGE", [<nMessageRow>] ) --> nPrevious <nMessageRow> is the row number where the @..PROMPT message line should appear on the screen. This option is not supported. The starting value is 0. ##SETVERB("MCENTER")## ................................................................ SETVERB( "MCENTER", [<lMessageCenter>] ) --> lPrevious If <lMessageCenter> is True, the @..PROMPT message line should appear centered on the screen. This option is not supported. The starting value is False. ##STRADDEXTENTION()## ---------------------------------------------------------------- STRADDEXTENTION( <cName>, <cExt> ) --> cCompleteName <cName> the file name (with or without path) that is probably without extention. <cExt> the extention that must be added to <cName> if it has not one. This function check <cName> for the presence of an extention. It it has not one, <cExt> will be added. ##STRCUTEXTENTION()## ---------------------------------------------------------------- STRCUTEXTENTION( <cName> ) --> cName <cName> the file name (with or without path) that is probably with extention. This function check <cName> for the presence of an extention. It it has one, the extention is removed. ##STRDRIVE()## ---------------------------------------------------------------- STRDRIVE( <cName> ) --> cDrive <cName> the file name (with or without path) that contains the drive letter. This function tries to extract the drive letter information from <cName>. ##STREXTENTION()## ---------------------------------------------------------------- STREXTENTION( <cName> ) --> cExtention <cName> the file name (with or without path) that contains an extention. This function tries to extract the extention information from <cName>. ##STRFILE()## ---------------------------------------------------------------- STRFILE( <cName> ) --> cFileName <cName> the file name with or without path. This function tries to extract the file name without path from <cName>. ##STRFILEFIND()## ---------------------------------------------------------------- STRFILEFIND( <cName>, <cPath> ) --> cFileName <cName> the file name or pathname containing the file name to search inside the <cPath> list. <cPath> a list of paths separated with semicolon (just like Dos does), where <cFile> should be searched. If your file is to be found on different possible positions, this function search the first place where the file is found and returns a valid pathname to that file. ##STRGETLEN()## ---------------------------------------------------------------- STRGETLEN( <xExpr>, <cPicture> ) --> nFieldLenght <xExpr> a generic expression. <cPicture> the picture string. This function returns the lenght of field when using <xExpr> with <cPicture>. ##STRLISTASARRAY()## ---------------------------------------------------------------- STRLISTASARRAY( <cList>, [<cDelimiter>] ) --> aList <cList> a character string containing a list separated with <cDelimiter>. <cDelimiter> the delimiter used to separate the elements contained inside the list. This function transform a character string list into an array. ##STROCCURS()## ---------------------------------------------------------------- STROCCURS( <cSearch>, <cTarget> ) --> nOccurrence <cSearch> the search string to find inside <cTarget>. <cTarget> the string to be searched for the presence of <cSearch>. This function returns the number of occurrence that <cSearch> is contained inside <cTarget>. ##STRPARENT()## ---------------------------------------------------------------- STRPARENT( <cName> ) --> cParentPath <cName> the pathname. This function tries to return a parent path from <cName>. ##STRPATH()## ---------------------------------------------------------------- STRPATH( <cName> ) --> cPath <cName> the pathname. This function tries to extract the path from <cName>. ##STRTEMPPATH()## ---------------------------------------------------------------- STRTEMPPATH() --> cTempPath This function returns a temporary path searching for possible definitions inside the environmental variables. ##STRXTOSTRING()## ---------------------------------------------------------------- STRXTOSTRING( <xVar>, [<cType>] ) --> cTrasformed_to_string <xVar> is the data of any type to be converted into string. <cType> is the type of the data contained inside <xVar>. This function returns <xVar> transformed into a character string. ##TB()## ---------------------------------------------------------------- TB( [<nTop>], [<nLeft>], [<nBottom>], [<nRight>], [<acCol>], [<acColSayPic>], [<acColTopSep>], [<acColBodySep>], [<acColBotSep>], [<acColHead>], [<acColFoot>], [<alColCalc>], [<abColValid>], [<abColMsg>], [<cColor>], [<abColColors>], [<nFreeze>], [<lModify>], [<lAppend>], [<lDelete>], [<lButtons> | <aButtons>] ) --> NIL <nTop>, <nLeft>, <nBottom>, <nRight> defines the screen area where browse have to take place. <acCol> is the columns array to be included into the browse. <acColSayPic> is the picture array. <acColTopSep> is the top separation array: default is chr(194)+chr(196). <acColBodySep> is the body sepatation array: default is chr(179). <acColBotSep> is the bottom separation array: default is chr(193)+chr(196). <acColHead> is the header array for every column. <acColFoot> is the footer array for every column. <alColCalc> is the array that identify the calculated column (not editable). True (.T.) means calculated. <abColValid> is the validation array that specify when a field is properly filled. The condition must be specifyed in code block format. <abColMsg> is the message array that permits to show information at the bottom of browse area. The array must be composed with code blocks whitch result with a character string. <cColor> is the color string: it may be longer than the usal 5 elements. <abColColors> is the color code block array. The code block receive as parameter the value contained inside the field and must return an array containing two numbers: they correspond to the two color couple from <cColor>. <nFreeze> indicates the number of columens to be left frozen on the left side. <lModify> indicates whether the browse can modify data. <lDelete> indicates whether the browse can delete and recall records. <lButtons> if True, default buttons are displayed. <aButtons> array of buttons. aButtons[n][1] N, the nth button row position; aButtons[n][2] N, the nth button column position; aButtons[n][3] C, the nth button text; aButtons[n][4] B, the nth button code block. This function, called without parameters, starts the browse of the active Alias, and if relations are established, the browse includes also related data. Please note that due to an unresolved problem, the field names contained inside <acCol> should better contain also the alias (ALIAS->FIELD_NAME). See also the examples. ##TEXT()## ---------------------------------------------------------------- TEXT( <cText> ) --> NIL Shows the text contained into <cText>. ##TGLINSERT()## ---------------------------------------------------------------- TGLINSERT() --> NIL Toggle the global insert mode and the cursor shape. ##TIMEX2N()## ---------------------------------------------------------------- TIMEX2N( [<nHH>], [<nMM>], [<nSS>] ) --> nTime <nHH> is the number of hours. <nMM> is the number of minuts. <nSS> is the number of seconds. This function calculate the "time number" that is a number represanting days and/or portion of a day: 1 is 1 day or 24 hours, 0.5 is 12 hours, and so on. ##TIMEN2H()## ---------------------------------------------------------------- TIMEN2H( <nTime> ) --> nHours <nTime> is the "time number" that is a number represanting days and/or portion of a day: 1 is 1 day or 24 hours, 0.5 is 12 hours, and so on. This function returns the integer number of hours conatined inside <nTime>. ##TIMEN2M()## ---------------------------------------------------------------- TIMEN2M( <nTime> ) --> nMinutes <nTime> is the "time number" that is a number represanting days and/or portion of a day: 1 is 1 day or 24 hours, 0.5 is 12 hours, and so on. This function returns the integer number of minutes conatined inside <nTime> after subtracting the hours. ##TIMEN2S()## ---------------------------------------------------------------- TIMEN2S( <nTime> ) --> nSeconds <nTime> is the "time number" that is a number represanting days and/or portion of a day: 1 is 1 day or 24 hours, 0.5 is 12 hours, and so on. This function returns the number of seconds (with evenutal decimals) conatined inside <nTime> after subtracting the hours and the minutes. ##TRUESETKEY()## ---------------------------------------------------------------- TRUESETLEY( <nInkeyCode>, <bAction> ) --> .T. This function is equivalent to SETKEY() but it returns ever .T. ##WAITFILEEVAL()## ---------------------------------------------------------------- WAITFILEEVAL( <lClose> ) --> .T. Shows a wait bar calling WAITPROGRESS() for operation on records of a database. If there is no index active, it is equivalent to WAITPROGRES(RECNO()/LASTREC()). if an index is active, this cannot work, so an increment for each call is made: WAITPROGRES((nIncrement++)/LASTREC()). This function must be closed calling it with the <lClose> parameter to true (.T.). This way, internal counters are closed and WAITPROGRESS() is closed too. ##WAITFOR()## ---------------------------------------------------------------- WAITFOR( [<cMessage>] ) --> NIL Shows <cMessage> until it is called again. The wait window is closed when called without parameter or with NIL. ##WAITPROGRESS()## ---------------------------------------------------------------- WAITPROGRESS( [<nPercent>] ) --> .T. Shows a wait bar on the screen top depending on the value contained into <nPercent>. <nPercent> starts form 0 and ends to 1 (100%). If a value of one or more, or NIL is passed, the wait window is closed. ##NORMAL COMMAND SUBSTITUTION## ================================================================ CA-Clipper works only with functions and commands are converted into fuction using the STD.CH. Here are described some command replacement that can be used also with nB macroes. ##?## ---------------------------------------------------------------- ? [<exp list>] qout([<exp list>]) ?? [<exp list>] qqout([<exp list>]) ##@BOX## ---------------------------------------------------------------- @ <nTop>, <nLeft>, <nBottom>, <nRight> BOX <cnBoxString> [COLOR <cColorString>] dispbox(<nTop>, <nLeft>, <nBottom>, <nRight>, [<cnBoxString>], [<cColorString>]) ##@TO## ---------------------------------------------------------------- @ <nTop>, <nLeft> TO <nBottom>, <nRight> DOUBLE [COLOR <cColorString>] dispbox(<nTop>, <nLeft>, <nBottom>, <nRight>, 2 [,<cColorString>]) @ <nTop>, <nLeft> TO <nBottom>, <nRight> [COLOR <cColorString>] dispbox(<nTop>, <nLeft>, <nBottom>, <nRight>, 1 [,<cColorString>]) @ <nTop>, <nLeft> CLEAR [TO <nBottom>, <nRight>] scroll([<nTop>], [<nLeft>], [<nBottom>, <nRight>]) setpos(<nRow>, <nCol>) ##@GET## ---------------------------------------------------------------- @ <nTop>, <nLeft> GET <Var> [PICTURE <cGetPicture>] [COLOR <cColorString>] [WHEN <lPreExpression>] [VALID <lPostExpression>] setpos(<nTop>, <nLeft>) aadd( GetList, _GET_( <Var>, "<Var>", <cGetPicture>, [{|| <lPostExpression>}], [{|| <lPreExpression>}] ):display() ) atail(GetList):colorDisp(<cColorString>) ##@SAY## ---------------------------------------------------------------- @ <nTop>, <nLeft> SAY <exp> [COLOR <cColorString>] devpos(<nTop>, <nLeft>) devout(<exp> [, <cColorString>]) @ <nTop>, <nLeft> SAY <exp> PICTURE <cSayPicture> [COLOR <cColorString>] devpos(<nTop>, <nLeft>) devoutpic(<exp>, <cSayPicture>, [<cColorString>]) ##APPEND## ---------------------------------------------------------------- APPEND BLANK dbappend() ##CLEAR## ---------------------------------------------------------------- CLEAR GETS ReadKill(.T.) GetList := {} CLEAR SCREEN | CLS Scroll() SetPos(0,0) CLEAR Scroll() SetPos(0,0) ReadKill(.T.) GetList := {} ##CLOSE## ---------------------------------------------------------------- CLOSE dbCloseArea() CLOSE <idAlias> <idAlias>->( dbCloseArea() ) CLOSE ALTERNATE Set(19, "") CLOSE DATABASES dbCloseAll() CLOSE INDEXES dbClearIndex() ##COMMIT## ---------------------------------------------------------------- COMMIT dbCommitAll() ##COUNT## ---------------------------------------------------------------- COUNT TO <idVar> [FOR <lForCondition>] [WHILE <lWhileCondition>] [NEXT <nNextRecords>] [RECORD <nRecord>] [REST] [ALL] dbeval( {|| <idVar> := <idVar> +1 }, {|| <lForCondition> }, {|| <lWhileCondition> }, <nNextRecords>, <nRecord>, <lRest> ) ##DEFAULT## ---------------------------------------------------------------- DEFAULT <xVar> TO <xDefaultValue> DEFAULT( @<xVar>, <xDefaultValue> ) --> xVar ##DELETE## ---------------------------------------------------------------- DELETE dbDelete() DELETE [FOR <lForCondition>] [WHILE <lWhileCondition>] [NEXT <nNextRecords>] [RECORD <nRecord>] [REST] [ALL] dbeval( {|| dbDelete()}, {|| <lForCondition> }, {|| <lWhileCondition> }, <nNextRecords>, <nRecord>, <lRest> ) DELETE FILE <xcFile> ferase( <cFile> ) ##EJECT## ---------------------------------------------------------------- EJECT qqout( chr(13) ) ##ERASE## ---------------------------------------------------------------- ERASE <xcFile> ferase( <cFile> ) ##FIND## ---------------------------------------------------------------- FIND <xcSearchString> dbSeek( <cSearchString> ) ##GO## ---------------------------------------------------------------- GO[TO] <nRecord> dbgoto(nRecord) GO[TO] BOTTOM dbGoBottom() GO[TO] TOP dbgotop() ##INDEX ON## ---------------------------------------------------------------- INDEX ON <expKey> TO <xcIndexName> [UNIQUE] [FOR <lForCondition>] [WHILE <lWhileCondition>] [[EVAL <lEvalCondition>] [EVERY <nRecords>]] [ASCENDING|DESCENDING] ordCondSet( [<cForCondition>], [<bForCondition>],, [<bWhileCondition>], [<bEvalCondition>], [<nRecords>], RECNO(),,,, <lDescending> ) ordCreate( <cIndexName>,, <cExpKey>, <bExpKey>, <lUnique> ) ##READ## ---------------------------------------------------------------- READ ReadModal(GetList) GetList := {} READ SAVE ReadModal(GetList) ##RECALL## ---------------------------------------------------------------- RECALL dbRecall() RECALL [FOR <lForCondition>] [WHILE <lWhileCondition>] [NEXT <nNextRecords>] [RECORD <nRecord>] [REST] [ALL] dbeval( {|| dbRecall()}, {|| <lForCondition> }, {|| <lWhileCondition> }, <nNextRecords>, <nRecord>, <lRest> ) ##REINDEX## ---------------------------------------------------------------- REINDEX [EVAL <lEvalCondition>] [EVERY <nRecords>] ordCondSet(,,,, [<bEvalCondition>], [<nRecords>],,,,,,,) ordListRebuild() ##RENAME## ---------------------------------------------------------------- RENAME <xcOldFile> TO <xcNewFile> frename( <cOldFile>, <cNewFile> ) ##REPLACE## ---------------------------------------------------------------- REPLACE <idField1> WITH <exp1> [, <idField2> WITH <exp2>...] [FOR <lForCondition>] [WHILE <lWhileCondition>] [NEXT <nNextRecords>] [RECORD <nRecord>] [REST] [ALL] dbeval( {|| <idField1> := <exp1> [, <idField2> := <exp2>...]}, {|| <lForCondition> }, {|| <lWhileCondition> }, <nNextRecords>, <nRecord>, <lRest> ) REPLACE <idField1> WITH <exp1> <idField1> := <exp1> ##RESTORE## ---------------------------------------------------------------- RESTORE SCREEN FROM <cScreen> restscreen( 0, 0, Maxrow(), Maxcol(), <cScreen> ) ##SAVE## ---------------------------------------------------------------- SAVE SCREEN TO <cScreen> <cScreen> := savescreen( 0, 0, maxrow(), maxcol() ) ##SEEK## ---------------------------------------------------------------- SEEK <expSearch> [SOFTSEEK] dbSeek( <expSearch> [, <lSoftSeek>] ) ##SELECT## ---------------------------------------------------------------- SELECT <xnWorkArea> | <idAlias> dbSelectArea( <nWorkArea> | <cIdAlias> ) ##SET## ---------------------------------------------------------------- SET ALTERNATE TO <xcFile> [ADDITIVE] Set( 19, <cFile>, lAdditive ) SET ALTERNATE ON | OFF | <xlToggle> Set( 18, "ON" | "OFF" | <lToggle> ) SET BELL ON | OFF | <xlToggle> Set( 26, "ON" | "OFF" | <lToggle> ) SET COLOR | COLOUR TO (cColorString) SetColor( cColorString ) SET CONFIRM ON | OFF | <xlToggle> Set( 27, "ON" | "OFF" | <lToggle> ) SET CONSOLE ON | OFF | <xlToggle> Set( 17, "ON" | "OFF" | <lToggle> ) SET CURSOR ON | OFF | <xlToggle> SetCursor( 1 | 0 | iif( <lToggle>, 1, 0 ) ) SET DATE FORMAT [TO] <cDateFormat> Set( 4, <cDateFormat> ) SET DECIMALS TO Set( 3, 0 ) SET DECIMALS TO <nDecimals> Set( 3, <nDecimals> ) SET DEFAULT TO Set( 7, "" ) SET DEFAULT TO <xcPathspec> Set( 7, <cPathspec> ) SET DELETED ON | OFF | <xlToggle> Set( 11, "ON" | "OFF" | <lToggle> ) SET DELIMITERS ON | OFF | <xlToggle> Set( 33, "ON" | "OFF" | <lToggle> ) SET DELIMITERS TO [DEFAULT] Set( 34, "::" ) SET DELIMITERS TO <cDelimiters> Set( 34, <cDelimiters> ) SET DEVICE TO SCREEN | PRINTER Set( 20, "SCREEN" | "PRINTER" ) SET EPOCH TO <nYear> Set( 5, <nYear> ) SET ESCAPE ON | OFF | <xlToggle> Set( 28, "ON" | "OFF" | <lToggle> ) SET EXACT ON | OFF | <xlToggle> Set( 1, "ON" | "OFF" | <lToggle> ) SET EXCLUSIVE ON | OFF | <xlToggle> Set( 8, "ON" | "OFF" | <lToggle> ) SET FILTER TO dbclearfilter() SET FILTER TO <lCondition> dbsetfilter( <bCondition>, <cCondition> ) SET FIXED ON | OFF | <xlToggle> Set( 2, "ON" | "OFF" | <lToggle> ) SET INDEX TO [<xcIndex> [, <xcIndex1>... ] ] ordListClear() ordListAdd( cIndex ) ordListAdd( cIndex1 ) ... SET INTENSITY ON | OFF | xlToggle Set( 31, "ON" | "OFF" | lToggle ) SET KEY <nInkeyCode> [TO] SetKey( <nInkeyCode>, NIL ) SET KEY <nInkeyCode> TO [<idProcedure>] SetKey( <nInkeyCode>, { |p, l, v| idProcedure(p, l, v)} ) SET MARGIN TO Set( 25, 0 ) SET MARGIN TO [<nPageOffset>] Set( 25, <nPageOffset> ) SET MESSAGE TO Set( 36, 0 ) Set( 37, .F. ) SET MESSAGE TO [<nRow> [CENTER | CENTRE]] Set( 36, nRow ) Set( 37, lCenter ) SET ORDER TO [<nIndex>] ordSetFocus( <nIndex> ) SET PATH TO Set( 6, "" ) SET PATH TO [<xcPathspec> [, <cPathspec1>... ] ] Set( 6, <cPathspec> [, <cPathspec1>... ] ) SET PRINTER ON | OFF | xlToggle Set( 23, "ON" | "OFF" | lToggle ) SET PRINTER TO Set( 24, "" ) SET PRINTER TO [<xcDevice>|<xcFile> [ADDITIVE]] Set( 24, <cDevice>|<cFile>, lAdditive ) SET RELATION TO dbclearrelation() SET RELATION TO [<expKey1> INTO <xcAlias1>] [, [TO] <expKey2> INTO <xcAlias2>...] [ADDITIVE] if !lAdditive dbClearRel() end dbSetRelation( <cAlias1>, <{|| expKey1}, ["<expKey1>"] ) dbSetRelation( <cAlias2>, <{|| expKey2}, ["<expKey1>"] ) SET SCOREBOARD ON | OFF | xlToggle Set( 32, "ON" | "OFF" | lToggle ) SET SOFTSEEK ON | OFF | xlToggle Set( 9, "ON" | "OFF" | lToggle ) SET TYPEAHEAD TO <nKeyboardSise> Set( 14, <nKeyboardSise> ) SET UNIQUE ON | OFF | xlToggle Set( 10, "ON" | "OFF" | lToggle ) SET WRAP ON | OFF | xlToggle Set( 35, "ON" | "OFF" | lToggle ) ##SKIP## ---------------------------------------------------------------- SKIP [<nRecords> [ALIAS <idAlias>|<nWorkArea>] [<idAlias>|<nWorkArea> -> ]( dbSkip([<nRecords>]) ) ##STORE## ---------------------------------------------------------------- STORE <value> TO <variable> <variable> := <value> ##SUM## ---------------------------------------------------------------- SUM <nExp1> [, <nExp2>...] TO <idVar1> [, <idVar2>...] [FOR <lForCondition>] [WHILE <lWhileCondition>] [NEXT <nNextRecords>] [RECORD <nRecord>] [REST] [ALL] dbeval( {|| <idVar1> := <idVar1> + <nExp1> [, <idVar2> := <idVar2> + <nExp2>...] }, {|| <lForCondition> }, {|| <lWhileCondition> }, <nNextRecords>, <nRecord>, <lRest> ) ##UNLOCK## ---------------------------------------------------------------- UNLOCK dbUnlock() UNLOCK ALL dbUnlockAll() ##USE## ---------------------------------------------------------------- USE dbclosearea() USE [<xcDatabase> [INDEX <xcIndex1> [, <xcIndex2>...] [ALIAS <xcAlias>] [EXCLUSIVE|SHARED] [NEW] [READONLY] [VIA <cDriver>]] dbUseArea( [<lNewArea>], [<cDriver>], <cDatabase>, [<cAlias>], [<lShared>], [<lReadOnly>] ) [dbSetIndex( <cIndex1> )] [dbSetIndex( <cIndex2> )] ... ##nB COMMAND SUBSTITUTION FUNCTIONS## ================================================================ Inside nB there are many functions made only in substitution to other CA-Clipper commands. ##GET## ---------------------------------------------------------------- @ <nTop>, <nLeft> GET <Var> [PICTURE <cGetPicture>] [COLOR <cColorString>] [WHEN <lPreExpression>] [VALID <lPostExpression>] Get( @<aGetList>, [<nTop>], [<nLeft>], { |x| iif( pcount() > 0, <Var> := x, <Var> ) } [<cGetPicture>], [<cColorString>], [<bPreExpression>], [<bValid>] ) <aGetList> is the get list array that will be increased with this get(). ##SAY## ---------------------------------------------------------------- @ <nTop>, <nLeft> SAY <exp> PICTURE <cSayPicture> [COLOR <cColorString>] Say( <nTop>, <nLeft>, <cVar>, [<cSayPicture>], [<cColorString>] ) ##APPEND FROM## ---------------------------------------------------------------- APPEND FROM <xcFile> [FIELDS <idField list> [<scope>] [WHILE <lCondition>] [FOR <lCondition>] [VIA <xcDriver>] dbApp( <cFileName>, [<acFields>], [<bForCondition>], [<bWhileCondition>], [<nNextRecords>], [<nRecord>], [<lRest>], [<cDriver>] ) APPEND FROM <xcFile> [FIELDS <idField list> [<scope>] [WHILE <lCondition>] [FOR <lCondition>] DELIMITED <xcDelimiter> dbDelim( .f., <cFileName>, [<cDelimiter>], [<acFields>], [<bForCondition>], [<bWhileCondition>], [<nNextRecords>], [<nRecord>], [<lRest>] ) APPEND FROM <xcFile> [FIELDS <idField list> [<scope>] [WHILE <lCondition>] [FOR <lCondition>] SDF dbSDF( .f., <cFileName>, [<acFields>], [<bForCondition>], [<bWhileCondition>], [<nNextRecords>], [<nRecord>], [<lRest>] ) ##CONTINUE## ---------------------------------------------------------------- CONTINUE dbContinue() ##COPY## ---------------------------------------------------------------- COPY FILE <xcSourceFile> TO <xcTargetFile>|<xcDevice> CopyFile( <cSourceFile>, <cTargetFile>|<cDevice> ) COPY STRUCTURE [FIELDS <idField list>] TO <xcDatabase> dbCopyStruct( <cDatabase>, [<acFields>] ) COPY STRUCTURE EXTENDED TO <xcExtendedDatabase> dbCopyXStruct( <cExtendedDatabase> ) COPY TO <xcFile> [FIELDS <idField list> [<scope>] [WHILE <lCondition>] [FOR <lCondition>] [VIA <xcDriver>] dbCopy( <cFileName>, [<acFields>], [<bForCondition>], [<bWhileCondition>], [<nNextRecords>], [<nRecord>], [<lRest>], [<cDriver>] ) COPY TO <xcFile> [FIELDS <idField list> [<scope>] [WHILE <lCondition>] [FOR <lCondition>] DELIMITED <xcDelimiter> dbDelim( .t., <cFileName>, [<cDelimiter>], [<acFields>], [<bForCondition>], [<bWhileCondition>], [<nNextRecords>], [<nRecord>], [<lRest>] ) COPY TO <xcFile> [FIELDS <idField list> [<scope>] [WHILE <lCondition>] [FOR <lCondition>] SDF dbSDF( .t., <cFileName>, [<acFields>], [<bForCondition>], [<bWhileCondition>], [<nNextRecords>], [<nRecord>], [<lRest>] ) ##CREATE## ---------------------------------------------------------------- CREATE <xcDatabase> FROM <xcExtendedDatabase> [NEW] [ALIAS <cAlias>] [VIA <cDriver>] dbOldCreate( <cDatabase>, <cExtendedDatabase>, [<cDriver>], [<lNew>], [<cAlias>] ) ##JOIN## ---------------------------------------------------------------- JOIN WITH <xcAlias> TO <xcDatabase> [FOR <lCondition>] [FIELDS <idField list>] dbJoin( <cAlias>, <cDatabase>, [<acFields>], [<bForCondition>] ) ##KEYBOARD## ---------------------------------------------------------------- KEYBOARD <cString> Keyboard( [<cString>] ) --> NIL ##LABEL FORM## ---------------------------------------------------------------- LABEL FORM <xcLabel> [TO PRINTER] [TO FILE <xcFile>] [NOCONSOLE] [<scope>] [WHILE <lCondition>] [FOR <lCondition>] [SAMPLE] dbLabelForm( <cLabel>, [<lToPrinter>], [<cFile>], [<lNoConsole>], [<bForCondition>], [<bWhileCondition>], [<nNextRecords>], [<nRecord>], [<lRest>], [<lSample>] ) ##LIST## ---------------------------------------------------------------- LIST <exp list> [TO PRINTER] [TO FILE <xcFile>] [<scope>] [WHILE <lCondition>] [FOR <lCondition>] [OFF] dbList( [<lToDisplay>], <abListColumns>, [<lAll>], [<bForCondition>], [<bWhileCondition>], [<nNextRecords>], [<nRecord>], [<lRest>], [<lToPrinter>], [<cFileName>] ) ##LOCATE## ---------------------------------------------------------------- LOCATE [<scope>] FOR <lCondition> [WHILE <lCondition> dbLocate( [<bForCondition>], [<bWhileCondition>], [<nNextRecords>], [<nRecord>], [<lRest>] ) ##PACK## ---------------------------------------------------------------- PACK dbPack() ##PUBLIC## ---------------------------------------------------------------- PUBLIC <idMemvar> MemPublic( <cMemvarName>|<acMemvarNames> ) ##QUIT## ---------------------------------------------------------------- QUIT Quit() ##RELEASE## ---------------------------------------------------------------- RELEASE <idMemvar> MemRelease( <cMemvarName>|<acMemvarNames> ) ##REPORT FORM## ---------------------------------------------------------------- REPORT FORM <xcReport> [TO PRINTER] [TO FILE <xcFile>] [NOCONSOLE] [<scope>] [WHILE <lCondition>] [FOR <lCondition>] [PLAIN | HEADING <cHeading>] [NOEJECT] [SUMMARY] RF( <cForm>, [<bForCondition>], [<bWhileCondition>], [<nNext>], [<nRecord>], [<lRest>], [<lPlain>], [<cbHeading>], [<lBeforeEject>], [<lSummary>], [<lDate>], [<acExtra>] ) --> NIL ##RESTORE FROM## ---------------------------------------------------------------- RESTORE FROM <xcMemFile> [ADDITIVE] MemRestore( <cMemFileName>, [<lAdditive> ) ##RUN## ---------------------------------------------------------------- RUN <xcCommandLine> Run( <cCommand> ) ##SAVE TO## ---------------------------------------------------------------- SAVE TO <xcMemFile> [ALL [LIKE|EXCEPT <skeleton>]] MemSave( <cMemFileName>, [<cSkeleton>], [<lLike>] ) ##SET FUNCTION## ---------------------------------------------------------------- SET FUNCTION <nFunctionKey> TO <cString> SetFunction( <nFunctionKey>, <cString> ) ##SORT## ---------------------------------------------------------------- SORT TO <xcDatabase> ON <idField1> [/[A|D][C]] [, <idField2> [/[A|D][C]] ...] [<scope>] [WHILE <lCondition>] [FOR <lCondition>] dbSort( <cDatabase>, [<acFields>], [<bForCondition>], [<bWhileCondition>], [<nNextRecords>], [<nRecord>], [<lRest>] ) ##TOTAL## ---------------------------------------------------------------- TOTAL ON <expKey> [FIELDS <idField list>] TO <xcDatabase> [<scope>] [WHILE <lCondition>] [FOR <lCondition>] dbTotal( <cDatabase>, <bKey>, [<acFields>, [<bForCondition>], [<bWhileCondition>], [<nNextRecords>], [<nRecord>], [<lRest> ) ##UPDATE## ---------------------------------------------------------------- UPDATE FROM <xcAlias> ON <expKey> [RANDOM] REPLACE <idField1> WITH <exp> [, <idField2> WITH <exp> ...] dbUpdate( <cAlias>, <bKey>, [<lRandom>], [<bReplacement>] ) Example: dbUpdate( "INVOICE", {|| LAST}, .T.,; {|| FIELD->TOTAL1 := INVOICE->SUM1,; FIELD->TOTAL2 := INVOICE->SUM2 } ) ##ZAP## ---------------------------------------------------------------- ZAP dbZap() ##RPT - THE nB PRINT FUNCTION## ================================================================ The function RPT() helps to print ASCII file containing Memvars, Fields and print commands. RPT() is accessible from the DOC() menu. ##RPT - MEMVARS AND FIELDS## ---------------------------------------------------------------- As usual with standard word processors, variables are written delimited with "<" (Alt+174) and ">" (Alt+175). Inside these delimiters can find place character Memvars, character Fields and functions giving a character result. The RPT() function generates a public variable n_Lines that contains the available lines inside the actual sheet. Every time a line is written, this value is reduced, until a new page is reached and then it will start again from the maximum value. It is usefull to read this variable to determinate if there is enough space or it is better to change page. ##RPT - COMMANDS## ================================================================ The function RPT() recognise some print commands. These commands starts with the asterisk (*) simbol. This means that "*" is a print command prefix. It follows the command sintax. ##*COMMAND## ---------------------------------------------------------------- *COMMAND <cStatement> <cStatement> ......... *END The lines contained inside *COMMAND - *END are executed with the nB macro interpreter. ##*DBSKIP## ---------------------------------------------------------------- *DBSKIP [<nSkip>] It Executes a dbskip() on the active Alias. ##*FOOT## ---------------------------------------------------------------- *FOOT <cFooter> <cFooter> ...... *END The lines contained inside *FOOT - *END are printed each time at the bottom of pages. ##*HEAD## ---------------------------------------------------------------- *HEAD <cHeader> <cHeader> ...... *END The lines contained inside *HEAD - *END are printed each time at the top of pages. ##*IF## ---------------------------------------------------------------- *IF <lCondition> ........ ........ *END If the condition <lCondition> is true, the lines contained inside *IF - *END are printed. ##*INSERT## ---------------------------------------------------------------- *INSERT <cFileName> Includes the text contained into the file <cFileName>. ##*LEFT## ---------------------------------------------------------------- *LEFT <nLeftBorder> The <nLeftBorder> is the number of column to be left blank as a left border. ##*LPP## ---------------------------------------------------------------- *LPP <nLinesPerPage> It determinates the page length expressed in lines. After printing the <nLinesPerPage>th line, a form feed is sent. ##*NEED## ---------------------------------------------------------------- *NEED <nLinesNeeded> If the available lines are less then <nLinesNeeded>, the follwing text will be printed on the next page. ##*PA## ---------------------------------------------------------------- *PA Jumps to a new page. ##*REM## ---------------------------------------------------------------- *REM | *COMMENT [<comment_line>] It adds a comment that will not be printed. ##*WHILE## ---------------------------------------------------------------- *WHILE <lCondition> ...... ...... *END The lines contained inside *WHILE - *END are printed as long as <lCondition> is true. ##RPT - EXAMPLES## ================================================================ It follows some example of text to be printed with the RPT() function. Example's lines are numbered. Line numbers must not be part of a real RPT text files. ##PAGE DEFINITION## ---------------------------------------------------------------- Margins are defined with *HEAD, *FOOT and *LEFT commands. In the following example is defined: Top 2 lines; Bottom 2 lines; Left 10 characters. The right margin is not defined as it depends on the lines length that will be printed. The only considered page dimention is the height, *LPP (lines per page): Page height 66 lines. Here starts the example: 001 *lpp 66 002 *head 003 004 005 *end 006 *foot 007 008 009 *end 010 *left 10 011 ... text text text 012 ... test text text ... At line 001 is defined the page height in lines. At line 002 is defined the header; it contains two empty lines (003 and 004) whitch will be printed at the top of every page. At line 006 starts the footer definition that contains two empty lines (007 and 008) that will be printed at the end of every page. At line 010 is defined the space on the left that will be added to every line printed. From line 011 starts the normal text. ##HEADER AND FOOTER## ---------------------------------------------------------------- The commands *HEAD and *FOOT are used to define the top and bottom border if they contains empty lines, it these lines are not empty, they became real head and foot. The dimentions are as it follows: Top 6 lines (should be one inch); Bottom 6 lines; Left 10 characters (should be an inch). Page height 66 lines (should be 11 inch). At position 0.5 inch (after 3 lines) a one line header appears. 001 *lpp 66 002 *head 003 004 005 006 ------------------- MYFILE.TXT ------------------- 007 008 009 *end 010 *foot 011 012 013 014 015 016 017 *end 018 *left 10 019 ... text text text 020 ... test text text ... At line 006 (the fourth header line) a text appears. It will be printed on every page at the absolute fourth page line. ##CODE INSERTION## ---------------------------------------------------------------- Peaces of code can be inserted inside *COMMAND - *END. It can be usefull to make complicated reports. The following example declares a public variable used to number pages. 001 *command 002 mempublic("PageNo") 003 PageNo := 0 004 *end 005 *lpp 66 006 *head 007 *command 008 PageNo := PageNo +1 009 *end 010 011 012 *end 013 *foot 014 015 Page <PageNo> 016 017 *end 018 *left 10 019 ... text text text 020 ... test text text ... At line 001 starts a *COMMAND definition: lines 002 and 003 will be interpreted from the funtion EX(), the nB interpreter. These lines define a public variable and initialize it at 0. This variable will be use to count pages. At line 007, inside the header (nested), start another *COMMAND definition that contains an increment for the "PageNo" variable. As the header is read and "executed" for every new page, and that before the footer, the variable "PageNo" will contain the right page number. At line 015, inside the footer, a reference to "PageNo" appears. Here will be printed the page number. A more complicated example can be found in ADDRESS.TXT the RPT text file used for the ADDRESS.& macro examples. ##HOW CAN I## ================================================================ nB is a little bit complicated as it may do many things. Here are some examples. ##CREATE A UDF FUNCTION## ---------------------------------------------------------------- UDF means User Defined Function. Inside nB there isn't the possibility to create functions, but there is an alternative: code blocks. <code block> <code blocks> <eval()> <aeval()> ##CREATE A BIG CODE BLOCK## ---------------------------------------------------------------- A code block cannot be longer than 254 characters, as any other instruction inside nB. So, there is no way to make a bigger code block, but a code block can call another code block, and so on. For example: mempublic( { "first", "second", "third" } ) first := {|| eval( second, "hello" ) } second := {|x| eval( third, x ) } third := {|x| alertbox( x ) } eval( first ) This stupid example simply will show the alert box containing the word "hello". <code block> <code blocks> <eval()> ##CREATE A VIRUS## ---------------------------------------------------------------- I HOPE that NO ONE will loose time creating a virus that can attach a nB macro program. In fact there is no protection against this problem. A compiled macro is simply a .DBF file with a different extention (I used .NB). So you can just read a compiled macro program as a database file. ##PROTECT MYSELF FROM VIRUSES## ---------------------------------------------------------------- There is no tecnical protection against macro program virues. I just think that nB will not be so famous to inspire a virus writer for nB's macro program files. ##THE SOURCE FILES## ================================================================ The nB source is composed of four files: NB.PRG The main source file containing essentially the nB menu. REQUEST.PRG Contains a link to all CA-Clipper standard functions. STANDARD.PRG Contains the most important standard functions. EXTRA.PRG Contains some extra function not absolutely necessary duriing macro execution. The file REQUEST.PRG source file generates some warnings because not all functions listed there are directly called form nB. Don't warry about that warning message. Different .RMK (rmake) files are included to compile nB differently, including/exluding some program parts, for example to obtain a runtime executor. ##AKNOLEDGMENTS## ================================================================ nB is written in CA-Clipper 5.2. CA-Clipper is produced by Computer Associates and Computer Associates has no resposibility on nB. Some peaces of the CA-Clipper standard functions description are taken from the CA-Clipper documentation. The function RF() is a modification of the source of the original __ReportForm() used by CA-Clipper. I would like to thank all who have tryed and will try nB. Every e-mail about that is very important to me. ##KNOWN PROBLEMS## ================================================================ There are some known unresolved problems inside nB. I am sorry. * nB Macros may be contained inside ascii files or a "compiled" .dbf file. In the second case, when nB executes the macro, a work area (the last available one) is used, so it should not be closed or the macro execution will be stopped. A dbcloseall() will stop execution of the macro. In substitution of dbcloseall(), DBCLOSE() should be used. * To simplify the macro interpretation, lines such as this: qqout( "You can't do that // you can't do that!" ) will generate an error as the interpreter will read only: qqout( "You can't do that * nB works good also if you have a screen configuration that permits you to show more than the usual 80 columns and 25 lines, but the library used to handle the mouse is not able to work outside the 80x25 area. But if nB runs under Windows inside a window, it works. ##nB HISTORY## ================================================================ z.exe 1995.03.18 to 1996.02.01 The result of an hobby project to create a .DBF, .NTX, .LBL and .FRM utility with a simplified macro ability. This program was distributed only in Italy. nBase 1996.01.15 The first version of a new hobby project to create a macro interpreter nB 1996.02.28 This is the first release of nB. nB is the result of nBase and z.exe. nB 1996.06.16 nB becomes "GNU-GPL" and the source is included. nB 1997.01 Mouse support: many standard functions are rewritten. TB() is modified: now more parameter are available. Bidimensional arrays may be directly edited with ATB(), a Tbrowse function for arrays. More functions are availables. Other minor changes. Other minor bug corrections. ##HOW TO CONTACT THE AUTHOR## ================================================================ If you like the program, I will be happy to know it, for example receiving a e-mail where you say something like: "I use nB". Will you tell me if you like this work? Comments, suggestions, bug reports and english text corrections are welcome (and needed) to make a better nB. Write to: Daniele Giacomini Via Turati, 15 I-31100 Treviso Italy Send your e-mail to: daniele@tv.shineline.it The latest about nB may be found at: http://www.geocities.com/SiliconValley/7737/nanobase.html