PC-Online 1998 February

home *** CD-ROM | disk | FTP | other *** search

/ PC-Online 1998 February / PCOnline_02_1998.iso / filesbbs / dos / dbonlin2.exe / DBONLINE.DOC < prev next >

Wrap

Text File | 1995-09-29 | 205.8 KB | 6,303 lines

dB Online Administrator's Manual Merlin Systems Inc. Ottawa, Ontario, Canada Copyright (c) 1993-1995 Merlin Systems Inc. All rights reserved. This software product and this manual are copyrighted and all rights are reserved by Merlin Systems Inc. No part of the contents of this manual may be reproduced or transmitted in any form or by any means without the written permission of the publisher. Merlin Systems Inc. does not assume any liability arising out of the application or use of any products described herein. Merlin Systems Inc. further reserves the right to make changes in any products described herein without notice. This document is subject to change without notice. dBASE III+ and dBASE IV are registered trademarks of Borland International Inc. Clipper is a registered trademark of Computer Associates Inc. FoxPro and MS-DOS are registered trademarks of Microsoft Corporation. DigiBoard is a registered trademark of DigiBoard Corp. All other trademarks and registered trademarks are the properties of their respective owners. Revision Date: 8/11/94 rev. 5 C O N T E N T S INTRODUCTION 1 COMMUNICATIONS MODES 1 SHAREWARE LIMITATIONS 1 PROFESSIONAL VERSION 1 INSTALLATION 1 DISKETTE INSTALLATION 1 ZIP FILE INSTALLATION 2 INSTALLED FILES 2 DATABASE CONCEPTS 3 WHAT IS A DATABASE? 3 FIELDS 3 RECORDS 4 TAGS 4 INDEXES 5 COMPILING 6 SOURCE CODE FORMAT (.PRG) 6 COMPILE SYNTAX 6 EXAMPLES 7 EXECUTION 9 FILE FORMAT COMPATIBILITY 9 OPERATION MODES 9 BBS DOORWAY MODE 9 LOCAL/LAN MODE 9 STAND ALONE MODE 10 COMMAND LINE PARAMETERS 10 STAND ALONE BATCH FILE 12 COMMUNICATIONS 13 PORT COMMAND SYNTAX 13 COM 13 INT14 13 FOSSIL 13 SDIGI 14 SARNET 14 LANGUAGE REFERENCE 15 SYMBOLS AND CONVENTIONS 15 EXPRESSIONS 15 VARIABLES/FIELDS 16 ALIASES 16 MATHEMATICAL OPERATORS 16 BBS INFORMATION FUNCTIONS 16 RELATIONAL OPERATORS 17 LOGICAL OPERATORS 17 OPERATOR PRECEDENCE 17 LANGUAGE MODIFICATIONS 18 LANGUAGE REFERENCE 20 APPENDICES 122 APPENDIX 1: ERRORLEVELS 122 PROGRAM EXECUTION ERRORS 122 START UP ERRORS 124 APPENDIX 2: COMPILER MESSAGES 126 ERROR MESSAGES 126 WARNING MESSAGES 126 APPENDIX 3: RUNTIME ERRORS 128 APPENDIX 4: FULL SCREEN ENTRY KEYS 130 Introduction dB Online is the first database application specifically designed for online environments. It provides a complete programming language that enables you to access, display, edit, and append to database files. dB Online accesses industry standard .DBF files with a superset of the dBASE III+ programming language. This allows you to use existing database applications, or easily create new ones. There is no need to learn new scripting languages. Communications Modes dB Online operates in three communication modes: o In BBS Doorway Mode, dB Online operates with most popular BBS's as a seamless door. BBS and user information is passed to dB Online and is available to the developer through xBase type function calls. o In Local/LAN Mode, dB Online provides a method for your local users to access the dB Online application. This mode is also useful for testing and debugging your application. o In Stand Alone Mode, dB Online operates without a BBS. It will wait for callers and make a connection before executing the application. This provides an alternative method to supply database access in an online environment. dB Online is multi-user compatible and provides full file and record locking capabilities. dB Online employs locking methods compatible to your native database management system. dB Online can be run concurrently with your existing applications and access the same data files simultaneously. While dB Online's strength is it's ability to access database files, it also provides a complete language to create any type of door for your BBS. Shareware Limitations While the shareware version of dB Online allows you to experience the power of dB Online for free, it does have some limitations. It was made available to allow you to try the software before you purchase it and should not be used on regular terms. Whenever dB Online runs a program that was compiled with the shareware version of compile.exe, it produces an æUnregistered Delay ScreenÆ before and after running the program. Professional Version The Professional version allows for non-BBS operation with the Stand Alone feature. This feature will allow dB Online to answer incoming calls. Installation Diskette Installation The dB Online diskette includes an installation program. The steps to follow are: o Insert the diskette into the drive you want to install from o Run the install program on the diskette by typing: a:install o The install program will ask you for the directory to install dB Online. It will also ask you the file format compatibility you wish to install. You have a choice of one or more of the following: dBASE III+, dBASE IV, Clipper or FoxPro. o Install will copy all necessary files into the specified directory. o Please review the readme.txt file for any product revisions. o Once installation is complete proceed to the COMPILING and EXECUTION sections to create your first online database application. Zip File Installation If you received dB Online from a download you should install as follows: o Create a directory for dB Online: md c:\dbonline o Unzip the dbol???.zip file into this directory: (??? refers to the version number of dB Online) pkunzip dbol???.zip c:\dbonline o Copy the dbonline.key file into the dB Online directory o Please review the readme.txt file for any product revisions. o Once installation is complete proceed to the COMPILING and EXECUTION sections to create your first online database application. Installed Files The following files should be in your dB Online directory after installation: COMPILE.EXE Source .PRG compiler DBOLFOX.EXE dB Online executable for FoxPro compatibility DBOL4.EXE dB Online executable for dBASE IV compatibility DBOL3.EXE dB Online executable for dBASE III+ compatibility DBOLCLIP.EXE dB Online executable for Clipper compatibility. DBONLINE.DOC ASCII version of this document README.TXT Product revisions and documentation updates. REGISTER.DOC Product registration information. DBONLINE.KEY Key file to access Registered functions Database Concepts What is a database? A database is a organized collection of related information or data. A common example of a database is a telephone book. It contains name, phone numbers, and addresses of thousands of people. Each entry in the phone book corresponds to a record, and each piece of information in the record, such as the name or phone number, corresponds to a field. A group of records such as a telephone book becomes a database. dB Online accesses the industry standard .DBF database files. This standard, known as the xBase standard, is presently the most widely used database standard. Fields A field is the most basic piece of data in a database file. There are four attributes that describe each field. These are described below: Field Description Attribute Name This refers to the name that will be used to identify the field. A field name can have a maximum of 10 characters. It must begin with an alphabetical character and may consist of any combination of alphanumeric or underscore characters. Type The type of the field determines what kind of information is stored. There are 5 types of fields in the xBase standard: Character, Date, Logical, Numeric, and Memo. The first four are fixed length fields and the Memo field is variable length. Length This refers to the number of characters or digits that can be stored in the field. Decimals This only applies to Numeric fields. It specified the number of digits to follow the decimal place. Memo fields are stored in a separate file and entries are referenced from a fixed field in the database file. A memo entry can be 64000 characters in length. Records A record consists of one instance of every field. Each record has a unique record number. The record number indicates the physical position of the data in the data file. Each record also has a deletion flag. This deletion flag determines weather a record is to be removed when the file is packed. Tags A tag determines the order that the records in the database file are presented. The tag does not affect the physical ordering of the database but only the order in which they are accessed. Tags are created by specifying an expression that the records are ordered from. The results of this expression is stored in the index key. Indexes An index is a file containing the sorted index keys for one or more tags. dB Online supports several formats of index files. They are specified below by the index file extensions: File Extension Format .CDX FoxPro .MDX dBASE IV .NDX dBASE III+ .NTX Clipper The .CDX and .MDX formats allow you to have multiple tags in each index file, and production index files. Production index files open automatically when the associated database is opened. The .NDX and .NTX index formats allow only one tag per index file. Compiling Source Code Format (.PRG) The source code for a dB Online program consists of one or more .PRG files. These are the standard source files for all xBase applications. The dB Online source program is defined by a main .PRG file and optional procedure files. The main file is the file that will be executed first once the source is compiled. Procedure files are specified using the SET PROCEDURE TO command. These files must include only procedure definitions. The main file and all its procedure files are compiled into a single source .DBX file. The following code provides an example of the Source Code Format: FILE: main.prg SET PROCEDURE TO function.prg * Beginning of main.prg ... RETURN && ends main program PROCEDURE proc1 && procedure definition with main program ... RETURN FILE: function.prg PROCEDURE proc2 && Procedure files only contain procedures ... PROCEDURE proc3 && RETURN assumed before PROCEDURE ... RETURN Compile Syntax The command line syntax of the dB Online compiler is: COMPILE <source.prg> <source.prg> identifies the main file to be compiled. The dB Online compiler will compile the source code of the main file. Any procedure files identified in the main file with the SET PROCEDURE TO command will also be compiled. The dB Online compiler will do full syntax checking for all dB Online commands. Compile will output two types of messages during the compile. Error messages indicate errors in the source code program. Compile will indicate the source line number and show where the error occurred in the actual source code. Warning messages indicate code that is not applicable to an executable version of an xBase program. These include commands such as SET TALK, SET SCOREBOARD, etc. If there are zero error messages as a result of the compile, dB Online will then link all procedure calls in the code. Procedure definition are compared with procedure calls to ensure that the correct number of parameters are being passed and that all procedure calls have corresponding procedure definitions. If there are no linking errors then a compiled source .DBX file is created. This is the file to be used with the dbonline.exe executable. All compilation error and warning messages are listed in APPENDIX 2. Examples Consider the following program: sample.prg ** File: sample.prg ? "Hello" Return The output from the compiler would be: dB Online 2.0 Copyright (c) 1993 Merlin Systems Inc. ------------------------------------------------------------ COMPILING: sample.prg TOTAL ERRORS: 0 TOTAL WARNINGS: 0 LINKING PROCEDURE CALLS SUCCESS WRITING FILE: sample.dbx For the following program: sample2.prg ** File: sample2.prg USE customer.dbf ALIAX clients LIST RETURN The output from the compiler would be: dB Online 2.0 Copyright (c) 1993 Merlin Systems Inc. ------------------------------------------------------------ COMPILING: sample2.prg *** ERROR: Syntax Error. Line: 2 USE customer.dbf ALIAX clients ^ TOTAL ERRORS: 1 TOTAL WARNINGS: 0 Execution dB Online operates with a number of database file formats, and three operating modes. These options are explained in this section. File Format Compatibility dB Online presently supports 4 common file formats. There is a separate dbonline.exe file for each format. This information is outlined in the following table: File Format Index Format Memo Format dB Online Executable dBASE III+ .NDX .DBT DBOL3.EXE CLIPPER .NTX .DBT DBOLCLIP.EXE dBASE IV .MDX .DBT DBOL4.EXE FoxPro .CDX .FPT DBOLFOX.EXE When referring to the dB Online executable, this manual will use dbonline.exe. However one of the above executables must be replaced for dbonline.exe on the command line. Operation Modes There are three modes of operation for dB Online: BBS Doorway Mode, Local / LAN Mode and Stand Alone Mode. The dB Online calling conventions for each mode area outlined below. BBS Doorway Mode To operate in BBS Doorway Mode you will need to use your BBS software to setup dB Online as a door. The BBS software will require you to create a batch file for the doorway. Please refer to your BBS documentation for assistance. You will need to include in dB OnlineÆs command line one or more filenames of BBS drop files. Local/LAN Mode dB Online can be executed in Local or LAN Mode. This allows for local testing and debugging of the application, as well as servicing all LAN nodes on your BBS. All that is need on the command line, is the filename of a DBX file. Local/Lan Mode operation will not output to any communications port. It only displays on the local screen. Stand Alone Mode dB Online provides a method to operate over a COMM port without the need of a BBS. Stand Alone mode will wait to receive a call on the modem and then connect with the user before executing the .DBX file. Command Line Parameters dB Online's command line syntax is as follows: dbonline <source.dbx> [<bbs drop files>] [PORT:xxxx:n,y] [-ESTACK:xx] [-STACK:xx] [-AREA:xx] [-QUIET] [-SA] <source.dbx> This is the path and filename of the compiled .PRG files. dB Online assumes a .DBX file extension if none is given. <bbs drop files> This can consist of any combination of the following. o DOOR.SYS (*) o PCBOARD.SYS (*) o DORINFOx.DEF (*) o CALLINFO.BBS (*) o CHAIN.TXT (*) o USERS.SYS o EXITINFO.BBS The BBS drop files are created by the BBS whenever a door is executed. Consult your BBS documentation for the BBS drop files created. At least one of the files with asterisks is required, as they provide COMM port information for dB Online. USERS.SYS and EXITINFO.BBS only provide user information. If the information in the <bbs drop files> provide a zero for the COMM port or BAUD settings then operation will default to Local/Lan Mode operation. This allows local nodes to log into your BBS and access the dB Online door application. PORT:xxxx:n,y This command is for custom port configuration only. This is not usually required for standard BBS Doorway Mode operation. For more information, see the Communications section. -ESTACK:xx This parameter is used to specify the amount of memory to allocate for the Evaluation Stack. By default this is 20. Maximum is 32768 or limited by available memory. -STACK:xx This parameter is used to specify the amount of memory to allocate for the Runtime Stack. By default this is 50. Maximum is 32768 or limited by available memory. -AREA:xx The maximum number of work areas to allocate memory for. By default this value is 20. -SA The -SA option identifies Stand Alone Mode operation. The PORT: command is not optional in Stand Alone operation. It must be specified in order that dB Online call detect incoming calls. Please see the Communications section for more details. Upon execution dB Online Stand Alone will enter the call waiting screen. This screen is shown below: ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ █ █ █ ▀▀▀ ▀▀▀▀▀▀▀▀▀ █ █ ▀▀ ▀▀ ▀▀ █ █ ▀▀ ▀▀ ▀▀ █ █ ▀▀ ▀▀ ▀▀ █ █ ▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀ █ █ ▀▀ ▀▀ ▀▀ ▀▀ █ █ ▀▀ ▀▀ ▀▀ ▀▀ █ █ ▀▀ ▀▀ ▀▀ ▀▀ █ █ ▀▀ ▀▀ ▀▀ ▀▀ █ █ ▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀▀▀▀ █ █ Online █ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄█ █▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ █ dB Online v2.0 Copyright (c) 1994 Merlin Systems Inc. █ █ Last call on 00/00/00 00:00 (0 total calls) █ █ Port 1 on UART driver opened at 9600 baud. █ █ Initializing Modem. █ █ Waiting for a call... (Press F1 for Help) █ █ █ █▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄█ This entry screen provides information on the PORT settings as well as previous caller information. There is a window that indicates the Connection Status of the PORT. There are three events that will exit from the call waiting screen. o A call is received. dB Online will make a connection and then execute the specified .DB2 program. o The local user presses <F2>. dB Online will then execute the specified .DBX program in local mode. o The local user presses <Esc>. dB Online will exit and return a DOS errorlevel of 114 (defined in Appendix 1). Once dB Online terminates for any reason, it will return control to DOS. You must create a batch file that will re-enter dB Online to wait for another caller. Stand Alone Batch File This example batch file will start dB Online Stand Alone with a source file sample.dbx using COMM port 1 at 9600 baud. If the user presses <Esc> at the call waiting screen then the batch file will terminate. :start dbonline sample.dbx -SA PORT:COM:1,9600 REM if local user presses escape do not re-enter if errorlevel 115 goto start if errorlevel 114 goto end goto start :end Communications dB Online includes the ability to communicate with a wide variety of communications hardware. Support is provided for standard COM ports, FOSSIL drivers, Interrupt 14 (BIOS), DigiBoard, and Arnet smart I/O cards. 16550 FIFO support is automatically handled. The PORT command line parameter is used to specify custom port configurations for use with dB Online. A PORT command is required for Stand Alone operation and may be required for BBS Doorway Mode operation. PORT Command Syntax The PORT command line parameter has the following syntax: PORT:<driver>:<port>,<baud> The <driver> settings are outlined below: COM The COM <driver> setting is for standard COM ports. For ISA machines the <port> value is between 1 and 4. For Multichannel machines the <port> value can be from 1 to 8. The <baud> value can range up to 115200. INT14 This INT14 <driver> setting is for Interrupt 14 (BIOS) ports. With this driver, dB Online will access the serial port through Interrupt 14. INT14 should be used if you have a TSR or driver that uses Int 14 to route serial calls to something other than the COM ports. INT14 should also be used if you have a non-intelligent I/O board and are using its driver software. The <port> value is the same as the standard COM port values. The <baud> value can range up to 19200. FOSSIL The FOSSIL <driver> setting is for FOSSIL drivers. Use this driver if you have a FOSSIL driver installed. Two such drivers are X00 and BNU. The <port> and <baud> values are dependent on the FOSSIL driver. SDIGI The SDIGI <driver> setting is for an Intelligent DigiBoard I/O board. A recent version of the DigiBoard driver will be required. The most recent driver as of printing of this manual was XDIDOS5.SYS version 4.0.5. It is available from the DigiBoard BBS at 612-943-0812. The <port> value will be the DigiBoard channel to be use. The <baud> value can range up to 115,200. For proper DigiBoard operation ensure the driver is configured for EBIOS support, and that the IRQ line, the character ready flag, and the handshaking are all disabled. SARNET The SARNET <driver> setting is for an Intelligent Arnet I/O board. The <port> value is the channel or handle as stated by the Arnet device driver upon loading. The <baud> value can range up to 115200. Language Reference Symbols and Conventions The following symbols are used throughout the Language Reference section to describe the syntax of the dB Online commands and functions. Symbol Definition <item> Angle brackets indicate that you must enter the enclosed item. Do not enter the angled brackets. [item] Square brackets indicate that the enclosed item is optional. Do not enter the Square brackets. <item1> | The vertical line separates choices of items. Choose <item2> one of the options given. <expr> A valid dB Online expression must be entered. See the Expressions section below. <expN> A numeric expression must be entered here. <expC> A character expression must be entered here. <expD> A date expression must be entered here. <expL> A logical expression must be entered here. <var> A memory variable identifier must be entered here. <memovar> A field that represents a Memo. <array> A memory variable that is an array. <field> A database field identifier must be entered here. <alais> A character alias identifier must be entered here. <proc name> A procedure name must be entered here. <filename> A valid DOS filename must be entered here. This can include the drive and full path if necessary. <text> Any text may be entered here. <scope> Allows the specification of records. Valid values are: ALL, RECORD <expN>, NEXT <expN>, REST. <commands> Any dB Online command may be entered here. <item list> The word list following an item indicates that a number of items may be entered. These items must be separated by a comma (,). <item> An item in italics indicate that it may be macro substituted. See the Macro (&) function for more details. The naming conventions for <var>, <field>, <proc name>, and <alias> area all the same. They may be up to 10 characters in length, can consist of alphanumeric and underscore characters, and must begin with an alphabetic character. Expressions dB Online provides a complete expression evaluator. The components of these expression are outlined below: Variables/Fields Variables can contain 5 types of data: character, numeric, date, logical, and array. Fields have the same data types, except for array, andso include the memo field type. Aliases There are twenty work areas available in dB Online. Aliases identify the work area of a specific database. The alias of a work area is usually the database file name minus the extension. This can be changed using the USE...ALIAS command. The alias for the first 10 areas can also be referred to as A through J. To specify a field from another work area the aliasing indicator (-> or .) must be used. For example to specify the NAME field in the second work area you would type: B->NAME or B.NAME To avoid confusion between a memory variable and a field of the same name you may explicitly specify the variable by writing M->VARIABLE. Mathematical Operators dB Online supports the standard symbols for mathematical calculations: Operator Description + Addition - Subtraction * Multiplication / Division ^ Exponent ** Exponent These operators may all be used with numeric operands. The +,- operators may be used with character operands. The + operator will concatenate two character strings. The - operator will also concatenate two strings but will move any trailing blanks from the first string to the end of the concatenated string. The +,- operators may be used for date arithmetic. Both can be used to add or subtract a specific number of days from a date value. For example {10/21/93} + 7 will return 10/28/93. Two dates may be subtracted from each other to determine the number of days in between them. BBS Information Functions The BBS Information Functions provide a way to include information from the BBS drop files into a dB Online application. Included with the description of each function is a Valid With clause. This determines which BBS drop files provide the information for the given function. If this BBS drop file is not included in the command line of dB Online a null value will be returned by the BBS Information Function. Relational Operators dB Online supports the following relational operators: Operator Description < Less than > Greater than = Equal to <> Not equal to # Not equal to <= Less than or equal to >= Greater than or equal to $ Is contained in The results of all relational operators is a logical value. The $ operator is valid with character operands. If A and B area character strings, A$B returns True (.T.) if A is either identical to B or contained within B. Logical Operators dB Online supports the following logical operators: Operator Description .AND. Logical AND .OR. Logical OR .NOT. Logical NOT (unary operator) All Operators may appear without periods. Operator Precedence dB Online evaluates expressions with the following standard operator precedence: Operators Description ( ) Parenthesis grouping + - Unary positive and negative ** ^ Exponent * / Multiplication, Division + - Addition, Subtraction < > <= >= = != # $ Relational Operators .NOT. Logical Not .AND. Logical And .OR. Logical Or All operations at the same precedence level are performed in order from left to right. Language Modifications The following language modifications are new to dB Online version 2.0. @ ... EDIT ... New command @ ... GET ... MESSAGE ... Added the MESSAGE keyword @ ... GET NOMODIFY Added the NOMODIFY keyword @ ... PROMPT New command @ ... SAY | GET COLOR ... Added the COLOR keyword ACOPY () New array function ADEL () New array function ADIR () New array function AELEMENT () New array function AFIELDS () New array function AINS () New array function ALEN () New array function ASCAN () New array function ASORT () New array function ASUBSCRIPT () New array function CBLOCK () New communications I/O function CBREAK () New communications I/O function CCD () New communications I/O function CCLOSE () New communications I/O function CCTS () New communications I/O function CDSR () New communications I/O function CDTRSET () New communications I/O function CERROR () New communications I/O function CGETS () New communications I/O function CHANDSHAKING () New communications I/O function COPEN () New communications I/O function CPEEKCHAR () New communications I/O function CPORT () New communications I/O function CPUTS () New communications I/O function CRC16 () New communications I/O function CRC32 () New communications I/O function CREAD () New communications I/O function CRING () New communications I/O function CRTSSET () New communications I/O function CRXCLEAR () New communications I/O function CSETPORT () New communications I/O function CSTATUS () New communications I/O function CTXCLEAR () New communications I/O function CWRITE () New communications I/O function DECLARE / DIMENSION ... New array commands FCHSIZE () New file I/O function FCLOSE () New file I/O function FCREATE () New file I/O function FDATE () New file I/O function FEOF () New file I/O function FERROR () New file I/O function FFLUSH () New file I/O function FGETS () New file I/O function FLEN () New file I/O function FLLOCK () New file I/O function FLUNLOCK () New File I/O function FOPEN () New file I/O function FPUTS () New file I/O function FREAD () New file I/O function FSEEK () New file I/O function FSETTIME () New file I/O function FTELL () New file I/O function FTIME () New file I/O function FUNCTION ... New command FWRITE () New File I/O function ISDIGIT () New function ISREMPTY () New communications I/O function ISRFULL () New communications I/O function ISTEMPTY () New communications I/O function ISTFULL () New communications I/O function LINENO () New function MEMORY () New function MENU TO ... New command MODIFY FILE | COMMAND ... New command MODIFY MEMO ... New command PROGRAM () New function RCVASCII () New communications I/O function RCVKERMIT () New communications I/O function RCVXMODEM () New communications I/O function RCVYMODEM () New communications I/O function RCVZMODEM () New communications I/O function REGISTEREDTO () New function RETURN ... RETURN can now return a value SELECT () New function SERIALNO () New function SET COMPATIBLE ... New command SET CURRENCY LEFT | RIGHT New command SET CURRENCY TO ... New command SET DATE TO ... New command SET MARK TO ... New command SET POINT TO ... New command SET SEPARATOR TO ... New command SET SPACE ON | OFF New command SNDASCII () New communications I/O function SNDKERMIT () New communications I/O function SNDXMODEM () New communications I/O function SNDYMODEM () New communications I/O function SNDZMODEM () New communications I/O function Language Reference & Function & is the macro substitution function. It substitutes the contents of a character memory variable for another variable name or a file name. Syntax &<var> Returns <var> | <field> | <filename> Remarks The contents of <var> will specify either another variable/field identifier or a file name to be used in a file command. The macro (&) function has been enhanced. Anywhere a variable/field identifier can be used, it can be substituted with a macro function as follows: &<var>, text&<var>. This allows the simulation of arrays with the second syntax. This will apply for both evaluation and assignment of variables and fields. Example To macro substitute a variable name: x = "hello" hello = 10 ? x hello ? &x 10 To macro substitute a file name: x = "customer.dbf" use &x &&Opens customer.dbf = Function Evaluates an expression Syntax = <expr> Remarks The Equals command can be used to evaluate an expression without assigning the value to a variable. This is useful for functions that have side effects such as LOCK(), PAGELEN(). Example =PAGELEN(23) ?|?? Function ?|?? evaluates and displays the value of one or more expressions. Syntax ?|?? <expr list> Remarks The single question mark issues a carriage return and line feed before the expression list is displayed. The double question mark displays at the current cursor position. The commas separating the expression list output a single space in between expressions. If an expression consists of a single MEMO field identifier, then dB Online will output the memo contents word wrapped to the width set by SET MEMOWIDTH TO. Example name = "John" ? "Hello there",name Hello there John ? "The date is "+ ctod(date()) The date is 10/21/93 ? 5+3*6 23 See Also @...SAY, TEXT...ENDTEXT, LIST, DISPLAY @...CLEAR Function @...CLEAR is used to clear a rectangular area on the screen. Syntax @ <expN1> , <expN2> CLEAR [TO <expN3> , <expN4>] [COLOR <color>] Remarks dB Online will clear to the current background color the space defined by the 4 expressions. The line and row given by <expN1> and <expN2> become the top left corner, and <expN3>, <expN4> become the bottom right corner. If the second coordinates are not given then dB Online will clear to the bottom right corner of the display. If the COLOR clause is included, then the color will be changed before execution of the command. See Also @...TO, CLEAR @...SAY...GET Function @...SAY..GET is used to create full screen input forms. It displays information at specific coordinates. Syntax @ <expN1> , <expN2> [SAY <expr> [PICTURE <expC>] [COLOR <color>]] [GET <var> | <field> [PICTURE <expC>] [RANGE <expr1> , <expr2>] [MESSAGE <expC>] [COLOR <color>] [NOMODIFY]] Remarks The output begins at the row and column positions specified by <expN1> and <expN2>. For a 23*80 terminal the row coordinate can range from 0 to 22 and the column coordinate from 0 to 79. The @...SAY command display information that you do not want to edit. The value can be any valid dB Online expression. The value of <expr> is evaluated and displayed at the row and column coordinates given. The @...GET command displays and allows editing of data from existing memory variables and fields. The READ command activates a full-screen editing mode which allows the editing of multiple GET fields. If an @...SAY...GET combination command is used, a single space is entered between the display of the SAY expression and the GET input field. The RANGE option is used with numeric and date variables to specify acceptable lower <expr1> and <expr2> lower bounds for input. If data is entered outside the values specified by RANGE, dB Online will not accept the input and request new data. The MESSAGE clause character expression <expC> is displaayed when a text edxit region is selected. The value of this character expression is displayed in the center of the last line. If the COLOR clause is included, then the color will be changed before execution of the command. By including the NOMODIFY clause, the field becomes read only, not allowing the user to alter its contents. The PICTURE option allows formatting of the output expression and restricts the type of data that may be entered into a variable. The <expC> is called a PICTURE clause and may consist of a function and/or a template. If a PICTURE function is used, the @ symbol must be the first character in the clause. If a PICTURE function is used with a picture template, a space must separate the two. dB Online provides the following PICTURE functions: Symbol Valid withDescription type C NUMERIC Display CR after a positive number. (SAY only) X NUMERIC Display DB after a negative number. (SAY only) ( NUMERIC Enclose negative number in parentheses. (SAY only) B NUMERIC Left justifies numeric data. (SAY only) Z NUMERIC Displays zero numeric value as a blank string. (SAY only) D DATE Use {MM/DD/YY} date format. E DATE Use {DD/MM/YY} date format. A CHARACTER Allow only alphabetic characters. (GET only) ! CHARACTER Converts all letters to uppercase. R CHARACTER Literal characters displayed in template, but not entered in the field. S<n> CHARACTER Limits field width to <n> characters. GETs will scroll horizontally to access whole field. <n> must be a literal positive integer. A PICTURE template is created by using a single symbol for each character to be displayed or input. Any character may be used, but characters other than the template symbols are considered literal characters. If the R picture function is used for character input with a template containing literal characters, the literals are inserted into the display and not stored as part of the GET variable. If R is not used, the literals are displayed instead of the corresponding string character and are stored in the GET variable. For numeric variables, literal characters are always inserted into the display and not stored as part of the number. dB Online provides the following template symbols: Symbol Description 9 Allows digits for character and date input. Allows digits and signs for numeric data. # Allows digits, blanks, and signs. A Allows only alphabetic characters. L Allows only logical characters: t, T, f, F, y, Y, n, N. Y Allows only logical characters: y, Y, n, N. N Allows alphanumeric characters. X Allows any character. ! Converts letters to uppercase and does not affect other characters $ Displays dollar signs in place of leading zeros for numeric data. * Displays asterisks in place of leading zeros for numeric data. . Specifies the decimal position for numeric data , Displays if there are digits to the left of the comma for numeric data. If a PICTURE template is used to GET a decimal number, the decimal point must be included in the template. Example The following code provides examples of the @...SAY PICTURE command: name = "John Smith" @ 1,0 SAY name John Smith @ 2,0 SAY name PICTURE '@!' JOHN SMITH num1 = 456789 num2 = 23.78 num3 = -9.25 @ 3,0 SAY num1 456789 @ 4,0 SAY num1 PICTURE '$$$,$$$,$$$' $$$$456,789 @ 5,0 SAY num2 PICTURE '***,***.***' *****23,780 @ 6,0 SAY num3 PICTURE "@X ***,***.**' ******9.25 DB See Also ?|??, APPEND BLANK, CLEAR, CLEAR GETS, COL(), READ, ROW(), SET BELL, SET CONFIRM, SET DELIMITERS, SET INTENSITY, TEXT...ENDTEXT @ ... EDIT Function This command creates a rectangular text editing region for editing a memo variable. Syntax @ <expN1>, <expN2> EDIT <memovar> [SIZE <expN3>, <expN4>] [MESSAGE <expC>] [NOMODIFY] [COLOR <color>] [TAB]] Remarks If you do not supply a SIZE clause, then this command behaves exactly like a @ ... GET command. The MESSAGE clause character expression <expC> is displaayed when a text edxit region is selected. The value of this character expression is displayed in the center of the last line. By including a NOMODIFY clause, the user is not allowed to edit the contents of the memo variable. If the COLOR clause is included, then the color will be changed before execution of the command. Inclusing the TAB clause causes the Tab key to be inserted into the text, instead of jumping to the next editing region. The user must then press CT to save their changes and move to the next editing region. See Also @...GET @... PROMPT Function Creates a menu bar Syntax @ <expN1>,<expN2> PROMPT <expC1> [MESSAGE <expC2>] [COLOR <color>] Remarks This statement will allow the building a menus. These menus are read with the MENU TO statement. If the COLOR clause is included, then the color will be changed before execution of the command. See Also MENU TO @...TO Function @...TO is used to draw a box with single or double lines. Syntax @ <expN1>,<expN2> TO <expN3>,<expN4> [DOUBLE] [COLOR <color>] Remarks The row and column of the top left corner of the box are specified by <expN1> and <expN2>. The bottom right corner are specified by <expN3> and <expN4>. If both row coordinates are the same, a horizontal line is drawn. If the column coordinates are the same, a vertical line is drawn. The DOUBLE option draws a double line box instead of the default single line box. If the COLOR clause is included, then the color will be changed before execution of the command. See Also @...CLEAR ABS() Function The ABS() function returns the absolute value of a numeric expression. Syntax ABS(<expN>) Returns NUMERIC Example ? ABS(3) 3 ? ABS(-3) 3 ACCEPT Function ACCEPT allows character input into a memory variable. Syntax ACCEPT [<expC>] TO <var> Remarks ACCEPT displays the optional prompt <expC> before waiting for user input. The character input is then placed into <var>. Example To input a users name: ACCEPT "Please input your name :" TO name ? name See Also @...SAY...GET, INPUT, WAIT ACOPY() Function Copies elements from one array to another array Syntax ACOPY ( <array1> , <array2> , <expN1> [ , <expN2> [ , <expN3> ] ] ] ) Returns NUMERIC Remarks <array1> is the source array, <array2> is the destination array, <expN1> is the first element in the source array to be copied, <expN2> is the number of elements to copy, <expN3> is the first element in the destination array. ACOPY will return the number of elements copied. See Also ADEL(), AELEMENT(), AINS(), ASCAN(), ASORT(), DIMENSION ADEL() Function Deletes an element, row or column from an array Syntax ADEL ( <array> , <expN1> [ , <expN2> ] ) Returns NUMERIC Remarks <array> is the array, <expN1> is the element, row or column to delete. If <expN2> is equal to 2, then <expN1> represents a column. ADEL() returns 1 is successful. The last element, row or column is set to a logical .F. See Also ACOPY(), AELEMENT(), AINS(), ASCAN(), ASORT(), DIMENSION ADIR() Function Retreives directory information into an array. Syntax ADIR ( <array> [ , <expC1> [ , <expC2> ] ] ) Returns NUMERIC Remarks <array> is the array, <expC1> is the file and path wildcard, <expC2> specifies additional files to include. ADIR() returns the number of files found. ADIR() will automatically overwrite and redimension <array>. <expC2> can be one or more of the following: D Subdirectories H Hidden Files S System Files V Volume Label The following table describes what each column in the array contains: Column File Information Data Type 1 Name CHARACTER 2 Size NUMERIC 3 Date DATE 4 Time CHARACTER 5 Attributes CHARACTER The File Attributes may contain any of the following: Letter Attribute A Archive H Hidden R Read Only S System D Directory V Volume Label Example DECALRE array(5,5) =ADIR(array,ôc:\dbonline\*.exeö) See Also ACOPY(), ADEL(), AELEMENT(), AINS(), ASCAN(), ASORT(), DIMENSION AELEMENT() Function Returns the number of an array element from the arrayÆs subscripts. Syntax AELEMENT ( <array> , <expN1> [ , <expN2> ] ) Returns NUMERIC Remarks <expN1> is the row subscript, <expN2> is the column subscript. Example DECLARE x(2,3) ? AELEMENT(x,1,3) 3 ? AELEMENT(x,2,3) 6 See Also ACOPY(), ADEL(), ADIR(), AFIELDS(), AINS(), ALEN(), ASCAN(), ASORT(), ASUBSCRIPT(), DIMENSION AFIELDS() Function Places the database structure into an array. Syntax AFIELDS( <array> ) Returns NUMERIC Remarks AFIELDS() returns the number of fields placed into the array. The array is overwritten and redimensioned to fir all of the data. The following table describes what each column in the array contains: Column Field Information Data Type 1 Name CHARACTER 2 Type CHARACTER 3 Length NUMERIC 4 Decimal Places NUMERIC The Field Type is one of the following: Field Type Description C CHARACTER D DATE L LOGICAL M MEMO N NUMERIC See Also ACOPY(), DEL(), ADIR(), AELEMENT(), AINS(), ALEN(), ASCAN(), ASORT(), ASUBSCRIPT(), DIMENSION AINS() Function Inserts an element, row or column from an array Syntax AINS ( <array> , <expN1> [ , <expN2> ] ) Returns NUMERIC Remarks <array> is the array, <expN1> is the element, row or column to insert. If <expN2> is equal to 2, then <expN1> represents a column. ADEL() returns 1 is successful. The inserted element, row or column is set to a logical .F. See Also ACOPY(), ADEL(), AELEMENT(), ASCAN(), ASORT(), DIMENSION ALEN() Function Returns the number of elements, rows or columns in an array. Syntax ALEN ( <array> [ , <expN> ] ) Returns NUMERIC Remarks What is returned depends on the value of <expN>; <expN> What is Returned 0 the number of elements 1 the number of rows 2 the number of columns Example DECLARE x(3,7) ? ALEN(x) 21 ? ALEN(x,1) 3 ? ALEN(x,2) 7 See Also ACOPY(), ADEL(), ADIR(), AFIELDS(), AINS(), ASCAN(), ASORT(), ASUBSCRIPT(), DIMENSION APPEND BLANK Function APPEND BLANK allows a new record to be added to the end of the active database file. Syntax APPEND BLANK Remarks The new record is blank and becomes the current record. Any open index files are updated with the new record information. This command cannot be used with read only files. ASC() Function The ASC() function returns the ASCII value of the first character in a character expression. Syntax ASC(<expC>) Returns NUMERIC Remarks Returns the ASCII value of the first character in <expC> in the range 0 to 255. If the length of <expC> is 0 then ASC() returns 0. Example ? ASC('A') 65 ? ASC("Hello") 72 See Also CHR() ASCAN() Function Searches an array for an expression. Syntax ASCAN ( <array> , <expr> [ , <expN1> [ , <expN2> ] ] ) Returns NUMERIC Remarks <array> is the array to search, <expr> is the expression to search for, <expN1> is the element to begin the search at, <expN2> is the number of elements to search. ASCAN() returns 0 if not match exists. Example =ASCAN(x,öJOE BROWNö) See Also ACOPY(), ADEL(), ADIR(), AFIELDS(), AINS(), ASORT(), ASUBSCRIPT(), DIMENSION ASORT() Function Sorts elements in an array. Syntax ASORT ( <array> [ , <expN1> [ , <expN2> [ , <expN3> ] ] ) Returns NUMERIC Remarks <array> is the array to sort, <expN1> is the element or row to begin the sort at, <expN2> is the column to begin the sort at, <expN3> if the sort order; 0 for ascending, 1 for descending. ASCAN() returns 1 if successful. See Also ACOPY(), ADEL(), ADIR(), AFIELDS(), AINS(), ASCAN(), ASUBSCRIPT(), DIMENSION ASUBSCRIPT() Function Return the row or column subscript on an element from the elementÆs number. Syntax ASUBSCRIPT ( <array> , <expN1> , <expN2> ) Returns NUMERIC Remarks <array> is an array, <expN1> is the element number, If <expN2> is 1, then ASUBSCRIPT() returns the row subscript, if <expN2> is 2, then ASUBSCRIPT() returns the column subscript. See Also ACOPY(), ADEL(), ADIR(), AFIELDS(), AINS(), ASCAN(), DIMENSION AT() Function The AT() function returns the starting position of a character string within a second string. Syntax AT(<expC1>,<expC2>) Returns NUMERIC Remarks Returns the character offset in <expC1> where <expC2> is contained. If <expC2> is not contained then 0 is returned. Example ? AT("Hi there John","there") 4 WAIT TO x responses = "123456" IF AT(responses,x) =0 ?"Invalid Choice" ENDIF See Also SUBSTR() AVERAGE Function AVERAGE calculates the arithmetic mean of numeric expressions in the active database file. Syntax AVERAGE [<scope>] <expr list> TO <var list> [WHILE <expL1>] [FOR <expL2>] Remarks All records in the current database are averaged unless specified by the <scope>, WHILE, or FOR clauses. The <expr list> items must correspond to the memory variables in <var list>. Example To AVERAGE the cost filed for all of John Smiths sales USE sales AVERAGE cost TO av_cost FOR salesman = "JS" ? av_cost See Also COUNT, SUM BAUD() Function The BAUD() function returns the baud the user connected at. Syntax BAUD() Returns NUMERIC Remarks If the user is connected locally, then BAUD() returns zero. Valid With pcboard.sys, exitinfo.bbs, door.sys, dorinfox.def, chain.txt, callinfo.bbs See Also COMMPORT(), DTE() BBSNAME() Function The BBSNAME() function returns the name of the calling BBS. Syntax BBSNAME() Returns CHARACTER Valid With chain.txt, dorinfox.def BOF() Function The BOF() function indicates the beginning of the current database file. Syntax BOF() Returns LOGICAL Remarks Returns a logical True (.T.) when an attempt is made to move the record pointer before the first logical record of the current database file. Example USE customer ? BOF() .F. SKIP -1 ? BOF() .T. See Also EOF() CANCEL Function CANCEL stops the execution of the current dB Online session. dB Online will close all files and return to the calling program (BBS etc.) Syntax CANCEL Remarks CANCEL will return a 0 to the DOS errorlevel. See Also QUIT, RETURN CBLOCK() Function Stops remote end from sending data. Syntax CBLOCK( <expN1> , <expN2> ) Returns LOGICAL Remarks <expN1> is a communications handle returned by COPEN(), <expN2> can be either 1 to set the port into hard blocking state, or 0 to clear that port. CBLOCK() will return .T. if successful. See Also COPEN(), CCLOSE() CBREAK() Function Send a break signal to a port. Syntax CBREAK( <expN1> [ , <expN2> ] ) Returns LOGICAL Remarks <expN1> is a communications handle returned by COPEN(), <expN2> is the number of milliseconds allowed to elapse before a timeout. CBREAK() will return .T. if successful. See Also COPEN(), CCLOSE() CCD() Function Returns the state of Carrier Detect (CD). Syntax CCD( <expN> ) Returns LOGICAL Remarks <expN> is a communications handle returned by COPEN() CCD() will return .T. if Carrier Detect is on. See Also COPEN(), CCLOSE() CCLOSE() Function Closes a specified communications port. Syntax CCLOSE( <expN> ) Returns LOGICAL Remarks <expN> is a communications handle returned by COPEN() CCLOSE() will return .T. if successful. See Also COPEN() CCTS() Function Returns the state of Clear To Send (CTS). Syntax CCTS( <expN> ) Returns LOGICAL Remarks <expN> is a communications handle returned by COPEN() CCTS() will return .T. if CTS is on. See Also COPEN(), CCLOSE() CDOW() Function The CDOW() function returns the character name of the day of the week from a date expression. Syntax CDOW(<expD>) Returns CHARACTER Example If the system date = 10/21/93 ? CDOW(DATE()) Thursday ? CDOW(DATE()+1) Friday See Also DAY(), DOW() CDSR() Function Returns the state of Data Set Ready (DSR). Syntax CDSR( <expN> ) Returns LOGICAL Remarks <expN> is a communications handle returned by COPEN() CCD() will return .T. if DSR is on. See Also COPEN(), CCLOSE() CDTRSET() Function Set DTR on or off for a communications port. Syntax CDTRSET( <expN1> , <expN2> ) Returns LOGICAL Remarks <expN1> is a communications handle returned by COPEN() <expN2> is 1 to set DTR, 0 to clear it. CDTRSET() will return .T. if successful. If the line is being used for flow control such as XON/XOFF or RTS/CTS, it may cause unpredidictable results. Dropping DTR is frequently used as a way yo hang up a modem. See Also COPEN(), CCLOSE() CDX() Function The CDX() function returns the filename for the active index files in a work area. Syntax CDX(<expN1> [ ,<expN2> | <alias>]) Returns CHARACTER Remarks Returns the filename of an open .cdx file in a work area. <expN1> is the .cdx file position in the index file list specified by the SET INDEX TO <file list>, or USE INDEX <file list> commands. The optional second parameter returns .cdx files for other work areas. Example USE customer INDEX name.cdx, phone.cdx ? CDX(1) c:name.cdx ? CDX(2) c:phone.cdx See Also NDX(), MDX() CERROR() Function Returns the last error on the specified communications port. Syntax CERROR( <expN1> [ , <expN2> ] ) Returns NUMERIC Remarks <expN1> is a communications handle returned by COPEN() If you include <expN2>, then the error status will be cleared. Error Description Number 0 No error. -1 General error, non-specific. -2 Specified port is invalid or not open. -3 Cannot open a port that is already open. -5 Out of memory. -6 Requested port has not being initialized or opened. -7 One or more parameters are invalid. -8 Receive buffer empty. -9 Transfer buffer full. -10 Timeout. -11 CTS was expected but not asserted. -12 CD was expected but not asserted. -13 DSR was expected but not asserted. -14 No 8250 family UART at the requested location. -16 Local pressing of <Esc> during a file transfer. -20 Attempt to open multiple ports on shared interrupt board using different interrupt lines conflict. -25 Baud rate is not legal. -27 Word length not legal. -28 Number of stop bits not legal. -30 Driver software not detected. (DigiBOARD or Arnet) -31 Buffer overflow. -34 Attempt to initialize on multi-port board using wrong number. -35 Multi-port board is in use. See Also COPEN(), CCLOSE() CGETS() Function Returns a character string from a communications port. Syntax CGETS( <expN1> [ , <expN2> ] ) Returns CHARACTER Remarks <expN1> is a communications handle returned by COPEN() <expN2> is the maximun number of characters to read. Use this function to read in a line of characters from a port. See Also COPEN(), CCLOSE() CHANDSHAKING() Function Enable or disable handshaking on a port. Syntax CHANDSHAKING( <expN1> , <expN2> , <expN3> ) Returns LOGICAL Remarks <expN1> is a communications handle returned by COPEN() <expN2> is the type of handshaking to enable or disable. <expN2> Type of handshaking 0 DTR/DSR 1 RTS/CTS 2 XON/XOFF If <expN3> is 1, then handshaking will be enabled, else it will be disabled. This function will return .T. is successful. See Also COPEN(), CCLOSE() CHR() Function The CHR() function returns the character corresponding to an ASCII code value. Syntax CHR(<expN>) Returns CHARACTER Remarks Returns a single character corresponding to the ASCII value of <expN>. If <expN> is 0 then CHR() returns an empty string. Example ? CHR(65) A ? CHR(72)+CHR(105) Hi See Also ASC(), INKEY() CITY() Function The CITY() function returns the user's city and state or province. Syntax CITY() Returns CHARACTER Valid With exitinfo.bbs, door.sys, dorinfo1.def, users.sys, callinfo.bbs CLEAR Function CLEAR erases both the local and remote screens. It also clears all pending GET's. Syntax CLEAR Remarks The cursor is positioned at the top left hand corner of the screen after execution. See Also @...CLEAR, CLEAR GETS CLEAR ALL Function CLEAR ALL closes all open database files, index file, and memo files, and selects work area 1. Syntax CLEAR ALL Remarks Memory variables are not cleared as in dBASE III+ See Also CLOSE CLEAR GETS Function CLEAR GETS releases all pending @...GET commands issued. Syntax CLEAR GETS See Also @...SAY...GET, CLEAR CLEAR TYPEAHEAD Function CLEAR TYPEAHEAD empties the type-ahead buffer. Syntax CLEAR TYPEAHEAD Remarks CLEAR TYPEAHEAD will only clear characters that have been received by the local modem. There can be significant delay in receiving characters from a remote terminal and CLEAR TYPEAHEAD will not clear characters in transit. CLOSE Function CLOSE is used to close various file types. Syntax CLOSE ALL|ALTERNATE|DATABASES|INDEX Remarks CLOSE ALTERNATE will close the current alternate file. CLOSE DATABASES will close all database, index and memo files and select work area 1. CLOSE INDEX will close all index files in the current work area. CLOSE ALL will close all the above file types. See Also CLEAR ALL, RETURN, SET ALTERNATE TO, USE CMONTH() Function The CMONTH() function returns the character name of the month from a date expression. Syntax CMONTH(<expD>) Returns CHARACTER Example Assume the date is 10/21/93 ? CMONTH(DATE()) October See Also MONTH() COL() Function The COL() function returns the current column position on the remote and local screens. Syntax COL() Returns NUMERIC Remarks Returns current column position from 0 to 79. Example ? "Hello" ? col() 5 See Also @...SAY...GET, ROW() COMMPORT() Function The COMMPORT() function returns a numeric value corresponding to the comm port connection. Syntax COMMPORT() Returns NUMERIC Remarks If the user is connected locally, then COMMPORT() will return zero. Valid With pcboard.sys, door.sys, dorinfo1.def, chain.txt, callinfo.bbs See Also BAUD(), DTE(), ISLOCAL() CONFERENCE() Function The CONFERENCE() function returns the number of the conference or area the user was in before calling the dB Online door. Syntax CONFERENCE() Returns NUMERIC Valid With pcboard.sys, door.sys See Also NODE() CONTINUE Function CONTINUE searches for the next record in current database as specified by the conditions of the most recent LOCATE command. Syntax CONTINUE Remarks See the LOCATE command for details See Also FOUND(), LOCATE, SEEK COPEN() Function Opens a communications port. Syntax COPEN ( <expN1> , <expN2> , <expN3> [ , <expC> [ , <expN4> [ , <expN5> ] ] ] ) Returns NUMERIC Remarks <expN1> is the type of driver to be used for the open; <expN1> Driver 1 BIOS/Interrupt 14 2 Fast & Direct 3 FOSSIL 4 Smart Arnet 5 Smart DigiBoard <expN2> is a communications port (1 .. 16) <expN3> is the baud rate (110 ... 115200) <expC> is the parity; <expC> Parity æNÆ None æOÆ Odd æEÆ Even æSÆ Space æMÆ Mark <expN4> is the databits (8 or 7), <expN5> is the stop bits (0 or 1). You may open only 8 ports and you may not reopen the port that you are currently operating in. See Also CCLOSE() COUNT Function COUNT calculates the number of records in the current database that match specified conditions. Syntax COUNT [<scope>] [WHILE <expL1>] [FOR <expL2>] TO <var> Remarks All records in the current database are counted unless specified by the <scope>, WHILE, or FOR clauses. Example To count all your Ontario customers USE customer COUNT FOR province = "ON" to number ? number See Also AVERAGE, SUM CPEEKCHAR() Function Returns a character from a communications port. Syntax CGETS( <expN> ) Returns CHARACTER Remarks <expN1> is a communications handle returned by COPEN() See Also COPEN(), CCLOSE() CPORT() Function Returns the communications handle of the port used. Syntax CPORT( ) Returns NUMERIC Remarks You may use the returned value in any function that requires a communication handle otherwise obtained from COPEN(). You should not close this port using the CCLOSE() function. See Also COPEN(), CCLOSE() CPUTS() Function Sends out a character string to a communications port. Syntax CPUTS( <expN1> , <expC> [ , <expN2> ] ) Returns NUMERIC Remarks <expN1> is the communications handle returned by COPEN(), <expC> is the string to send, <expN2> is the number of characters to send. A carriage return and line feed is appended and sent with the string. CPUTS() will return the number of characters sent. See Also COPEN(), CCLOSE() CRC16() Function Returns the 16-bit CRC of a character string Syntax CRC16( <expC> , <expN>) Returns NUMERIC Remarks This functions computes the CCITT (ITI) Cyclic Redundancy Check word supporting the polynomial X^16+X^12+X^5+1. <expN> is the starting value. This is usually -1 or 0. See Also CRC32() CRC32() Function Returns the 32-bit CRC of a character string Syntax CRC32( <expC> , <expN> ) Returns NUMERIC Remarks This functions computes the CCITT (ITI) Cyclic Redundancy Check word supporting the polynomial X^16 + X^15 + X^14 + X^13 + X^12 + X^11 + X^10 + X^9 + X^8 + X^7 + X^6 + X^5 + X^4 + X^3 + X^2 + X^1 + X^0. <expN> is the starting value. This is usually -1 or 0. See Also CRC16() CREAD() Function Reads a series of characters from a communications port. Syntax CREAD( <expN1> , <expN2> [ , <expN3> ] ) Returns CHARACTER Remarks <expN1> is the communications handle returned by COPEN(), <expN2> is the number of characters to send, <expN3> is the optional timeout in milliseconds. If you do not use a timeout, this function returns immediately. See Also COPEN(), CCLOSE(), CGETS(), CWRITE() CRING() Function Returns whether or not a ring has been detected since the last CRING() function call. Syntax CRING ( <expN> ) Returns LOGICAL Remarks <expN> is the communications handle returned by COPEN(). See Also COPEN(), CCLOSE() CRTSSET() Function Set RTS on or off for a communications port. Syntax CRTSSET( <expN1> , <expN2> ) Returns LOGICAL Remarks <expN1> is a communications handle returned by COPEN() <expN2> is 1 to set RTS, 0 to clear it. CRTSSET() will return .T. if successful. If the line is being used for flow control such as XON/XOFF or DTR/DTS, it may cause unpredidictable results See Also COPEN(), CCLOSE() CRXCLEAR() Function Clears the receive buffer for a communications port. Syntax CRXCLEAR( <expN> ) Returns LOGICAL Remarks <expN> is a communications handle returned by COPEN(). This function returns .T. if successful. See Also COPEN(), CCLOSE() CSETPORT() Function Sets the parameters for a communications port. Syntax CSETPORT( <expN1> , <expN2> , <expC> , <expN3> , <expN4> ) Returns LOGICAL Remarks <expN1> is a communications handle returned by COPEN(), <expN2> is the baud rate (110 ... 115200), <expC> is the parity (æNÆ, æOÆ, æEÆ, æSÆ, æMÆ), <expN3> is the databits (8 or 7), <expN4> is the stopbits (0 or 1). This function returns .T. if successful. See Also COPEN(), CCLOSE() CSTATUS() Function Returns the line status for a communications port. Syntax CSTATUS( <expN1> [ , <expN2> ] ) Returns NUMERIC Remarks <expN1> is a communications handle returned by COPEN(), If <expN2> is non-zero, then the line status will be cleared. The return value is made up of any combinations of the following: Value Description 2 Overrun error. 4 Parity error. 8 Framing error. 16 Break signal detected. 32 Transmitter holding register empty. 64 Transmitter shift and holding registers empty. See Also COPEN(), CCLOSE() CTOD() Function The CTOD() function converts a character expression to a date value. Syntax CTOD(<expC>) or {<date>} Returns DATE Remarks Returns a date value by converting <expC>. The format of <expC> is mm/dd/yy with SET CENTURY OFF, or mm/dd/ccyy with SET CENTURY ON. The {} structure allows for date literals. The syntax is {mm/dd/yy}. Example STORE CTOD('02/28/93') to test ? test 02/28/93 ? test + 5 03/05/93 See Also DTOC(), SET CENTURY CTXCLEAR() Function Clears the transmit buffer for a communications port. Syntax CTXCLEAR( <expN> ) Returns LOGICAL Remarks <expN> is a communications handle returned by COPEN(). This function returns .T. if successful. See Also COPEN(), CCLOSE() CWRITE() Function Writes a series of characters from a communications port. Syntax CWRITE( <expN1> , <expC> , <expN2> [ , <expN3> ] ) Returns NUMERIC Remarks <expN1> is the communications handle returned by COPEN(), <expC> is the character string to be sent, <expN2> is the number of characters to send, <expN3> is the optional timeout in milliseconds. If you do not use a timeout, this function returns immediately. See Also COPEN(), CCLOSE(), CPUTS(), CREAD() DATABITS() Function The DATABITS() function returns the number of databits of the current communications port. Syntax DATABITS() Returns NUMERIC Remarks If a valid BBS drop file does not exist, the DATABITS() function returns a default value of 8. Valid With dorinfox.def, callinfo.bbs See Also PARITY(), STOPBITS() DATAPHONE() Function The DATAPHONE() function returns the user's data phone number. Syntax DATAPHONE() Returns CHARACTER Valid With exitinfo.bbs, door.sys, users.sys, callinfo.bbs See Also VOICEPHONE() DATE() Function The DATE() function returns the current system date. Syntax DATE() Returns DATE Example Assume the system date is 10/21/93 ? DATE() 10/21/93 See Also DAY(), MONTH(), SET CENTURY, YEAR() DAY() Function The DAY() function returns the day of the month from a date expression. Syntax DAY(<expD>) Returns NUMERIC Example If the system date is 10/21/93 ? DAY(DATE()) 21 See Also DATE(), MONTH(), YEAR() DBF() Function The DBF() function returns the filename of the database in the current work area. Syntax DBF() Returns CHARACTER Remarks Returns the full path used to specify the database in the current work area. Example USE customer ? dbf() c:customer.dbf See Also CDX(), FIELD(), LUPDATE(), MDX(), NDX(), RECCOUNT(), RECSIZE() DECLARE Function Declares one or more array variables. Syntax DECLARE <array> ( <expN1> [, <expN2>] ) [, ...] Remarks DECLARE is identical in operation to DIMENSION. Please See that command for more information. See Also DIMENSION DELETE Function DELETE marks records in the current database for deletion. Syntax DELETE [<scope>] [WHILE <expL>] [FOR <expL>] Remarks Unless otherwise specified DELETE marks only the current record for deletion. DELETE cannot be used with read only files. Example USE customer ? DELETED() .F. DELETE ? DELETED() .T. See Also DELETED(), PACK, RECALL, SET DELETED DELETED() Function The DELETED() function identifies records that are marked for deletion. Syntax DELETED() Returns LOGICAL Remarks Returns True (.T.) if the current record is marked for deletion, if not, False (.F.) is returned. Example USE customer ? DELETED() .F. DELETE ? DELETED() .T. See Also DELETE, PACK, RECALL, SET DELETED ON DIMENSION Function Creates one or more array variables. Syntax DIMENSION <array> ( <expN1> [, <expN2>] ) [, ...] Remarks If a variable existed by the same name as <array>, then it is overwritten and assigned the properties of an array. If the older variable is an array, then it is redimensioned, and its original values are placed back into the new array. A new arrayÆs elements are always filled with .F. after its creation. If you include <expN2>, then the array will be a two-dimensional array, and will have <expN1> rows and <expN2> columns. Example DIMENSION myarray(5) myarray(2)=3.5 myarray(3)=ôHelloö ? myarray(3) Hello ? myarray(2) 3.5 ? myarray(1) .F. See Also DECLARE DISKSPACE() Function The DISKSPACE() function returns the number of bytes available on the default drive. Syntax DISKSPACE() Returns NUMERIC See Also GETENV(), OS(), VERSION() DISPLAY Function DISPLAY is used to view the contents of the current database file. Syntax DISPLAY [OFF] [<scope>] [<expr list>] [WHILE <expL1>] [FOR <expL2>] Remarks The current record is displayed unless otherwise specified with the <scope>, WHILE, or FOR expressions. If <expr list> is not specified then all fields are displayed. The record number is displayed unless the OFF option is included. A memo field will be output in a word wrapped format only if it is explicitly specified in <expr list>. The memo field will be output in a column width defined by SET MEMOWIDTH TO. See Also LIST, SET MEMOWIDTH DO Function DO executes a user defined procedure and passes optional parameters. Syntax DO <proc name> [WITH <expr list>] Remarks The <proc name> is defined with the PROCEDURE command. Program execution passes to the corresponding procedure. After procedure execution, program control passes to the command after the DO statement. The WITH option allows parameter passing to the subroutine. The parameter list can contain any valid expression. If a parameter is specified as a single memory variable, any changes made to the variables value in the subroutine will be reflected in the calling programs variable. Example The following program calculates the area of a circle. area = 0 DO areacalc WITH 2 , area ? area 12.5663600 PROCEDURE areacalc PARAMETERS radius, result result = 3.14159 * radius^2 RETURN See Also PARAMETERS, PRIVATE, PROCEDURE, RETURN, SET PROCEDURE DO CASE Function DO CASE is a structured programming command that chooses one alternative from a set of choices. Syntax DO CASE CASE <expL> <commands> [CASE <lexpr] <commands> [...] [OTHERWISE] <commands> ENDCASE Remarks The <expL> following the CASE statements determine which set of <commands> are executed. The <command> set corresponding to the first <expL> to evaluate to True (.T.) will be executed. If none evaluate to True (.T.) then the <commands> corresponding to the OTHERWISE condition are executed if present. After a set of <commands> are executed, program execution continues after the ENDCASE command. See Also DO, DO WHILE, IF, IIF() DO WHILE Function DO WHILE is a structured programming command that allows a set of commands to be executed based on a specified condition. Syntax DO WHILE <expL> <commands> [EXIT] <commands> [LOOP] <commands> ENDDO Remarks The <expL> following the DO WHILE statement determines whether the <commands> in the structure are executed. The EXIT command transfers program control to the command following the ENDDO statement. It is often used with an IF...ENDIF structure. The LOOP command transfers program control back to the DO WHILE statement. The <expL> is then reevaluated and the <commands> conditionally executed. Example USE customer DO WHILE .NOT. EOF() .... DISPLAY IF QUIT = .T. EXIT ENDIF ENDDO See Also DO, DO CASE, IF, RETURN DOW() Function The DOW() function returns a number representing the day of the week. Syntax DOW(<expD>) Returns NUMERIC Remarks Returns a number representing the day of the week. Sunday returns 1, and Saturday returns 7 Example Assume the system date is 10/21/93 ? DOW(DATE()) 5 See Also CDOW(), DAY() DTE() Function The DTE() function returns the DTE baud of the user. Syntax DTE() Returns NUMERIC Valid With pcboard.sys, door.sys, callinfo.bbs See Also BAUD(), COMMPORT() DTOC() Function The DTOC() function returns a character representation of the date expression. Syntax DTOC(<expD>) Returns CHARACTER Remarks Returns a character representation of <expD> in the form mm/dd/yy if SET CENTURY is OFF, or mm/dd/ccyy if SET CENTURY is ON. Example Assume the system date is 10/21/93 ? DTOC(DATE()) 10/21/93 See Also CTOD(), SET CENTURY ERRORCOR() Function The ERRORCOR() function identifies if an error correcting connection has been established. Syntax ERRORCOR() Returns LOGICAL Valid With pcboard.sys, exitinfo.bbs, door.sys, callinfo.bbs EOF() Function The EOF() function indicates the end of the current database file. Syntax EOF() Returns LOGICAL Remarks Returns a logical true (.T.) when record pointer is positioned after the last logical record of the current database file. Example USE customer GOTO BOTTOM ? EOF() .F. SKIP 1 ? EOF() .T. See Also BOF(), FOUND() ERASE Function ERASE deletes a file from the disk directory. Syntax ERASE <filename> or DELETE FILE <filename> Remarks The file will be deleted if it exists on the drive. Example To delete c:\sales\customer.txt file = "c:\sales\customer.txt" ERASE &file ERROR() Function The ERROR() function returns the number corresponding to the error that caused an error condition. Syntax ERROR() Returns NUMERIC Remarks The ERROR() function is used for runtime error handling. In the procedure set by the ON ERROR command the ERROR() function can be used to attempt corrective action and then RETRY execution. The return values of the ERROR() function are outlined in APPENDIX A. Example The following program will recover from the error: File is already open. ON ERROR DO recover <commands> USE customer <commands> RETURN PROCEDURE recover IF ERROR() = 3 CLOSE DATABASES RETRY && attempt to re-use ENDIF RETURN See Also MESSAGE(), ON ERROR(), RETRY EXP() Function The EXP() function returns the value of ex. Syntax EXP(<expN>) Returns NUMERIC Remarks Returns the value ex where x is <expN>. Example ? EXP(1.000) 2.718 See Also OG() FCHSIZE() Function Changes the size of a file on disk Syntax FCHSIZE( <expN1>, <expN2>) Returns LOGICAL Remarks <expN1> is the file handle returned by FOPEN or FCREATE <expN2> is the size you wish the file to be If the file is not opened, or another errors occurs, .F. is returned and the ERROR() function is updated with the error number. See Also FOPEN(), FCLOSE(), FCREATE(), FSEEK(), FTELL() FCLOSE() Function Closes a files Syntax FCLOSE( <expN>) Returns LOGICAL Remarks <expN> is the file handle returned by FOPEN or FCREATE If the file is not opened, or another errors occurs, .F. is returned and the ERROR() function is updated with the error number. See Also FOPEN(), FCREATE() FCREATE() Function Creates and opens a file Syntax FCREATE( <expC> [, <expN>] ) Returns NUMERIC Remarks <expC> is a filename If you include <expN>, then it represents one of the followin file attributes. <expN> File Attribute 0 Read/Write (default) 1 Read Only 2 Hidden 3 Read Only / Hidden 4 System 5 Read Only / System 6 System / Hidden 7 Read Only / Hidden / System If an error occurs, then -1 is returned and FERROR() is updated with an error number. See Also FOPEN(), FCLOSE() FDATE() Function Returns the last updated date of the opened file Syntax FDATE( <expN1> ) Returns DATE Remarks <expN1> is a file handle returned by either FOPEN or FCREATE. If the file is not opened, or another errors occurs, null is returned and the ERROR() function is updated with the error number. See Also FOPEN(), FCREATE(), FTIME(), FSETTIME() FEOF() Function Determines if the fileÆs position is at the end of the file Syntax FEOF( <expN> ) Returns LOGICAL Remarks <expN> is the file handle returned by FOPEN or FCREATE If the file is not opened, or another errors occurs, .F. is returned and the ERROR() function is updated with the error number. See Also FOPEN(), FCLOSE(), FTELL(), FSEEK() FERROR() Function Returns a number that represents the last low-level file error that occured Syntax FERROR( ) Returns NUMERIC Remarks FERROR() returned zero (0) if no file errors have occured since and inclusing the last low-level file function. Otherwise it contains one of the following: Error Number Description 2 File not found 4 Too many files open (out of file handles) 5 Access denied 6 Invalid file handle given 8 Out of memory 25 Seek error 29 Disk full 31 Error opening file See Also FCHSIZE(), FCLOSE(), FCREATE(), FDATE(), FEOF(), FFLUSH(), FGETS(), FLEN(), FLLOCK(), FOPEN(), FPUTS(), FREAD(), FSEEK(), FSETTIME(), FTELL(), FTIME(), FLUNLOCK(), FWRITE() FFLUSH() Function Flushes a file to disk Syntax FFLUSH( <expN> ) Returns LOGICAL Remarks <expN> is the file handle returned by FOPEN or FCREATE If the file is not opened, or another errors occurs, .F. is returned and the ERROR() function is updated with the error number. See Also FOPEN(), FCLOSE(), FWRITE(), FPUTS() FGETS() Function Returns a character string read from an opened file Syntax FGETS( <expN1> [, <expN2>] ) Returns CHARACTER Remarks <expN1> is the file handle returned by FOPEN or FCREATE <expN2> is the maximum length of characters to read. The maximum character ever read is 254. If the file is not opened, or another errors occurs, null is returned and the ERROR() function is updated with the error number. See Also FOPEN(), FCLOSE(), FREAD() FIELD() Function The FIELD() function returns field names from the current database file. Syntax FIELD(<expN>) Returns CHARACTER Remarks eturns the field name corresponding to <expN> in the file structure of the current database file. The returned field name is in uppercase. Example USE customer ? FIELD(2) LASTNAME See Also BF() FILE() Function The FILE() function determines the existence of a file on the disk. Syntax FILE(<expC>) Returns LOGICAL Remarks eturns a logical True (.T.) if the file specified by <expC> exists. If no drive is specified the default drive is used. FILE() will search the current directory first and then any directories specified by the SET PATH TO command. Example If the default drive is C and customer.dbf is on D ? FILE(customer.dbf) .F. ? FILE(d:customer.dbf) .T. See Also ET PATH FIRSTNAME() Function The FIRSTNAME() function returns the user's first name with appropriate capitalization. Syntax FIRSTNAME() Returns CHARACTER Valid With pcboard.sys, dorinfo1.def See Also USERNAME() FLEN() Function Returns the size of the opened file Syntax FLEN( <expN1> ) Returns NUMERIC Remarks <expN1> is a file handle returned by either FOPEN or FCREATE. If the file is not opened, or another errors occurs, zero is returned and the ERROR() function is updated with the error number. See Also FOPEN(), FCREATE(), FCHSIZE() FLLOCK() Function Locks an opened file Syntax FLLOCK( <expN1>, <expN2>, <expN3> ) Returns LOGICAL Remarks <expN1> is a file handle returned by either FOPEN or FCREATE. The location and the size of the lock, is specified in the <expN2> and <expN3> value respectfully. If the lock is successful, then true (.T.) is returned, otherwise false (.F.) is returned and the ERROR() function is updated with the error number. Ony one lock can occur at a certain location in a file. Thus if another application has locked a similar area as your application, the lock will fail. Example Lock the file starting at location 0 for 16 bytes if .not. FLLOCK(flhandle,0,16) ? ôFile is locked!ö endif See Also FLUNLOCK(), FOPEN(), FCREATE() FLOCK() Function he FLOCK() function attempts to lock the current database file and returns the whether it was successful. Syntax LOCK() Remarks OCK() will return True (.T.) if dB Online was able to lock the current database file. It will return False (.F.) otherwise. Any file that has been locked by another user cannot be written to. A record remains locked until RLOCK() is issued, the file is closed, or the UNLOCK command is issued. FLOCK() will re-attempt to lock the current database based on the value of SET REPROCESS TO. Example IF FLOCK() PACK && must lock before PACKing ELSE ? "Unable to lock file", dbf() RETURN ENDIF See Also OCK(), RLOCK(), SET EXCLUSIVE, SET REPROCESS, UNLOCK, USE FLUNLOCK() Function Unlocks a previously locked opened file Syntax FLUNLOCK( <expN1>, <expN2>, <expN3> ) Returns LOGICAL Remarks <expN1> is a file handle returned by either FOPEN or FCREATE. The location and the size of the lock, is specified in the <expN2> and <expN3> value respectfully. If the unlock is successful, then true (.T.) is returned, otherwise false (.F.) is returned and the ERROR() function is updated with the error number. See Also FLLOCK(), FOPEN(), FCREATE() FOPEN() Function Opens a file Syntax FOPEN( <expC> [, <expN>] ) Returns NUMERIC Remarks <expC> is a filename If you include <expN>, then it represents one of the followin file attributes. <expN> Read/Write Attribute Buffering Scheme 0 Read Only (default) Buffered 1 Write Only Buffered 2 Read and Write Buffered 10 Read Only Unbuffered 11 Write Only Unbuffered 12 Read and Write Unbuffered If an error occurs, then -1 is returned and FERROR() is updated with an error number. See Also FCREATE(), FCLOSE() FOUND() Function he FOUND() function returns the success of the previous FIND, SEEK, LOCATE, or CONTINUE command. Syntax FOUND() Returns LOGICAL Remarks Returns a logical True (.T.) if the previous FIND, SEEK, LOCATE, or CONTINUE command is successful. If files are linked with the SET RELATION command dB Online does an implicit SEEK on the slave database files. FOUND() will then return the status of the slave files. If the record pointer is moved with any other commands the result of FOUND() is .F. See Also CONTINUE, EOF(), LOCATE(), SEEK, SET RELATIOIN FPUTS() Function Writes a character string, a carriage return, and a line feed to an opened file Syntax FPUTS( <expN1>, <expC> [, <expN2>] ) Returns NUMERIC Remarks <expN1> is the file handle returned by FOPEN or FCREATE <expC> is the character string that you wish to save to the file If included, <expN2> is the maximum length of characters to save. Otherwise, the entire string is saved. If the file is not opened, or another errors occurs, zero is returned and the ERROR() function is updated with the error number. If successful, the number of characters written. See Also FOPEN(), FCLOSE(), FWRITE() FREAD() Function Returns a character string read from an opened file Syntax FREAD( <expN1>, <expN2> ) Returns CHARACTER Remarks <expN1> is the file handle returned by FOPEN or FCREATE <expN2> is the maximum length of characters to read. If the file is not opened, or another errors occurs, null is returned and the ERROR() function is updated with the error number. See Also FOPEN(), FCLOSE(), FGETS() FSEEK() Function Set a files position Syntax FSEEK( <expN1>, <expN2> [, <expN3>] ) Returns NUMERIC Remarks <expN1> is the file handle returned by FOPEN or FCREATE <expN2> is the number of bytes to move the pointer <expN3> is a value that determines how the pointer is moved according to the following table: <expN3> Movement Relative to 0 the beginning of the file (default) 1 the current file pointer position 2 the end of the file Is successful, FSEEK() returns the new file position. If the file is not opened, or another errors occurs, null is returned and the ERROR() function is updated with the error number. See Also FOPEN(), FCLOSE(), FTELL() FSETTIME() Function Set the date and time of an opened file Syntax FSETTIME( <expN1>, <expD>, <expC>) Returns LOGICAL Remarks <expN1> is a file handle returned by either FOPEN or FCREATE. <expD> is the date that you wish the file to have. <expC> is the time that you wish the file to have in the following format: HH:MM:SS If the file is not opened, or another errors occurs, .F. is returned and the ERROR() function is updated with the error number. See Also FOPEN(), FCREATE(), FTIME(), FDATE() FTELL() Function Returns the current position of an opened file Syntax FTELL( <expN1> ) Returns NUMERIC Remarks <expN1> is a file handle returned by either FOPEN or FCREATE. If the file is not opened, or another errors occurs, zero is returned and the ERROR() function is updated with the error number. See Also FOPEN(), FCREATE(), FSEEK() FTIME() Function Returns the last updated time of the opened file Syntax FTIME( <expN1> ) Returns CHARACTER Remarks <expN1> is a file handle returned by either FOPEN or FCREATE. If the file is not opened, or another errors occurs, null is returned and the ERROR() function is updated with the error number. Example flhandle=fopen(ô\autoexec.batö) ? FTIME(flhandle) 10:45:23 See Also FOPEN(), FCREATE(), FDATE(), FSETTIME() FUNCTION Function Identifies the start of a user-defined function Syntax FUNCTION <function name> Remarks The FUNCTION statement is quite like the PROCEDURE statement, except that upon return from the function, a value can be returned and placed on the evaluation stack. Functions can be used anywhere an expression can be used, but they must return the correct type needed or a DATA TYPE MISMATCH error will occur at run-time. The PARAMETERS statement can proceed the FUNCTION statement to declare parameters for this function. Example ? areacalc(2) 12.5663600 FUNCTION areacalc PARAMETERS radius RETURN 3.14159 * radius^2 See Also PROCEDURE, PARAMETERS FWRITE() Function Writes a character string to an opened file Syntax FWRITE( <expN1>, <expC> [, <expN2>] ) Returns NUMERIC Remarks <expN1> is the file handle returned by FOPEN or FCREATE <expC> is the character string that you wish to save to the file If included, <expN2> is the maximum length of characters to save. Otherwise, the entire string is saved. If the file is not opened, or another errors occurs, zero is returned and the ERROR() function is updated with the error number. If successful, the number of characters written. See Also FOPEN(), FCLOSE(), FPUTS() GETENV() Function The GETENV() function returns the value of an environmental system variable. Syntax GETENV(<expC>) Returns CHARACTER Remarks Returns the value of the DOS system variable specified by <expC> such as PATH or COMSPEC. If the character expression is not found, dB Online returns a null string. Example ? GETENV("COMSPEC") C:\COMMAND.COM ? GETENV("PATH") C:\DOS;C:\BIN See Also DISKSPACE, OS(), VERSION() GO|GOTO Function GO|GOTO positions the record pointer to a specific record in the active database file. Syntax [GO|GOTO] <expN> or GO|GOTO TOP|BOTTOM Remarks If the [GO|GOTO] optional command is not specified then <expN> must begin with a numeric constant. If an index file is active GO TOP|BOTTOM refer to the top and bottom logical records in the index file. GO|GOTO <expN> always refers to a specific record number. If SET DELETED is ON, you may access a record marked for deletion by directly specifying its record number. Example USE customer GO TOP ? RECNO() 1 5 ? RECNO() 5 See Also RECNO(), SKIP IF Function IF is a structured programming command that allows the conditional execution of commands. Syntax IF <expL> <commands> [ELSE] <commands> ENDIF Remarks If <expL> is evaluated to True (.T.) then the first set of <commands> are executed and program control is transferred to the ENDIF statement. If <expL> is evaluated to False (.F.) then dB Online transfers program control to the ELSE statement or the ENDIF statement if the ELSE statement is omitted. See Also DO CASE, IIF() IIF() Function The IIF() function is a shortcut to the IF...ENDIF structure. It returns one of two values based on a logical expression. Syntax IIF(<expL> , <expr1> , <expr2>) Returns <expr1> or <expr2> Remarks Returns the value of <expr1> if <expL> is Logical True (.T.), otherwise it returns the value of <expr2>. Example lastname = "Smith" ? IIF(sex = 'M',"Mr. ","Ms. ") + lastname See Also IF...ENDIF, DO CASE INKEY() Function The INKEY() function returns a value representing the most recent key pressed by either the remote or local terminals. It does not wait for a keypress. Syntax INKEY( [<expN>] ) Returns NUMERIC Remarks Returns a value in the range of 0 to 255 corresponding to a value in the IBM Extended Character. If there are several characters in the type-ahead buffer the first character is returned and cleared from the buffer. If you supply an argument to INKEY, it will wait <expN> seconds. If 0 is the argument or no argument is present, it will wait indefinitely. INKEY() returns zero if no key is pressed and the control-key equivalent of cursor and extended keys. The return values of INKEY are identified in the following table: Cursor Alternative INKEY() return Key Keys value r CD 4 l CS 19 t CE 5 b CX 24 Cr CB 2 Cl CZ 26 I CV 22 D CG 7 h Ca 1 e Cf 6 u Cr 18 d Cc 3 Ch C] 29 Ce Cw 23 E 27 Cu C_ 31 Cd C] 30 Example ? "Press any key to continue" DO WHILE INKEY() =0 @ 1,72 SAY TIME() ENDDO See Also CHR(), LASTKEY(), WAIT INPUT Function INPUT is used to input numeric information from the keyboard. Syntax INPUT [<expC>] TO <var> Remarks The optional <expC> is displayed as a prompt for input. The value returned to the <var> is the numeric value of the characters inputted. Example INPUT "Type in your age " TO age && If 28 is entered ? age 28 See Also ACCEPT, WAIT INT() Function The INT() function return the integer portion of a numeric argument Syntax INT(<expN>) Returns NUMERIC Remarks Returns the integer portion of <expN>. All digits to the right of the decimal point are discarded. Example ? INT(23.55) 23 ? INT(-5.5) -5 ISALPHA() Function The ISALPHA function returns a logical True (.T.) if a character string begins with an alpha character. Syntax ISALPHA(<expC>) Returns LOGICAL Remarks Returns a logical True (.T.) if the first character in <expC> is an upper or lower case letter between a and z. Example ? ISALPHA("HELLO") .T. ? ISALPHA("123 Main St.") .F. See Also ISLOWER(), ISUPPER(), ISDIGIT() ISANSI() Function The ISANSI() function returns whether the user is in ANSI compatible mode. Syntax ISANSI() Returns LOGICAL Valid With pcboard.sys, door.sys, dorinfo1.def, chain.txt See Also ISCOLOR(), ISRIP() ISCOLOR() Function The ISCOLOR() function determines whether the user has selected color operation. Syntax ISCOLOR() Returns LOGICAL Remarks This information is provided by a BBS drop file. ISCOLOR() a logical True (.T.) if the user has selected color operation. Valid With pcboard.sys, door.sys, callinfo.bbs Example To change default black and white colors if user is in color mode: IF ISCOLOR() SET COLOR TO W+/B,N/BG ENDIF See Also SET COLOR ISDIGIT() Function Returns true if the first character is a digit. Syntax ISDIGIT( <expC> ) Returns NUMERIC Remarks This function only processes the first character, the rest are ignored. Example ? ISDIGIT(ôHelloö) .F. ? ISDIGIT(ô123 Elmvale Roadö) .T. See Also ISALPHA(), ISUPPER(), ISLOWER() ISLOCAL() Function The ISLOCAL() function returns whether the user is in local mode. Syntax ISLOCAL() Returns LOGICAL Valid With all ISLOWER() Function The ISLOWER() function returns a logical True (.T.) if the character expression begins with a lowercase letter. Syntax ISLOWER(<expC>) Returns LOGICAL Example ? ISLOWER("Hello") .F. ? ISLOWER("hello") .T. ? ISLOWER("123 Main St.") .F. See Also ISALPHA(), ISUPPER(), ISDIGIT() ISREMPTY() Function Returns whether the receive buffer is empty or not. Syntax ISREMPTY( <expN1> ) Returns LOGICAL Remarks <expN1> is the communications handle returned by COPEN(). See Also COPEN(), CCLOSE() ISRFULL() Function Returns whether the receive buffer is full or not. Syntax ISRFULL( <expN1> ) Returns LOGICAL Remarks <expN1> is the communications handle returned by COPEN(). See Also COPEN(), CCLOSE() ISRIP() Function The ISRIP() function returns whether the user is in RIP mode. Syntax ISRIP() Returns LOGICAL Valid With pcboard.sys, door.sys See Also ISANSI(), ISCOLOR() ISTEMPTY() Function Returns whether the transmit buffer is empty or not. Syntax ISTEMPTY( <expN1> ) Returns LOGICAL Remarks <expN1> is the communications handle returned by COPEN(). See Also COPEN(), CCLOSE() ISTFULL() Function Returns whether the transmit buffer is full or not. Syntax ISTFULL( <expN1> ) Returns LOGICAL Remarks <expN1> is the communications handle returned by COPEN(). See Also COPEN(), CCLOSE() ISUPPER() Function The ISUPPER() function returns a logical True (.T.) if the character expression begins with a uppercase letter. Syntax ISUPPER(<expC>) Returns LOGICAL Example ? ISUPPER("Hello") .T. ? ISUPPER("hello") .F. ? ISUPPER("123 Main St.") .F. See Also ISALPHA(), ISLOWER(), ISDIGIT() LANGUAGE() Function The LANGUAGE() function returns the user's language filename extension. Syntax LANGUAGE() Returns CHARACTER Valid With pcboard.sys Remarks The LANGUAGE() function will return a null string if the language extension is English. Otherwise it will return a 4 character string which could correspond to the extension on text files to be displayed: i.e.. If the French language is chosen then ".FRE" is returned. LASTKEY() Function The LASTKEY() function returns the value of the last key pressed to exit a full screen READ command. Syntax LASTKEY() Returns NUMERIC Remarks The return values of LASTKEY correspond to the INKEY() values. Example @ 2,2 SAY "NAME" GET NAME <commands> READ IF LASTKEY() = 27 QUIT ENDIF See Also INKEY() LEFT() Function The LEFT() function returns a number of characters from the beginning of the specified character expression. Syntax LEFT(<expC> , <expN>) Returns CHARACTER Remarks Returns the leftmost <expN> characters in <expC>. If <expN> is less than or equal to zero, dB Online returns a null string. If <expN> is greater than the length of <expC>, dB Online returns the entire string. Example ? LEFT(æHello ThereÆ,5) Hello See Also AT(), LTRIM(), RIGHT(), SUBSTR(), TRIM() LEN() Function The LEN() function returns the length of a character string. Syntax LEN(<expC>) Returns NUMERIC Remarks Returns the length of <expC>. If <expC> is a null string, dB Online returns zero. Example ? LEN("Good Morning") 12 See Also TRIM() LINENO() Function Returns the currently executing line number Syntax LINENO( [<expN>] ) Returns NUMERIC Remarks The line number is derived from the source code used to compile the currently running DBX file. The <expN> parameter always ignored, and is only provided as a means of compatibility. See Also PROGRAM() LIST Function LIST is used to view the contents of the current database file. Syntax LIST [OFF] [<scope>] [<expr list>] [WHILE <expL1>] [FOR <expL2>] Remarks All records are listed unless otherwise specified with the <scope>, WHILE, or FOR expressions. If <expr list> is not specified then all fields are displayed. The record number is displayed unless the OFF option is included. A memo field will be output in a word wrapped format only if it is explicitly specified in <expr list>. The memo field will be output in a column width defined by SET MEMOWIDTH TO. See Also DISPLAY, SET MEMOWDTH LOCATE Function LOCATE scans the active database for records that satisfy specified conditions. Syntax LOCATE [<scope>] [WHILE <expL1>] [FOR <expL2>] [...] [CONTINUE] Remarks LOCATE searches the entire database unless otherwise specified with the <scope>, WHILE, or FOR expressions. LOCATE will find the first record to match the specified conditions. If this record is found then FOUND() returns .T. Use CONTINUE to find the next occurrence of the specified conditions. When the record counter reaches the end of the file or the end of the <scope> then FOUND() returns .F. You can have a different LOCATE/CONTINUE for each work area. The most recent LOCATE in any work area overrides any previous. See Also CONTINUE, FOUND(), SEEK LOCK() Function The LOCK() function attempts to lock the current record and returns the whether it was successful. LOCK() is identical to RLOCK(). Please refer to RLOCK() in this section. Syntax LOCK() | RLOCK() See Also FLOCK(), RLOCK(), SET EXCLUSIVE, SET REPROCESS, UNLOCK, USE LOG() Function The LOG() function returns the natural logarithm of a numeric expression. Syntax LOG(<expN>) Returns NUMERIC Remarks Returns the natural logarithm of <expN>. <expN> must be greater than zero. Example ? LOG(2.71828) 1.00000 See Also EXP() LOWER() Function The LOWER() function converts a character expression to lower case. Syntax LOWER(<expC>) Returns CHARACTER: Remarks Returns a string in which all uppercase characters in <expC> have been converted to lowercase. Example ? LOWER("Hello") hello See Also ISALPHA(), ISLOWER(), ISUPPER(), UPPER() LTRIM() Function The LTRIM() function removes leading blanks from a character expression. Syntax LTRIM(<expC>) Returns <expC> Example ? STR(12.45) 12.45 ? LTRIM(STR(12.45)) 12.45 See Also LEFT(), RIGHT(), RTRIM(), STR(), SUBSTR(), TRIM() LUPDATE() Function The LUPDATE() function returns the last date the current database file was updated. Syntax LUPDATE() Returns DATE Example Assume the system date is 10/21/93 USE customer ?LUPDATE() 9/15/93 PACK ?LUPDATE() 10/21/93 See Also DBF() MAX() Function The MAX() function returns the largest of two expressions. Syntax MAX(<expr1>,<expr2>) Returns <expr> Remarks Returns the largest of the two values. Both <expr1> and <expr2> must be the same type and cannot be Logical. Example ? MAX(55,102) 102 See Also MIN() MDX() Function The MDX() function returns the filename for the active index files in a work area. Syntax MDX(<expN1> [,<expN2> | <alias>]) Returns CHARACTER Remarks Returns the filename of an open .mdx file in a work area. <expN1> is the .mdx file position in the index file list specified by the SET INDEX TO <file list>, or USE INDEX <file list> commands. The optional second parameter returns .mdx files for other work areas. Example USE customer INDEX name.mdx, phone.mdx ? MDX(1) c:name.mdx ? MDX(2) c:phone.mdx See Also CDX(), DBF(), FIELD(), LUPDATE(), NDX(), SET INDEX, SET ORDER MEMORY() Function Returns the amount of free memory on your system. Syntax MEMORY () Returns NUMERIC Remarks This functions returns the number of kilobytes of available memory. In DOS, this would be any free memory underneath 640k. Example ? MEMORY() 365 MENU TO Function Activates a menu bar created with @... PROMPT Syntax MENU TO <memvar> Remarks The value initially contained in the <memvar> specifies which menu bar is activated. Upon exit from the menu. the <memvar> variable contains the choice. If E is pressed, <memvar> wil contain 0. See Also @... PROMPT MESSAGE() Function The MESSAGE() function returns the message corresponding to an error condition. Syntax MESSAGE() Returns CHARACTER Remarks Returns the character message during a runtime error handling procedure. Example ON ERROR DO recover <commands> PROCEDURE recover ?"dB Online has encountered a run time error" ? MESSAGE() ? "Now exiting" QUIT RETURN See Also ERROR() MIN() Function The MIN() function returns the smaller of two numeric or date functions. Syntax MIN(<expr1> , <expr2>) Returns <expr> Remarks Returns the smaller of the two values. Both <expr1> and <expr2> must be the same type and cannot be Logical. Example ? MIN(55,102) 55 See Also MAX() MOD() Function The MOD() function returns the remainder from a division of two numbers. Syntax MOD(<expN1> , <expN2>) Returns NUMERIC Remarks Returns the modulus, which is the remainder of <expN1> divided by <expN2> Example ? MOD(10,8) 2 ? MOD(0,60) 0 MODIFY FILE | COMMAND Function Opens an editing window for editing a text file Syntax MODIFY FILE | COMMAND <filename> [NOEDIT] Remarks If MODIFY COMMAND is used and the filename has no file extension, then .PRG will be assumed. This statement has the same effect as MODIFY MEMO, but will allow a user to edit a text file.. By speficying the NOEDIT clause, the user will not be able to alter the contents of the file. NOTE: Only the first 64000 bytes of the fille will be editable, and upon saving the file will be truncated to only 64000 bytes See Also MODIFY MEMO MODIFY MEMO Function Opens an editing window for editing a memo field Syntax MODIFY MEMO <memovar> [NOEDIT] Remarks This statement cause the same effect as placing a @ GET statement with a memo field and then having the user press Ch. By speficying the NOEDIT clause, the user will not be able to alter the contents of the memo field. See Also @...GET, MODIFY FILE MONTH() Function The MONTH() function returns a number representing the month from a date expression. Syntax MONTH(<expD>) Returns NUMERIC Remarks Returns a value between 1 and 12 corresponding to January to December. Example Assume the system date is 10/21/93 ? MONTH(DATE()) 10 See Also CMONTH(), DAY(), YEAR() NDX() Function The NDX() function returns the filename for the active index files in a work area. Syntax NDX(<expN1> [ ,<expN2> | <alias>]) Returns CHARACTER Remarks Returns the filename of an open .ndx file in a work area. <expN1> is the .ndx file position in the index file list specified by the SET INDEX TO <file list>, or USE INDEX <file list> commands. The optional second parameter returns .ndx files for other work areas. Example USE customer INDEX name.ndx, phone.ndx ? NDX(1) c:name.ndx ? NDX(2) c:phone.ndx See Also CDX(), DBF(), LUPDATE(), SET INDEX, SET ORDER NODE() Function The NODE() function return the node number the user is on. Syntax NODE() Returns NUMERIC Valid With pcboard.sys, door.sys, callinfo.bbs Remarks The NODE() function is useful for creating temporary file names for each BBS node. See Also CONFERENCE() NOTE Function NOTE is used to indicate comments in the source code. Syntax NOTE|* <text> [<command>]&& <text> Remarks The <text> indicated above is ignored by the compiler. If any comment line ends with a semicolon, then the next line is also treated as a comment. && is used to insert a comment on the same line as a command. Example USE customer.dbf && open customer database NOTE List all data LIST ON ERROR Function ON ERROR is used to enable runtime error handling. Syntax ON ERROR [DO <proc name> [WITH <expr list>]] Remarks ON ERROR responds to dB Online database errors as outlined in APPENDIX 3. When a runtime error occurs, program control will transfer to the procedure <proc name> defined in the ON ERROR command. To disable error trapping enter ON ERROR R without a DO command. In the procedure the function ERROR() will identify the error which occurred and the function MESSAGE() will return a character message of the error which occurred. If the error recovery procedure ends with a RETRY command, the same command which generated the error will be executed. However RETRY will not attempt to re-execute any conditional commands such as IF, WHILE, CASE etc. Example The following program will recover from the error: File is already open. ON ERROR DO recover <commands> USE customer <commands> RETURN PROCEDURE recover IF ERROR() = 3 CLOSE DATABASES RETRY && attempt to USE again ENDIF RETURN See Also INKEY(), ON ESCAPE ON ESCAPE Function ON ESCAPE responds to the user pressing E. Syntax ON ESCAPE [DO <proc name> [WITH <expr list>]] Remarks When the user presses E during program execution, program control will be transferred to the procedure <proc name> define in the ON ESCAPE DO command. ON ESCAPE only works when SET ESCAPE is ON. To disable error trapping enter ON ESCAPE R without a DO command. During the execution of the ON ESCAPE procedure, escape key trapping is disabled. Example This example allows the user to cancel a long listing: USE customer SET ESCAPE ON ON ESCAPE DO if_esc LIST RETURN PROCEDURE if_esc ACCEPT "Do you want to quit (Y/N)" TO response IF 'Y' $ UPPER(response) RETURN ELSE RETRY ENDIF See Also INKEY(), ON ERROR, READKEY(), SET ESCAPE OS() Function The OS() function returns the name of the operating system under which dB Online is running. Syntax OS() Returns CHARACTER Remarks Returns a character value of the operating system. As dB Online only operates in DOS environments, OS() returns the DOS version. Example ? OS() DOS 6.0 See Also DISKSPACE(), GETENV(), VERSION() PACK Function PACK permanently removes all record marked for deletion in the active database file. Syntax PACK Remarks All open index files are automatically REINDEXed and all memofiles area automatically compressed. PACK cannot be used with read only files. See Also DELETE, RECALL, REINDEX PAGELEN() Function The PAGELEN() function returns the user's page length setting. Syntax PAGELEN( [ <expN> ]) Returns NUMERIC Remarks PAGELEN() will accept an optional numeric expression to allow the value to be changed. This can be done using the new EQUALS command. eg: = PAGELEN(23) Valid With exitinfo.bbs, door.sys, user.sys, chain.txt, callinfo.bbs See Also @..SAY...GET PARAMETERS Function PARAMETERS assigns local variable names to data items passed from a calling program. Syntax PARAMETERS <var list> Remarks The PARAMETERS command must follow the PROCEDURE <proc name> command. The <var list> corresponds to the <expr list> from the calling program. All variables identified in the PARAMETERS list are private to that procedure. When the procedure ends, the PARAMETER variables are released. See Also DO, PRIVATE, PROCEDURE , PUBLIC, SET PROCEDURE PARITY() Function The PARITY() function identifies the parity setting of the current comm port. Syntax PARITY() Returns CHARACTER Valid With door.sys Remarks PARITY() will return 'EVEN' for even parity and 'NONE' for no parity. PASSWORD() Function The PASSWORD() function returns the user's password. Syntax PASSWORD() Returns CHARACTER Valid With pcboard.sys, door.sys, users.sys, callinfo.bbs See Also SECURITY() PRIVATE Function PRIVATE creates new memory variables in a lower-level subroutine. Syntax PRIVATE <var list> Remarks Any changes made to private memory variables do not affect other variables of the same name in higher level procedures. When a procedure containing a private memory variable ends, the value hidden by PRIVATE variable are then available. Any variables defined in a PARAMETERS list are PRIVATE for that subroutine. See Also DO, PARAMETERS, PUBLIC PROCEDURE Function PROCEDURE identifies the beginning of a procedure subroutine definition. Syntax PROCEDURE <proc name> [PARAMETERS <var list>] <commands> Remarks Procedures can be placed after the main program or in separate procedure files. These procedure files are identified in the main program with the SET PROCEDURE TO command. The optional PARAMETERS variable list indicate PRIVATE memory variables corresponding to the parameters passed with DO <proc name> WITH <expr list>. A RETURN statement is used to terminate PROCEDURE execution. If the RETURN statement is not included, one is assumed before the next PROCEDURE command or the end of file. Example The following program calculates the area of a circle. area = 0 DO areacalc WITH 2 , area ? area 12.5663600 PROCEDURE areacalc PARAMETERS radius, result result = 3.14159 * radius^2 RETURN See Also DO, PARAMETERS, SET PROCEDURE PROGRAM() Function Returns the name of the currently executing program. Syntax PROGRAM( [<expN>] ) Returns CHARACTER Remarks The name is derived from the filename of the source code used to compile the currently running DBX file. The <expN> parameter always ignored, and is only provided as a means of compatibility. See Also LINENO() PROTOCOL() Function The PROTOCOL() function returns the user's selected protocol. Syntax PROTOCOL() Returns CHARACTER Valid With door.sys, users.sys, callinfo.bbs Remarks The return value will be a single character. Possible values include: Return Value Protocol A ASCII X Xmodem C Xmodem-CRC 1 Xmodem-1K Y Ymodem (batch) G Ymodem-G Z Zmodem K Kermit PUBLIC Function PUBLIC makes memory variables globally available. Syntax PUBLIC <var list> Remarks All variables defined in your program are considered PUBLIC unless they are declared as private within a subroutine using the PARAMETERS or PRIVATE command. See Also PARAMETERS, PRIVATE QUIT Function QUIT stops the execution of the current dB Online session. dB Online will close all files and return to the calling program (BBS etc.) Syntax QUIT Remarks QUIT will return a 0 to the DOS errorlevel. See Also CANCEL, RETURN RCV...() Function Receives a file(s) via the modem. Syntax RCVASCII ( <expC> [ , <expN1> ] ) RCVKERMIT ( <expC> [ , <expN1> ] ) RCVYMODEM ( <expC> [ , <expN1> [ , <expN2> ] ] ) RCVXMODEM ( <expC> [ , <expN1> [ , <expN2> ] ] ) RCVZMODEM ( <expC> [ , <expN1> ] ) Returns NUMERIC Remarks All of the above functions return the bytes transfered. For RCVASCII(), RCVKERMIT() and RCVXMODEM(), <expC> represents a path and a filename to store the incoming data into. For RCVYMODEM() and RCVZMODEM(), <expC> represents just a path to store the incoming files into. <expN1> is the optional communications handle returned by COPEN(). By default the currently active communications port is used. For RCVYMODEM(), <expN2> may be 1 to represent the use of the Ymodem-G protocol. For RCVXMODEM(), <expN2> is as follows: <expN2> Function 0 Use Xmodem-CRC protocol (default) 1 Use Xmodem-1k protocol 2 Use Xmodem-G protocol See Also SND...(), COPEN(), CCLOSE() READ Function READ activates all @...GETs issued since the last CLEAR, CLEAR ALL, CLEAR GETS, or READ. Syntax READ [SAVE] Remarks READ allows the user to enter data into multiple fields on a single input screen. The fields are defined by @...GET commands. The user is allowed to tab through the input fields in order to enter information. The full screen editing keys are defined in APPENDIX 4. READ clears all GETs after editing is finished. The SAVE option does not clear the GETs, they will be active when the next READ command is issued. If an @...GET is issued with a field of a read only file, then the read command will allow the user to browse through the data but not change any values. Example To allow a user to enter his name with a maximum of 12 characters. The first character will be forced to uppercase. name = SPACE(12) @ 3,3 SAY "Enter your name: " GET name PICTURE "!XXXXXXXXXXX" READ See Also @...SAY...GET, @...EDIT, CLEAR, CLEAR GETS READKEY() Function The READKEY() function returns a value representing the key pressed to exit a full screen read statement. READKEY() also indicates whether any data was changed. Syntax READKEY() Returns NUMERIC Remarks The READKEY() return values are identified in the table below. If none of the data had been changed, the return value is between zero and 15. If any of the data had been changed the return value increases by 256. Key pressed READKEY() READKEY() Meaning No changes Changes Left - ^Home - <- 0 256 Backward one character Right 1 257 Forward one character Up 4 260 Backward one field Down 5 261 Forward one field PgUp 6 262 Backward one screen PgDn 7 263 Forward one screen Esc 12 --- Terminate without save ^End - ^W 13 270 Terminate with save Enter - Tab 15 271 Completed last field Example To determine if the contents of a memory variable were altered and to REPLACE a field if changes were made. @ 2,2 SAY "NAME" GET mname READ IF READKEY() >=256 && if data changed REPLACE name WITH mname ENDIF See Also INKEY(), READ RECALL Function RECALL unmarks records in the current database that have been marked for deletion. Syntax RECALL [<scope>] [WHILE <expL1>] [FOR <expL2>] Remarks Unless otherwise specified RECALL unmarks only the current record. RECALL cannot be used with read only files. Example USE customer ? DELETED() .T. RECALL ? DELETED() .F. See Also DELETE, DELETED(), PACK, SET DELETED RECCOUNT() Function The RECCOUNT() function returns the number of records in the currently selected database. Syntax RECCOUNT() Returns NUMERIC Example USE clients.dbf ? RECCOUNT() 49 See Also DBF(), DISKSPACE(), RECNO(), RECSIZE() RECNO() Function The RECNO() function returns the current record number of the selected database. Syntax RECNO() Returns NUMERIC Example USE clients.dbf ? RECNO() 1 SKIP ? RECNO() 2 GO BOTTOM ? RECNO() 49 See Also GOTO, RECCOUNT(), SKIP RECSIZE() Function The RECSIZE() functions returns the size of a record in the currently selected database file. Syntax RECSIZE() Returns NUMERIC Example USE customer.dbf ? RECSIZE() 43 See Also DBF(), DISKSPACE(), LUPDATE(), RECCOUNT() REGISTEREDTO() Function Returns the Company Name that dB Online is registered to Syntax REGISTEREDTO() Returns CHARACTER Remarks This information is derived from the DBONLINE.KEY file. If this version is shareware, then this will return a blank string. See Also SERIALNO() REINDEX Function REINDEX rebuilds all active index files in the current work area. Syntax REINDEX Remarks Only index files that have been opened with the corresponding database file will be rebuilt. REINDEX cannot be used with read only files. See Also PACK, SET INDEX, USE RENAME Function RENAME changes the name of a file on disk. Syntax RENAME <filename1> TO <filename2> Remarks If drive specifiers are used, they must both indicate the same drive. RENAME cannot be used to copy files to different drives. REPLACE Function REPLACE changes the contents of specified fields in the current database. Syntax REPLACE [<scope>] <field> WITH <expr> [,<field> WITH <expr> ...] [WHILE <expL1>] [FOR <exp2L>] Remarks REPLACE only changes the current record unless otherwise specified by the <scope>, WHILE or FOR expressions. The <field> and WITH <expr> must have the same data type. If replacements are made on a key field of an index file will update the index file if it's in use. Thus the <scope>, WITH, and FOR conditions will not operate properly as the record order will change as the records are replaced. The records should be replaced in natural order when replacing more than a single record. REPLACE cannot be used with read only files. Example To raise all product costs by 10%: USE product INDEX part_no SET ORDER TO 0 && Record ordering REPLACE ALL part_no WITH part_no * 1.10 REPLICATE() Function The REPLICATE() function repeats a character expression a specified number of times. Syntax REPLICATE(<expC>,<expN>) Returns CHARACTER Remarks Returns <expC> repeated <expN> times. The resulting character expression must not exceed 254 characters. Example REPLICATE can be used to create bar graphs percent1 = 30 percent2 = 60 ? percent1, REPLICATE('*',percent1/10) 30 *** ? percent2, REPILCATE('*',percent2/10) 60 ****** See Also SPACE() RESTORE Function RESTORE retrieves memory variables from a memory file. Syntax RESTORE FROM <filename> Remarks A .mem file extension is assumed unless otherwise specified. Any current memory variables with the same name as those being restored are overwritten. The RESTORed variables will have the same scope (PUBLIC, PRIVATE) as when the were SAVEed. All current memory variables are retained when using RESTORE. Example variable = "Hello" SAVE TO memfile variable = "" RESTORE FROM memfile ? variable Hello See Also SAVE, STORE RETRY Function RETRY completes subroutine execution and returns program control to the command that called the subroutine. Syntax RETRY Remarks RETRY is used mainly in error recovery where it can repeat a command until it is successfully executed. RETRY will re-execute the command that called the current subroutine. This is in contrast to the RETURN command that executes the command after the calling command. If a runtime error occurs in a program that has a routine defined by ON ERROR DO, then RETRY can be used to re-attempt the erroneous command when the error conditions are corrected. Example The following program will recover from the error: File is already open. ON ERROR DO recover <commands> USE customer <commands> RETURN PROCEDURE recover IF ERROR() = 3 CLOSE DATABASES RETRY && attempt to USE again ENDIF RETURN See Also ERROR(), ON ERROR, RETURN RETURN Function RETURN completes procedure/function execution and returns program control to the calling program. The command after the calling command is then executed. Syntax RETURN [TO MASTER | <expr>] Remarks The TO MASTER option will return program control to the highest level calling program. This allows a simple method of RETURNing from nested procedures. If the RETURN command is not included at the end of a program or procedure file a RETURN is assumed before the next PROCEDURE or FUNCTION statement or the end of file. RETURN releases all PRIVATE variables of a procedure. If the RETURN statement contains an expression, then it must be part of a FUNCTION declaration. See Also DO, PRIVATE, PROCEDURE, FUNCTION RIGHT() Function The RIGHT() function returns a specified number of characters from the end of a character expression. Syntax RIGHT(<expC>,<expN>) Returns CHARACTER Remarks Return the last <expN> characters of <expC>. If <expN> is less than or equal to zero, then a null string is returned. If <expN> is greater than the length of <expC> then the entire string is returned. Example ? RIGHT('Hello Bob',3) Bob See Also LEFT(), LTRIM(), SUBSTR(), TRIM() RLOCK() Function The RLOCK() function attempts to lock the current record and returns the whether it was successful. Syntax RLOCK() | LOCK() Remarks RLOCK() will return True (.T.) if dB Online was able to lock the current record. It will return False (.F.) otherwise. Any record that has been locked by another user cannot be written to. A record remains locked until the the record pointer is moved, the file is closed, or the UNLOCK command is issued. RLOCK() will re-attempt to lock the current record based on the value of SET REPROCESS TO. Example IF RLOCK() DO editproc && edit the record ELSE CLEAR ? "Unable to lock record" RETURN ENDIF See Also FLOCK(), LOCK(), SET EXCLUSIVE, SET REPROCESS, UNLOCK, USE ROUND() Function The ROUND() function rounds off numbers to a specified number of decimal places. Syntax ROUND(<expN1>,<expN2>) Returns NUMERIC Remarks Returns <expN1> rounded off to <expN2> decimal places. If <expN2> is negative, Round() returns a rounded whole number. Example ? ROUND(123.4567,2) 123.46 ? ROUND(123.4567,0) 123 ? ROUND(123.4567,-1) 120 See Also INT() ROW() Function he ROW() function returns the row number of the current cursor position on the local and remote screens. Syntax ROW() Returns NUMERIC Remarks Returns the current row number between 0 and 24. Example CLEAR ? ROW() 1 ? ROW() 2 See Also @...SAY...GET, ROW() RTRIM() Function The RTRIM() function removes trailing blanks from a character expression. Syntax RTRIM(<expC>) Returns CHARACTER Remarks The RTRIM() function is identical to the TRIM() function. Example title = "Mr. " name = "Jones" ? title + name Mr. Jones ? RTRIM(title)+' '+name Mr. Jones See Also LEFT(), LTRIM(), RIGHT(), TRIM() RUN Function RUN executes a DOS command from within dB Online. Syntax RUN | ! <dos command> Remarks All parameters must be included in <dos command> above. There must be enough memory to shell another version of COMMAND.COM RUN is only available in the Registered and Pro versions of dB Online. Example To download a file using DSZ.exe with dB Online. file = "data.zip" command = "dsz " + file ? "Please start you zmodem download" RUN &command SAVE Function SAVE stores all or part of the current set of memory variables to a disk file. Syntax SAVE TO <filename> [ALL LIKE | EXCEPT <var name spec>] Remarks The default extension for <filename> is .MEM unless otherwise specified. If the ALL LIKE|EXCEPT option is not used then all current variables are saved to disk. In <var name spec>, a question mark (?) masks a single character and an asterisk (*) masks any number of characters. Example To SAVE all memory variables beginning with 'user' to file.mem SAVE TO file ALL LIKE user* See Also RESTORE, STORE SECURITY() Function The SECURITY() function returns the user's security level. Syntax SECURITY( [ <expN> ]) Returns NUMERIC Remarks SECURITY() will accept an optional numeric expression to allow the value to be changed. This can be done using the new EQUALS command. eg: = SECURITY(23) Valid With exitinfo.bbs, door.sys, dorinfox.def, users.sys, chain.txt, callinfo.bbs See Also PASSWORD() SEEK Function SEEK searches for the first record in the active index of the current database whose key matches a specified expression. Syntax SEEK <expC> | <expD> | <expN> Remarks The expression must have the same data type as the active index key. For character searches, the result of the search depends on the setting of SET EXACT. If SET EXACT is ON the key expression would have to match the full length of the index key. However with SET EXACT OFF a partial string will match the first occurrence in a index key. If the search is successful the FOUND() flag is set to True(.T.). If the search is unsuccessful the record pointer moves to the end of the file and FOUND() is set to False (.F.). Example USE customer INDEX name SET EXACT OFF SEEK "Smi" ? name Smith SET EXACT ON SEEK "Smi" ? FOUND() .F. See Also EOF(), FOUND(), LOCATE, SET DELETED, SET INDEX, SET EXACT, SET ORDER, USE SELECT() Function Returns the currently selected work area Syntax SELECT( [<expN>] ) Remarks If you include <expN>, and it equals 1, then the last available work area is returned. See Also SELECT SELECT Function SELECT chooses a work area from the twenty available work areas. Syntax SELECT <expN> | <alias> Remarks Work areas are <integers> numbered from 1 to 20, or A through J (Alpha aliasing can only access the first 10 work areas). When you start up your dB Online application, the active work area is one. Each work area can contain one open database file and it's associated index and memo files. You can use SELECT to change work areas so that the database in the new work area becomes the active database file. You can also use SELECT by specifying the <alias> of a work area. This <alias> is specified when the database is opened with the USE...ALIAS command. If the ALIAS command is not used then the database filename minus the extension is the default alias name. If you specify 0 for <expN>, then the next available area is used. Each work area maintains its own record pointer and moving between work areas does not affect the position of any record pointers. All work areas operate independently of each other unless related with SET RELATION TO. Fields in the current work are accessed by simply indicating their field name. To access fields from other work areas you can specify fields in other work areas by using the aliasing indicator: alias->field or alias.field Example SELECT a USE customer ? name Smith SELECT 2 USE sales ? a->name Smith ? subtotal 23.45 See Also SET INDEX, USE, SELECT() SERIALNO() Function Returns dB OnlineÆs Serial Number Syntax SERIALNO() Returns CHARACTER Remarks This information is derived from the DBONLINE.KEY file. If this version is shareware, then this will return a blank string. See Also REGISTEREDTO() SET ALTERNATE Function SET ALTERNATE records all output other than that of full-screen commands to a text file. Syntax SET ALTERNATE on | OFF SET ALTERNATE TO [<filename>] Remarks SET ALTERNATE is OFF by default. This command consists of two parts: SET ALTERNATE TO <filename> creates and opens an ALTERNATE file. It overwrites any file with the same name. A .TXT file extension is assumed unless otherwise specified. SET ALTERNATE ON starts recording of text output to the text file. Full screen commands such as @..SAY...GET are not recorded. SET ALTERNATE OFF suspends the recording of output to the file without closing the file. Recording can be restarted with SET ALTERNATE ON. The file is closed with the SET ALTERNATE TO command or the equivalent CLOSE ALTERNATE. Example To flag a file to be downloaded in PCBoard: file = "program.zip" SET ALTERNATE TO pcbstuff.kbd SET ALTERNATE ON SET CONSOLE OFF && To avoid output to screen ?? "FLAG " + file ? SET CONSOLE ON SET ALTERNATE TO &&Closes pcbstuff.kbd See Also CLOSE SET BELL Function SET BELL determines whether a bell is sounded when an invalid data type is entered in an entry field or the end of an input area is reached. Syntax SET BELL ON | off Remarks SET BELL is ON by default See Also @...SAY...GET, SET CONFIRM SET CENTURY Function SET CENTURY allows the input and display of centuries in the year portion of dates. Syntax SET CENTURY on | OFF Remarks SET CENTURY is OFF by default. Date display and entry will only allow for 6 significant digits when SET CENTURY is OFF. Thus all dates entered will default to the twentieth century. However any date calculation that result in non- twentieth century dates will be stored with the correct century. With SET CENTURY ON date display and entry will allow 8 significant digits. Thus century information can be fully specified. Example ? DATE() 10/21/93 SET CENTURY ON ? DATE() 10/21/1993 See Also CTOD(), DATE(), DTOC(), YEAR() SET COLOR Function SET COLOR allows custom color selection for both standard and enhanced output. Syntax SET COLOR TO [<standard>[,<enhanced>]] Remarks SET COLOR is only operational in ANSI terminal operation. The <standard> colors are used for normal text output and the <enhanced> colors are used for @...GET input fields and error message outputs. The default colors upon startup are: Standard: White on Black Enhanced: Black on White SET COLOR TO R will re-select the default colors. The <standard> and <enhanced> colors are specified as follows: Color Letter Code Intense Color Letter Code Black N or blank Dark Gray N+ Blue B Light Blue B+ Red R Light Red R+ Green G Light Green G+ Cyan BG Light Cyan BG+ Magenta RB Light Magenta RB+ Brown GR Yellow GR+ Light Gray RGB or W White RGB+ or W+ Blank X Flashing * Foreground and background colors are separated by a slash (/). The intense colors are only available in the foreground. If an asterisk (*) is present then the output will be flashing. The Blank (X) color specifier will output blank characters. This is useful for password entry. Example The following SET COLOR commands are explained: * Standard: Yellow on a Red background. Enhanced: White on a Red background. SET COLOR TO GR+/R,W/R * Standard: White on a Blue background. Enhanced: Black on a Cyan background. SET COLOR TO W+/B,N/BG See Also ISCOLOR(), SET INTENSITY SET COMPATIBLE Function SET COMPATIBLE alters how some commands function. Syntax SET COMPATIBLE TO [ FOXPLUS | DB4 | DB3PLUS | ON | OFF ] Remarks FOXPLUS is the default. ON is the same as FOXPLUS and OFF is the same as DB4. SET CONFIRM Function SET CONFIRM determines whether the cursor moves automatically to the next entry field when the current field is full. This command affects only full screen functions. Syntax SET CONFIRM on | OFF Remarks SET CONFIRM is OFF by default. This causes the cursor to automatically advance from one field to the next in a full screen @...GET READ command. SET CONFIRM ON causes the cursor to remain in the field until the R key is pressed. See Also @...SAY...GET, SET BELL SET CONSOLE Function SET CONSOLE determines whether output is sent to the local and remote terminals. Syntax SET CONSOLE ON | off Remarks SET CONSOLE is ON by default. This causes all output to be sent to the local and remote terminals. SET CONSOLE OFF does not send output to either local or remote terminals. This is useful for writing files to disk with SET ALTERNATE. See Also SET ALTERNATE SET CURRENCY Function Defines the currency symbol and position in the display of numeric expressions Syntax SET CURRENCY TO [<expC>] or SET CURRENCY LEFT | RIGHT Remarks If <expC> is omited, the dollar sign ($) will be used. SET DATE Function Specifies the format for the display of date expressions Syntax SET DATE [TO] AMERICAN | ANSI | BRITSH | FRENCH | GERMAN | ITALIAN | JAPAN | USA | MDY | DMY | YMD Remarks The following is a table of formats for the above settings: Setting Format AMERICAN mm/dd/yy ANSI yy.mm.dd BRITSH / FRENCH dd/mm/yy GERMAN dd.mm.yy ITALIAN dd-mm-yy JAPAN yy/mm/dd USA mm-dd-yy MDY mm/dd/yy DMY dd/mm/yy YMD yy/mm/dd See Also SET MARK SET DECIMALS Function SET DECIMALS determines the minimum number of decimals to display for the results of numeric calculations. Syntax SET DECIMALS TO <expN> Remarks SET DECIMALS is set to 2 by default. SET DECIMALS applies to division, exponents, EXP(), LOG(), SQRT() and VAL() functions. If SET FIXED is ON, SET DECIMALS applies to all numeric output. Example SET DECIMALS TO 2 ? 1/4 0.25 ? 1/4.000 0.250 ? SQRT(3.452) 1.86 SET DECIMALS TO 5 ? 1/4 0.25000 See Also SET FIXED SET DEFAULT Function SET DEFAULT determines the default drive to where all operations take place and files are stored unless otherwise specified. Syntax SET DEFAULT TO <drive> Remarks SET DEFAULT is set to the drive that dB Online was started up from. SET DEFAULT does not check if the given disk drive exists and it does not change the default drive when dB Online exits. Example To set the default drive to D: SET DEFAULT TO d See Also SET PATH SET DELETED Function SET DELETED determines whether records marked for deletion are included in the execution of dB Online commands. Syntax SET DELETED on | OFF Function SET DELETED is OFF by default. With SET DELETED ON, most commands will not recognize records marked for delete as part of the database. Commands like LOCATE or LIST will not display deleted records. Commands that specify a record number using RECORD <n> or GO|GOTO <n> will included deleted records. See Also DELETE, DELETED(), RECALL SET DELIMITERS Function SET DELIMITERS determines how fields are indicated in full-screen editing mode. Syntax SET DELIMITERS on | OFF SET DELIMITERS TO [<expC> | DEFAULT] Remarks SET DELIMITERS is OFF by default. This causes entry fields not to be enclosed by delimiter characters. If SET INTENSITY is ON, entry fields are display in enhanced colors. SET DELIMITERS ON will enclose entry fields by the default delimiters of colons (:). SET DELIMITERS TO <expC> changes the default delimiter characters. If a single character is specified then it is used to delimit both the beginning and end of the entry field. If two characters are specified then the first marks the beginning and the second marks the end. Any extra characters are ignored. SET DELIMITERS TO DEFAULT returns the delimiters to colons (:) See Also @...SAY...GET, SET INTENSITY SET ESCAPE Function SET ESCAPE determines whether pressing E terminates program execution. Syntax SET ESCAPE ON | off Remarks SET ESCAPE is ON by default. This causes the dB Online program to terminate when the user presses the E key. Escape key trapping with ON ESCAPE is only available with SET ESCAPE ON. With SET ESCAPE OFF the E key does not terminate program execution. The keypress may be determined like any other keypress with the INKEY() function. See Also INKEY(), ON ESCAPE, READKEY() SET EXACT Function SET EXACT determines whether a comparison between two character strings requires an exact match. Syntax SET EXACT on | OFF Remarks SET EXACT is OFF by default. This causes character string comparisons to be True (.T.) if the strings are identical up to the length of the second string. With SET EXACT ON the character strings must be exactly the same before a True (.T.) is returned. SET EXACT also applies to the SEEK command with character index keys. Example SET EXACT OFF ? "abc" = "abcdef" .F. ? "abcdef" = "abc" .T. SET EXACT ON ? "abcdef" = "abc" .F. See Also LOCATE, SEEK, = SET EXCLUSIVE Function SET EXCLUSIVE allows the shared use of database file on a multi-user system. Syntax SET EXCLUSIVE ON | off Remarks SET EXCLUSIVE is ON by default. This means that all data files are opened in exclusive mode. Any other user attempting to open the will receive an error. SET EXCLUSIVE OFF enables multi-user access to the database files. dB Online will provide file and record locking for database files in a method native to your DataBase Management System. See Also FLOCK(), LOCK(), RLOCK(), SET LOCK, SET REPROCESS, UNLOCK, USE SET FILTER Function SET FILTER allows only records that meet a specified condition to be displayed. Syntax SET FILTER TO [<expL>] Remarks All commands that access database records can be used with the SET FILTER TO <expL> condition. SET FILTER only applies to the current database work area. Thus a different condition may be set for each work area. All records for which <expL> is True (.T.) are available for processing and any for which <expL> is False (.F.) are ignored. Filter conditions are not valid until the record pointer is moved after the SET FILTER TO command is executed. You must move your record pointer with GOTO TOP or SKIP to ensure the filter condition is valid. SET FILTER TO R turns of a filter for the current work area. All records are then available for processing. Example To count the number of customers in New York: USE customer SET FILTER TO state = "NY" COUNT TO number To total all sales in October 1993: USE sales SET FILTER TO MONTH(saledate) = 10 .AND. YEAR(saledate) = 1993 SUM price * quantity TO total See Also SET DELETED SET FIXED Function SET FIXED determines whether a fixed number of decimal places are displayed for all numeric output. Syntax SET FIXED on | OFF Remarks SET FIXED is OFF by default. This causes the number of decimal places for numeric output to be as explained in the SET DECIMALS command. If SET FIXED is ON all numeric output will have the number of decimal places identified by SET DECIMALS TO. See Also SET DECIMALS SET INDEX Function SET INDEX opens specified index files in the current work area. Syntax SET INDEX TO [<filename> [,<filename>]...] Remarks The default file extension is determined by which database file compatibility you have chosen with dB Online. For dBASE III+ file compatibility the default extension is .NDX, for Clipper: .NTX, for dBASE IV: .MDX, and for FoxPro: .CDX SET INDEX closes all indexes in the current work area before opening the ones specified in the file list. SET INDEX TO R will close all index file in the current work area and is equivalent to CLOSE INDEX. The first tag of the first index file specified becomes the master index for the current database (Tags do not apply to dBASE III+ and Clipper file compatibility). The master index determines the record order as well as the search key for the SEEK command. The record pointer is positioned at the first logical record of the index key. All open index files are updated when changes are made to a database file. See Also SET ORDER, USE SET INTENSITY Function SET INTENSITY determines whether the enhanced screen colors are used for full screen data entry fields. Syntax SET INTENSITY ON | off Remarks SET INTENSITY is ON by default. This causes all full screen data entry fields (@...GETs) to be displayed in the enhanced screen color as determined by SET COLOR TO. All other text output is displayed in the standard screen color. If SET INTENSITY is OFF, then the standard screen color is used for all data output. See Also @...SAY...GET, SET COLOR, SET DELIMITERS SET LOCK Function SET LOCK allows the current record of a database file to be locked before reading. Syntax SET LOCK on | OFF Remarks SET LOCK is OFF by default. This mean that records are not locked as they are read into the record buffer. This allows users to view the same record simultaneously. With SET LOCK ON, any record is automaticallly locked before reading. This ensures that there can be no changed to the data once it is read. While this greatly simplifies creating multi-user applications. It increases the chances that another user will have to wait for a record if he only wants to view it. See Also FLOCK(), LOCK(), RLOCK(), SET EXCLUSIVE, SET REPROCESS, UNLOCK SET MARK Function Specifies the delimeter used to display dates Syntax SET MARK TO [<expC>] Remarks SET MARK TO specifies the character that separates the month, day, and year in displayed dates. If you omit <expC>, then the default forward slash (/) will be used. Example ? DATE() 08/01/94 SET MARK TO æ-Æ ? DATE() 08-01-94 See Also SET DATE SET MEMOWIDTH Function SET MEMOWIDTH determines the width for memo field output. Syntax SET MEMOWIDTH TO <expN> Remarks SET MEMOWIDTH TO has a default value of 50 by default. The minimum value is 8 characters. All memo output using the ?|?? or LIST|DISPLAY commands will be word wrapped within a column width defined by SET MEMOWIDTH TO. SET ORDER Function SET ORDER sets up an open index file as the master index. Syntax SET ORDER TO [<expN> | TAG <tag>] Remarks SET ORDER TO changes the master index from the available index tags. If SET ORDER TO <expN> is used then the master index becomes the tag corresponding to the value of <expN>. For dBASE III+ and Clipper file compatibility this number corresponds to the index file on the USE...INDEX or SET INDEX TO list. For dBASE IV and FoxPro compatibility it corresponds to the all the tags of the index file list. If SET ORDER TO TAG <tag> is used then a search is made for the first tag whose name matches <tag>. The tag names for dBASEIII and Clipper index files correspond to the index file names without the filename extension. SET ORDER TO 0 returns the database to natural record ordering. See Also CDX(), MDX(), NDX(), SET INDEX SET PATH Function SET PATH determines the directories dB Online will search to find files not in the current directory. Syntax SET PATH TO [<path list>] Remarks By default dB Online only searches the current directory. If a <path list> is specified dB Online will search for a file in the current directory first and then in the directories specified. The <path list> consists of a list of paths separated by commas (,) or semi-colons (;). SET PATH applies only to commands that search for existing files. If you create a file it will be saved in the current directory unless the you specify the path with the filename. Example The following program will search in two directories if a file cannot be found in the default directory. SET PATH TO c:\dbonline\databases,c:\foxpro\files use customer See Also FILE(), SET DEFAULT SET POINT Function Specifies the decimal point character used in the display of numeric expressions Syntax SET POINT TO [<expC>] Remarks If you omit <expC>, the period (.) will be used. Example ? 1.25 1.25 SET POINT TO æ,Æ ? 1.25 1,25 See Also SET DECIMAL, SET FIXED, SET SEPARATOR SET PROCEDURE Function SET PROCEDURE is used to include procedure files while a source file is being compiled. Syntax SET PROCEDURE TO [<filename>] Remarks SET PROCEDURE TO specifies filenames to be included with the current main file. All source files are compiled and a single .DBX file is created. Thus it is not necessary to CLOSE PROCEDURE files. The SET PROCEDURE TO command is not present at runtime. See the Compiling section for more details on SET PROCEDURE. See Also DO, PARAMETERS SET RELATION Function SET RELATION links two open database files according to a key expression that is common to both files. Syntax SET RELATION TO [<key expr> | <expN> INTO <alias>] Remarks SET RELATION TO links the active database file to an open database file in another work area. The INTO file is identified by its alias. Only one relation can be made from each work area. The active database file is called the parent file, and the INTO file is called the child file. If a <key expression> is used then the child database must be indexed. The <key expression> is evaluated and then a seek is performed on the child work area. The child database is position to the first record that matches the key expression. When the <expN> is used, and the child database is not indexed, then the child database is positioned to the record number given by <expN>. If no record is found then the child database is positioned to the end of file and EOF() will return True (.T.). As the parent and child files must be in separate work areas, SET RELATION is only available in the Pro version of dB Online. Example If the invoice database has a field inv_no which matches the same field in sales we can set the following relation: SELECT a USE invoice.dbf USE sales INDEX inv_no.ndx IN 2 && open sales in work area b SELECT a SET RELATION TO inv_no INTO b LIST inv_no, customer, b->product, b->sales && output related fieldS See Also SET INDEX, SET ORDER SET REPROCESS Function SET REPROCESS determines how may times dB Online will attempt to access a locked record before returning an error. Syntax SET REPROCESS TO <expN> Remarks SET REPROCESS is set to -1 by default. This means that dB Online will attempt to open the locked data approximately every second indefinately. Once the data is available, then dB Online will proceed with program execution. If SET REPROCESS is set to any non-negative value, dB Online will attempt to open the locked data <expN> times. These open attempts will occur at approximately one second intervals. If SET REPROCESS is set to 0 then dB Online will immidiately return a locking error. See Also FLOCK() , LOCK(), RLOCK(), SET LOCK, SET EXCLUSIVE, UNLOCK SET SEPARATOR Function Dspecifies the character that separates each group of three digits to the left of the decimal point Syntax SET SEPARATOR TO [<expC>] Remarks If you omit <expC>, the comma (,) will be used. Example ? 12345 12,345 SET SEPARATOR TO æ.Æ ? 12345 12.345 See Also SET MARK SET SPACE Function Determines whether or not a space is displayed between fields or expressions when you use the ? or ?? statement. Syntax SET SPACE ON | off Example SET SPACE OFF ? ôJohnö,öSmithö JohnSmith SET SPACE ON ? ôJohnö,öSmithö John Smith See Also ? | ?? SKIP Function SKIP moves the record pointer forward or backward in the current database file. Syntax SKIP [<expN>] Remarks SKIP uses the natural record order when moving the record pointer, unless there is an active index file in use, then SKIP follows the index file order. SKIP moves the record pointer by the value of <expN>. Both positive and negative values of <expN> are allowed with negative values moving the record pointer backwards. If <expN> is omitted, then the record pointer is moved a single record forward. If SKIP is used with a positive value when the record pointer is at the last record in the database, then the EOF() condition will be True (.T.). If SKIP is used with a negative value when the record pointer is at the first record in the database, then the BOF() condition will be True (.T.). Example USE customer SKIP ? RECNO() 2 SKIP 15 ? RECNO() 17 SKIP -5 ? RECNO() 12 See Also BOF(), EOF(), GOTO SND...() Function Transfers a file via the modem. Syntax SNDASCII ( <expC> [ , <expN1> ] ) SNDKERMIT ( <expC> [ , <expN1> ] ) SNDYMODEM ( <expC> [ , <expN1> [ , <expN2> ] ] ) SNDXMODEM ( <expC> [ , <expN1> [ , <expN2> ] ] ) SNDZMODEM ( <expC> [ , <expN1> ] ) Returns NUMERIC Remarks All of the above functions return the bytes transfered. <expC> is the path and filename of the file to transfer. For SNDYMODEM() and SNDZMODEM(), you may use multiple files separated by spaces. <expN1> is the optional communications handle returned by COPEN(). By default the currently active communications port is used. For SNDYMODEM(), <expN2> may be 1 to represent the use of the Ymodem-G protocol. For SNDXMODEM(), <expN2> is as follows: <expN2> Function 0 Use Xmodem-CRC protocol (default) 1 Use Xmodem-1k protocol 2 Use Xmodem-G protocol See Also RCV...(), COPEN(), CCLOSE() SPACE() Function The SPACE() function generates a character string containing a specified number of spaces. Syntax SPACE(<expN>) Returns CHARACTER Remarks The range of <expN> is from 0 to 254 Example ? '*' + SPACE(10) + '*' * * See Also REPLICATE() SQRT() Function The SQRT() function returns the square root of a specified positive numeric argument. Syntax SQRT(<expN>) Returns NUMERIC Example ? SQRT(4) 2 ? SQRT(2) 1.4 ? SQRT(2.0000) 1.414 STOPBITS() Function The STOPBITS() function identifies the number of stopbits of the current comm port settings. Syntax STOPBITS() Returns NUMERIC Valid With dorinfox.def Remarks If a valid BBS drop file is not included then STOPBITS returns a default value of one. See Also DATABITS(), PARITY() STORE Function STORE creates and assigns values to one or more memory variables. Syntax STORE <expr> TO <var list> or <var> = <expr> Remarks The value of <expr> is assigned to all the variables in <var list> when using the STORE command. With the alternate syntax, only a single variable may be assigned at a time. You can not assign values to fields using the STORE command. You must use the REPLACE command. Example STORE 0 TO a,b,c && initialize a, b, c to zero name = "Smith" && STORES 'Smith' to variable name See Also PRIVATE, PUBLIC STR() Function The STR() function converts a number into a character string Syntax STR(<expN1> [,<expN2>] [ ,<expN3>]) Returns CHARACTER Remarks Returns a character representation of <expN1>. The total length of the string is specified by <expN2>. The number of decimals in the string is specified by <expN3>. If <expN2> is not specified the string length is 10. If <expN3> is not specified the number is truncated to an integer. The length includes the decimal point, minus sign and any numbers. If the number specified is too large to fit into the length, dB Online returns asterisks in the string. Example ? STR(10.54,5,2) 10.54 ? STR(10.54) 10 ? STR(1459,3,0) *** See Also SUBSTR(), VAL() STUFF() Function The STUFF() function replaces a portion of a character string with another character string. Syntax STUFF(<expC1>,<expN1>,<expN2>,<expC2>) Returns CHARACTER Remarks Character expression <expC1> is the string to be altered. Character expression <expC2> is to be inserted into <expC1>. The insertion takes place at the position specified by <expN1>. At this position <expN2> characters are removed from <expC1> and then <expC2> is inserted. Example ? STUFF('abc',2,1,'xyz') axyzc ? STUFF('abc',2,1,'') ac ? STUFF('abc',2,0,'xyz') axyzbc See Also LEFT(), RIGHT(), SUBSTR() SUBSTR() Function The SUBSTR() function extracts a specified number of characters from a character string. Syntax SUBSTR(<expC> , <expN1> [,<expN2>]) Returns CHARACTER Remarks Returns the next <expN2> characters of <expC> beginning at the <expN1> position. If <expN2> is not specified, dB Online returns the remainder of <expC> Example ? SUBSTR("Press any key",7,3) any See Also AT(), LEFT(), RIGHT(), STR(), STUFF() SUM Function SUM calculates the total of numeric expressions in the active database file. Syntax SUM [<scope>] <expr list> TO <var list> [WHILE <expL1>] [FOR <expL2>] Remarks All records in the current database are totaled unless specified by the <scope>, WHILE, or FOR clauses. The <expr list> items must correspond to the memory variables in <var list>. Example To output the total sales by John Smith: USE sales SUM quantity * price TO total FOR salesman = "JS" ? total See Also AVERAGE, COUNT TAG() Function The TAG() function returns the TAG names in the currently selected database. Syntax TAG(<expN> [,<expN1> | <alias>]) Returns CHARACTER Remarks Returns the name of an index file (.ndx, .ntx) or a tag name (.cdx, .mdx) of the currently selected database. In dBASE III+ and Clipper file formats, <expN1> identifies the index file in the position as specified in the SET INDEX TO, or USE INDEX command. In dBASE IV and FoxPro file formats, <expN1> identifies the tag number of all opened multiple index files. The second parameter is used to identify tags in other work areas. Example To identify the second tag of cust.mdx USE cust omer.dbf INDEX cust.mdx ? TAG(2) PHONE See Also CDX(), DBF(), MDX(), NDX(), SET INDEX, SET ORDER, USE TEXT Function TEXT is used to output blocks of text to the screen. Syntax TEXT <text> <text> ... ENDTEXT Remarks The text is output exactly as it appears in the source file. The first text line that begins with ENDTEXT will terminate the output text. Example To output a short menu to the screen. CLEAR TEXT [S] Search [L] List [Q] Quit [?] Help Please enter your selection: ENDTEXT See Also ?|??, @...SAY, DISPLAY, LIST TIME() Function The TIME() function return the current system time. Syntax TIME() Returns CHARACTER Remarks Returns the current system time in the format hh:mm:ss Example ? TIME() 12:36:55 See Also DATE() TIMELEFT() Function The TIMELEFT() function returns the user's time left in minutes. Syntax TIMELEFT( [ <expN>]) Returns NUMERIC Remarks A timeout occurs when dB Online has been running for the number of minutes initially passed by the BBS drop files. If no BBS drop files are specified (i.e. Local or Stand Alone operation), the initial value for TIMELEFT() is 999 minutes. TIMELEFT() will accept an optional numeric expression to allow the value to be changed. This can be done using the new EQUALS command. eg: = TIMELEFT(23) Valid With pcboard.sys, door.sys, dorinfox.def, chain.txt, callinfo.bbs See Also TIME() TRANSFORM() Function The TRANSFORM() function allows PICTURE formatting of data without using the @...SAY command. Syntax TRANSORM(<expr>,<expC>) Returns CHARACTER Remarks Returns the data in <expr> in the format specified by the PICTURE format <expC>. <expr> can be any of the four data types: NUMERIC, CHARACTER, LOGICAL, DATE. For information about PICTURE formats, refer to the @ command. Example ? TRANSFORM('john','!XXX') John ? TRANSFORM(4123.5,'999,999.99') 4,123.50 See Also @...SAY...GET TRIM() Function The TRIM() function is identical to the RTRIM() function. Please refer to RTRIM() in this section. Syntax TRIM(<expC>) Returns CHARACTER See Also LTRIM(), RTRIM() TYPE Function Displays a file. Syntax TYPE <expc> Remarks TYPE will generate a "-More- [C]ontinue, [S]top, [N]onstop ?" prompt when displaying large file listings. The number of lines displayed is determined by the PAGELEN() variable given by the BBS drop files. Example TYPE menu.ans UNLOCK Function UNLOCK removes locks previously placed on a datafile using FLOCK(), LOCK(), or RLOCK(). Syntax UNLOCK Remarks UNLOCK will unlock the file in the current work area. UNLOCK allows other users to access all the information in a database file. It should be used after the commands that required file or record locking are completed. Example USE customer.dbf IF FLOCK() && if lock is successful PACK UNLOCK && unlock file after PACKing. ELSE ? "Unable to lock file" QUIT ENDIF See Also FLOCK(), LOCK(), RLOCK(), SET EXCLUSIVE, SET LOCK, SET REPROCESS UPPER() Function The UPPER() function converts a character expression to upper case. Syntax UPPER(<expC>) Returns CHARACTER: Remarks Returns a string in which all lowercase characters in <expC> have been converted to uppercase. Example ? UPPER("Hello") HELLO See Also LOWER() USE Function USE opens an existing database file and any specified index files. If the database includes memo fields, then the corresponding memo file is opened. Syntax USE [<filename>] [INDEX <index file list>] [ALIAS <alias>] [IN <expN>] Remarks Unless otherwise specified dB Online assumes a .DBF extension for the database file while the default index file extension is dependent on the file compatibility in use. All index files in the <index file list> are opened with the database file. In dBASE IV and FoxPro file compatibility if there is a production index file associated with the database file it is opened automatically. USE R will close the database and index files in the currently selected work area. If the ALIAS option is omitted, then dB Online will use the database filename minus the extension for the ALIAS. The files are opened in the currently selected work area. If the IN command is used, then dB Online switches to the specified work area before attempting to open any files. If you specify 0 for <expN>, then the next available area is used. Example SELECT 1 USE customer && open customer.dbf in work area 1 USE sales INDEX part_no IN 2 && open sales in work area 2 SELECT customer && select customer.dbf using alias See Also CLOSE, SELECT, SET EXCLUSIVE, SET INDEX USERNAME() Function The USERNAME() function returns the user's full name. Syntax USERNAME() Returns CHARACTER Remarks The USERNAME() function returns the name as the BBS stores it. This is usually in full capitals. Valid With pcboard.sys, exitinfo.bbs, door.sys, dorinfo1.def, users.sys, chain.txt, callinfo.bbs See Also FIRSTNAME() VAL() Function The VAL() function converts a character representation of a number into a numeric expression. Syntax VAL(<expC>) Returns NUMERIC Remarks Returns the value of <expC>. Any leading blanks are ignored in <expC>. Once numeric digits are found, VAL() proceeds left to right until a non numeric character is encountered. If <expC> is non- numeric, VAL() returns zero. The decimal portion of the returned number is determined by SET DECIMALS. Example ? VAL(" 555") 555.00 ? VAL("Hello") 0.00 See Also SET DECIMALS, STR() VERSION() Function The VERSION() function returns the version number of dB Online in use. Syntax VERSION() Returns CHARACTER Example ?VERSION() dB Online 1.20 See Also DISKSPACE(), GETENV(), OS() VOICEPHONE() Function The VOICEPHONE() function returns the user's voice phone number. Syntax VOICEPHONE() Returns CHARACTER Valid With exitinfo.bbs, door.sys, users.sys, callinfo.bbs See Also DATAPHONE() WAIT Function WAIT pauses until a single key in input on either the remote or local terminals. Syntax WAIT [<expC>] [TO <var>] [TIMEOUT x] Remarks WAIT displays the optional prompt <expC> before waiting for a user keypress. If no prompt is specified then "Press any key to continue..." is displayed. If the optional <var> is specified then the character input is placed into <var>. If R or other non-printable character is entered, a null string is assigned to <var>. If the TIMEOUT keyword is used, then the prompt will timeout in x seconds. Example WAIT 'Do you wish to continue (Y/N)' TO answer IF UPPER(answer) = 'N' QUIT ENDIF See Also ON ESCAPE YEAR() Function The YEAR() function returns a number representing the year from a date expression. Syntax YEAR(<expD>) Returns NUMERIC Example Assume the system date is 10/21/93 ? YEAR(DATE()) 1993 See Also DATE(), DAY(), MONTH() ZAP Function Deleted and packes all records in the current database. Syntax ZAP Remarks ZAP is equivalent to DELETE ALL followed by a PACK command, except it executes faster. Appendices Appendix 1: Errorlevels Program Execution Errors The following values are returned to the DOS errorlevel upon termination of dB Online. These errors below 100 are returned when execution is halted during .PRG execution. The error message will appear on the dB Online exit screen. Errorlevel Error Description 0 Normal The .PRG application completed execution Termination and terminated correctly. 1 Runtime Error A runtime error occurred in the .PRG application. Before program termination the source .PRG filename and line number of the error is indicated to assist the debugging process. Runtime errors can be trapped with the ON ERROR command. 10 Auto Timeout The user time provided to dB Online from the BBS info functions has expired during program execution. dB Online terminates and returns control to the calling application. 11 Lost Carrier The carrier was lost during program execution. dB Online terminates and returns control to the calling application. 12 Terminated The user pressed the E key when SET Escape ESCAPE was set to ON. This causes dB Online to terminate and return control to the calling application. 13 Unexpected An internal error has occurred within dB Runtime Online. Your .DBX file may be corrupt. Re-compile the source .PRG file and then execute dB Online. If this does not solve the problem please contact Merlin Systems Inc. 14 Run Stack An attempt was made to nest procedure Overflow calls too deep. dB Online is able to nest procedure call up to 20 levels deep. If parameters are passed with procedure calls then this limit is reduced. If this error persists please contact Merlin Systems Inc. 15 Run Stack An internal error has occurred within dB Underflow Online. Your .DBX file may be corrupt. Re-compile the source .PRG file and then execute dB Online. If this does not solve the problem please contact Merlin Systems Inc. 16 Evaluation An attempt was made to evaluate an Stack Overflow expression too complex for the dB Online evaluator. This can be fixed by splitting the complex expression onto two command lines. Please contact Merlin System Inc. if you receive this error. 17 Evaluation An internal error has occurred within dB Stack Online. Your .DBX file may be corrupt. Underflow Re-compile the source .PRG file and then execute dB Online. If this does not solve the problem please contact Merlin Systems Inc. Start Up Errors The following values are returned to the DOS errorlevel upon termination of dB Online. These errors above 100 are returned when execution is halted during setup prior to .DBX execution. This error message will appear on the DOS screen upon exit. Errorlevel Error Description 100 Syntax dB Online was executed without any Explanation parameters. This displays the command line syntax information. 101 Cannot Open dB Online could not open the source .DBX DBX file. Ensure that your source .PRG file is compiled and the resultant .DBX file's path is fully specified in the command line. 102 Not a Valid The .DBX file is not a valid dB Online file. DBX Ensure that your source .PRG file is compiled with the current version of COMPILE.EXE 103 CanÆt Find USERS.SYS File 104 Cannot Find PCBOARD.SYS File 105 Cannot Find EXITINFO.BBS File 106 Cannot Find DORINFO1.DEF File 107 Cannot Find DOOR.SYS File 108 Cannot Find CALLINFO.BBS File 109 Invalid Command Line Argument 110 Corrupted The DBONLINE.KEY file has been DBONLINE.KEY File corrupted. Copy your backup DBONLINE.KEY file to your DBONLINE directory. If this does not solve the problem please contact Merlin Systems. 111 Expired Beta KEY The DBONLINE.KEY file that was issued File to the beta testers has expired. 112 Unable to Open COMM dB Online was unable to open the comm Port port that was specified in one of the BBS information files or in the PORT: command line parameter. 113 Port Information Not There was no port information Specified specified in any of the BBS information files and the PORT: command line parameter was not found. This error only occurs with the -SA option for Stand Alone operation. 114 Stand Alone The sysop on the host pressed E on Interrupt the call waiting screen of the Stand Alone option. This causes dB Online to terminate and return control back to the calling program. 115 Stand Alone An attempt was made to execute dB Unavailable Online with the Stand Alone option without having the PRO version of dB Online. Please contact your distributor if you wish to upgrade. Appendix 2: Compiler Messages Error Messages The following is a list of error messages displayed by the compiler o Alias name required. o Character literal required. o Exponent too large. o Field identifier required. o Illegal number of arguments. o Misplaced parameters list. o Misplaced set procedure command. o Missing endcase. o Missing enddo. o Missing endif. o Not a function. o On Error only supports procedure calls. o Picture clause expected. o Procedure name expected. o Procedure redeclaration. o Right brace expected. o Source line too long. o Syntax Error. o Too Many errors. o Unable to open source file. o Unexpected command. o Unexpected end of line. o Unmatched case statement. o Unmatched else statement. o Unmatched endcase statement. o Unmatched enddo statement. o Unmatched endif statement. o Unmatched number of parameters. o Unmatched otherwise statement. o Unmatched variable list. o Unrecognized command verb. o Variable identifier expected. o Work area out of range. Warning Messages The following is a list of warning messages displayed by the compiler. These indicate xBase commands that are not valid in the dB Online environment and will not affect program execution. o CLOSE PROCEDURE ignored o SET CATALOG not supported o SET DATE not supported o SET HEADING not supported o SET HELP not supported o SET HISTORY not supported o SET ODOMETER not supported o SET PRINTER not implemented o SET PROCEDURE TO ignored o SET SAFETY not supported o SET SCOREBOARD not supported o SET STATUS not supported o SET TALK not supported o TO PRINT not implemented Appendix 3: Runtime Errors Below is a list of runtime error message for dB Online. The number in the parenthesis is the value returned by the ERROR() function in error handling routines. ERROR() Error 24 ALIAS name already in use 13 ALIAS not found 38 Beginning of file encountered 17 Cannot select requested database 111 Cannot write to read-only file 42 CONTINUE without LOCATE 44 Cyclic relation 9 Data type mismatch 26 Database is not indexed 41 Memo file cannot be opened 4 End of file encountered 77 Execution error on +: Concatenated string too large 76 Execution error on -: Concatenated string too large 78 Execution error on ^ or **: Negative base) fractional exponent 57 Execution error on CHR(): Out of range 58 Execution error on LOG(): Zero or negative 87 Execution error on NDX(): Invalid index number 88 Execution error on REPLICATE(): String too large 60 Execution error on SPACE(): Negative 59 Execution error on SPACE(): Too large 61 Execution error on SQRT(): Negative 79 Execution error on STORE: String too large 63 Execution error on STR(): Out of range 102 Execution error on STUFF(): String too large 62 Execution error on SUBSTR(): Start point out of range 7 File already exists 1 File does not exist 3 File is already open 108 File is in use by another 46 Illegal value 19 Index file does not match database 106 Invalid index number 107 Invalid operator 123 Invalid printer port 55 Memory Variable file is invalid 52 No database in use 45 Not a character expression 15 Not a dBASE database 37 Not a Logical expression 27 Not a numeric expression 39 Numeric overflow (data was lost) 90 Operation with Logical field invalid 34 Operation with Memo field invalid 30 Position is off the screen 126 Printer is either not connected or turned off 109 Record is in use by another 20 Record is not in index 5 Record is out of range 142 Relation record is in use by others 209 TAG not found 28 Too many indices 92 Unable to load COMMAND.COM 0 Unable to open file 12 Variable not found Appendix 4: Full Screen Entry Keys The following keys are used in full-screen operations. Keys apply to both data entry screens and the memo editor. Key Alternative Function Up Moves the cursor up one line or field Down Moves the cursor down one line or field Left Moves the cursor one space to the left. Right Moves the cursor one space to the right. ^Left Moves the cursor a word left in the memo editor ^right Moves the cursor a word right in the memo editor <- Erases the character to the left of the cursor Del Erases the character at the current cursor position. End Moves the cursor to the end of the line or field ^End ^W Exits and saves changes to memo or entry screens. Enter Moves the cursor to the next field or line. Esc ^Q Exits without saving changes. Home Moves the cursor to the start of the line or field Ins Toggles insert mode. PgUp Moves the cursor up one page. PgDn Moves the cursor down one page. ^PgDn Enter full screen memo editor. ^PgUp ^W Exit memo screen editor. Tab Completes field entry and moves to next field. ^Y Erases line in memo editor.