Microsoft Programmer's Library 1.3

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

/ Microsoft Programmer's Library 1.3 / Microsoft_Programmers_Library.7z / MPL / basic / qb45lang.txt < prev next >

Wrap

Text File | 2013-11-08 | 812.4 KB | 23,403 lines

Microsoft QuickBASIC: Language Reference ════════════════════════════════════════════════════════════════════════════ Microsoft(R) QuickBASIC BASIC: Language Reference For IBM(R) Personal Computers and Compatibles ════════════════════════════════════════════════════════════════════════════ Information in this document is subject to change without notice and does not represent a commitment on the part of Microsoft Corporation. The software described in this document is furnished under a license agreement or nondisclosure agreement. The software may be used or copied only in accordance with the terms of the agreement. It is against the law to copy the software on any medium except as specifically allowed in the license or nondisclosure agreement. No part of this manual may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, for any purpose without the express written permission of Microsoft. (C)Copyright Microsoft Corporation 1987, 1988. All rights reserved. Simultaneously published in the U.S. and Canada. Printed and bound in the United States of America. Microsoft, MS, MS-DOS, CodeView, and XENIX are registered trademarks of Microsoft Corporation. AT&T is a registered trademark of American Telephone and Telegraph Company. Hercules is a registered trademark and InColor is a trademark of Hercules Computer Technology. IBM and PC/AT are registered trademarks and PC/XT is a trademark of International Business Machines Corporation. Intel is a registered trademark of Intel Corporation. Olivetti is a registered trademark of Ing. C. Olivetti. Document No. 410700018-450-R00-1188 ──────────────────────────────────────────────────────────────────────────── Table of Contents Introduction Document Conventions Reference Page Format PART 1 LANGUAGE FUNDAMENTALS Chapter 1 Language Elements 1.1 Character Set 1.2 The BASIC Program Line 1.2.1 Using Line Identifiers 1.2.2 BASIC Statements 1.2.3 BASIC Line Length Chapter 2 Data Types 2.1 Data Types 2.1.1 Elementary Data Types──String 2.1.2 Elementary Data Types──Numeric 2.1.2.1 Integer Numbers 2.1.2.2 Floating-Point Numbers 2.1.3 User-Defined Data Types 2.2 Constants 2.2.1 Literal Constants 2.2.2 Symbolic Constants 2.3 Variables 2.3.1 Variable Names 2.3.2 Declaring Variable Types 2.3.2.1 Type-Declaration Suffix 2.3.2.2 AS Declaration Statements 2.3.2.3 DEFtype Declaration Statements 2.3.2.4 Declaring Array Variables 2.3.3 Variable Storage Allocation 2.4 Scope of Variables and Constants 2.4.1 Global Variables and Constants 2.4.2 Local Variables and Constants 2.4.3 Sharing Variables 2.4.4 DEF FN Functions 2.4.5 Summary of Scope Rules 2.5 Static and Dynamic Arrays 2.6 Automatic and Static Variables 2.7 Type Conversion Chapter 3 Expressions and Operators 3.1 Expressions and Operators Defined 3.2 Hierarchy of Operations 3.3 Arithmetic Operators 3.3.1 Integer Division 3.3.2 Modulo Arithmetic 3.3.3 Overflow and Division by Zero 3.4 Relational Operators 3.5 Logical Operators 3.6 Functional Operators 3.7 String Operators Chapter 4 Programs and Modules 4.1 Modules 4.2 Procedures 4.2.1 FUNCTION Procedures 4.2.2 SUB Procedures 4.2.3 DEF FN Functions 4.3 Passing by Reference and Passing by Value 4.4 Recursion PART 2 STATEMENT AND FUNCTION REFERENCE ABS Function ASC Function ATN Function BEEP Statement BLOAD Statement BSAVE Statement CALL Statement (BASIC) CALL, CALLS Statement (Non-BASIC) CALL ABSOLUTE Statement CALL INT86OLD Statements CALL INTERRUPT Statements CDBL Function CHAIN Statement CHDIR Statement CHR$ Function CINT Function CIRCLE Statement CLEAR Statement CLNG Function CLOSE Statement CLS Statement COLOR Statement COM Statements COMMAND$ Function COMMON Statement CONST Statement COS Function CSNG Function CSRLIN Function CVSMBF, CVDMBF Functions CVI, CVS, CVL, CVD Functions DATA Statement DATE$ Function DATE$ Statement DECLARE Statement (BASIC) DECLARE Statement (Non-BASIC) DEF FN Statement DEF SEG Statement DEFtype Statements DIM Statement DO...LOOP Statement DRAW Statement END Statement ENVIRON Statement ENVIRON$ Function EOF Function ERASE Statement ERDEV, ERDEV$ Functions ERR, ERL Functions ERROR Statement EXIT Statement EXP Function FIELD Statement FILEATTR Function FILES Statement FIX Function FOR...NEXT Statement FRE Function FREEFILE Function FUNCTION Statement GET Statement──File I/O GET Statement──Graphics GOSUB...RETURN Statements GOTO Statement HEX$ Function IF...THEN...ELSE Statement INKEY$ Function INP Function INPUT$ Function INPUT Statement INPUT # Statement INSTR Function INT Function IOCTL$ Function IOCTL Statement KEY (n) Statements KEY Statements KILL Statement LBOUND Function LCASE$ Function LEFT$ Function LEN Function LET Statement LINE Statement LINE INPUT Statement LINE INPUT # Statement LOC Function LOCATE Statement LOCK...UNLOCK Statement LOF Function LOG Function LPOS Function LPRINT, LPRINT USING Statements LSET Statement LTRIM$ Function MID$ Function MID$ Statement MKD$, MKI$, MKL$, MKS$ Functions MKDIR Statement MKSMBF$, MKDMBF$ Functions NAME Statement OCT$ Function ON ERROR Statement ONevent Statements ON...GOSUB, ON...GOTO Statement ON UEVENT GOSUB Statement OPEN Statement OPEN COM Statement OPTION BASE Statement OUT Statement PAINT Statement PALETTE, PALETTE USING Statements PCOPY Statement PEEK Function PEN Function PEN ON, OFF, and STOP Statements PLAY Function PLAY Statement PLAY ON, OFF, and STOP StatementsP PMAP Function POINT Function POKE Statement POS Function PRESET Statement PRINT Statement PRINT USING Statement PRINT #, PRINT # USING Statements PSET Statement PUT Statement──File I/O PUT Statement──Graphics RANDOMIZE Statement READ Statement REDIM Statement REM Statement RESET Statement RESTORE Statement RESUME Statement RETURN Statement RIGHT$ Function RMDIR Statement RND Function RSET Statement RTRIM$ Function RUN Statement SADD Function SCREEN Function SCREEN Statement SEEK Function SEEK Statement SELECT CASE Statement SETMEM Function SGN Function SHARED Statement SHELL Statement SIN Function SLEEP Statement SOUND Statement SPACE$ Function SPC Function SQR Function STATIC Statement STICK Function STOP Statement STR$ Function STRIG Function and Statement STRIG ON, OFF, and STOP Statements STRING$ Function SUB Statements SWAP Statement SYSTEM Statement TAB Function TAN Function TIME$ Function TIME$ Statement TIMER Function TIMER ON, OFF, and STOP Statements TRON/TROFF Statements TYPE Statement UBOUND Function UCASE$ Function UEVENT Statement UNLOCK Statement VAL Function VARPTR, VARSEG Functions VARPTR$ Function VIEW Statement VIEW PRINT Statement WAIT Statement WHILE...WEND Statement WIDTH Statement WINDOW Statement WRITE Statement WRITE # Statement Appendix A Keyboard Scan Codes and ASCII Character Codes A.1 Keyboard Scan Codes A.2 ASCII Character Codes Appendix B Error Messages B.1 Error-Message Display B.2 Invocation, Compile-Time, and Run-Time Error Messages B.3 LINK Error Messages B.4 LIB Error Messages Index Figures 2.1 BASIC Numeric Representations R.1 WINDOW and WINDOW SCREEN Tables 2.1 Types of Numeric Constants 2.2 Variable-Type Memory Requirements 3.1 Relational Operators and Their Functions 3.2 BASIC Logical Operators 3.3 Values Returned by Logical Operations R.1 INT86OLD and INT86XOLD Register Values R.2 FILEATTR Mode Codes R.3 Values for Bits per Pixel per Plane and for Planes R.4 Keyboard Scan Codes R.5 SCREEN Color and Attribute Ranges R.6 MDPA Screen Modes R.7 Hercules Screen Modes R.8 CGA Screen Modes R.9 EGA Screen Modes R.10 Default Attributes: SCREEN 10, Monochrome Display R.11 Color Values: SCREEN 10, Monochrome Display R.12 VGA Screen Modes R.13 MCGA Screen Modes R.14 Default Attributes and Colors for SCREEN Modes 1 and 9 R.15 Default Attributes and Colors for SCREEN Modes 2 and 11 R.16 Default Attributes and Colors for SCREEN Modes 0, 7, 8, 9, 12, and 13 ──────────────────────────────────────────────────────────────────────────── Introduction Microsoft(R) QuickBASIC 4.5 is a powerful programming language for either commercial applications or quick development of single-use programs. QuickBASIC is compatible with BASICA, adding advanced features such as user-defined data types and recursive procedures to the elements that have traditionally made BASIC an ideal language for new programmers. The Microsoft BASIC Language Reference describes the QuickBASIC programming language. Use this manual as a printed reference guide while you are programming to find the syntax or effect of particular statements and functions. You can also use this book to explore BASIC by reading about unfamiliar statements and trying them in the short example programs provided. The BASIC Language Reference has these parts: ■ Part 1, "Language Fundamentals," describes the elements of the BASIC language: characters, program lines, data types, constants, variables, modules, programs, and procedures. ■ Part 2, "Statement and Function Reference," contains reference material on each BASIC statement and function, organized alphabetically. ■ The appendixes list the keyboard scan and ASCII character codes and provide quick reference information on error messages. This volume is a companion to the other books supplied with QuickBASIC Version 4.5. Learning to Use Microsoft QuickBASIC explains how to use the QuickBASIC environment and introduces BASIC programming. Programming in BASIC contains more advanced programming information. Document Conventions This manual uses the following typographic conventions: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Example of Convention Description ────────────────────────────────────────────────────────────────────────── QB.LIB, ADD.EXE, COPY, Uppercase (capital) letters indicate file names LINK, /X and DOS-level commands. Uppercase is also used for command-line options (unless the application accepts only lowercase). SUB, IF, LOOP, PRINT, Bold capital letters indicate language-specific WHILE, TIME$ keywords with special meaning to Microsoft BASIC. Keywords are a required part of statement syntax, Example of Convention Description ────────────────────────────────────────────────────────────────────────── Keywords are a required part of statement syntax, unless they are enclosed in double brackets as explained below. In programs you write, you must enter keywords exactly as shown. However, you can use uppercase letters or lowercase letters. CALL NewProc(arg1!, This kind of type is used for program examples, var2%) program output, and error messages within the text. ¢INCLUDE: BC.BI A column of three dots indicates that part of the . example program has been intentionally omitted. . . CHAIN "PROG1" END ' Make one pass The apostrophe (single right quotation mark) marks the beginning of a comment in sample Example of Convention Description ────────────────────────────────────────────────────────────────────────── marks the beginning of a comment in sample programs. filespec Italic letters indicate placeholders for information you must supply, such as a file name. Italics are also occasionally used in the text for emphasis. «optional-item» Items inside chevrons are optional. {choice1 | choice2} Braces and a vertical bar indicate a choice among two or more items. You must choose one of the items unless all of the items are also enclosed in double square brackets. repeating elements... Three dots following an item indicate that more items having the same form may appear. ALT+F1 Capital letters are used for the names of keys Example of Convention Description ────────────────────────────────────────────────────────────────────────── ALT+F1 Capital letters are used for the names of keys and key sequences, such as ENTER and CTRL+R. A plus (+) indicates a combination of keys. For example, CTRL+E means to hold down the CTRL key while pressing the E key. The carriage-return key, sometimes marked with a bent arrow, is referred to as ENTER. The cursor movement ("arrow") keys on the numeric keypad are called DIRECTION keys. Individual DIRECTION keys are referred to by the direction of the arrow on the key top (LEFT, RIGHT, UP, DOWN) or the name on the key top (PGUP, PGDN). The key names used in this manual correspond to the names on the IBM(R) Personal Computer keys. Other machines may use different names. Example of Convention Description ────────────────────────────────────────────────────────────────────────── Other machines may use different names. "defined term" Quotation marks usually indicate a new term defined in the text. Video Graphics Array Acronyms are usually spelled out the first time (VGA) they are used. ────────────────────────────────────────────────────────────────────────── The syntax below (for the "LOCK...UNLOCK" statements) illustrates many of the typographic conventions in this manual: LOCK«#»filenumber«,{record | «start» TO end }» . . . UNLOCK«#»filenumber«,{record | «start» TO end }» ──────────────────────────────────────────────────────────────────────────── NOTE Throughout this manual, the term "DOS" refers to both the MS-DOS(R) and IBM Personal Computer DOS operating systems. The name of a specific operating system is used when it is necessary to note features that are unique to that system. The term "BASICA" refers to interpreted versions of BASIC in general. ──────────────────────────────────────────────────────────────────────────── Reference Page Format Each statement and function description in Part 2, "Statement and Function Reference," uses the following format: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Heading Function ────────────────────────────────────────────────────────────────────────── Action Summarizes what the statement or function does. Syntax Gives the correct syntax for the statement or Heading Function ────────────────────────────────────────────────────────────────────────── Syntax Gives the correct syntax for the statement or function. Remarks Describes arguments and options in detail and explains how to use the statement or function. Differences from BASICA Optional section that tells whether or not the given statement or function is new, enhanced, or different from the same statement in the Microsoft BASIC 2.0 Interpreter described in the IBM Personal Computer BASICA reference manual. See Also Mentions related statements and functions (also an optional section). Example Gives sample commands, programs, and program segments illustrating the use of the statement or function (also an optional section). Heading Function ────────────────────────────────────────────────────────────────────────── ────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── PART 1 LANGUAGE FUNDAMENTALS ──────────────────────────────────────────────────────────────────────────── Part 1 describes aspects of the BASIC language. Chapter 1 gives information on the BASIC character set and the structure of a BASIC program line. Chapter 2 discusses data types, constants, variables, and arrays. Chapter 3 talks about BASIC operators and expressions. Chapter 4 explains how to use modules and procedures in BASIC programming. This chapter also describes the relationship between programs and modules and discusses the SUB and FUNCTION procedures available in QuickBASIC. ──────────────────────────────────────────────────────────────────────────── Chapter 1 Language Elements 1.1 Character Set 1.2 The BASIC Program Line 1.2.1 Using Line Identifiers 1.2.2 BASIC Statements 1.2.3 BASIC Line Length This chapter discusses some of the fundamental elements of the QuickBASIC version of the BASIC language. As in virtually all programming languages, characters from the BASIC character set form labels, keywords, variables, and operators. These then combine to form the statements that make up a program. ■ The BASIC character set and the special meanings of some characters ■ The format of a line in a BASIC program ■ Line labels ■ Executable and nonexecutable statements ■ Program line length Chapter 2, "Data Types," and Chapter 3, "Expressions and Operators," discuss other parts of statements, including expressions. 1.1 Character Set The Microsoft BASIC character set consists of alphabetic characters, numeric characters, and special characters. The alphabetic characters in BASIC are the uppercase letters (A-Z) and lowercase letters (a-z) of the alphabet. The BASIC numeric characters are the digits 0-9. The letters A-F and a-f can be used as parts of hexadecimal numbers. The characters in Table 1.1 have special meanings in BASIC statements and expressions. Table 1.1 BASIC Character Set ╓┌─┌──────────────────┌──────────────────────────────────────────────────────╖ Character Name ────────────────────────────────────────────────────────────────────────── ENTER Terminates input of a line Blank (or space) ! Exclamation point (single-precision data-type suffix) # Number sign (double-precision data-type suffix) $ Dollar sign (suffix for string data type) % Percent (suffix for integer data type) & Ampersand (suffix for long-integer data type) ' Single quotation mark (apostrophe) ( Left parenthesis ) Right parenthesis * Asterisk (multiplication symbol) + Plus sign , Comma - Minus sign . Period (decimal point) Character Name ────────────────────────────────────────────────────────────────────────── . Period (decimal point) / Slash (division symbol) : Colon ; Semicolon < Less than = Equal sign (relational operator or assignment symbol) > Greater than ? Question mark @ At symbol [ Left bracket ] Right bracket \ Backslash (integer division symbol) ^ Up arrow or caret (exponentiation symbol) _ Underscore (line continuation) ────────────────────────────────────────────────────────────────────────── 1.2 The BASIC Program Line BASIC program lines have the following syntax: [[line-identifier]] [[statement]] [[: statement]]...[[comment]] 1.2.1 Using Line Identifiers BASIC supports two types of line-identifiers──line numbers and alpha-numeric line labels: 1. A line number may be any combination of digits from 0 to 65,529. The following are examples of valid line numbers: 1 200 300PRINT "hello" '300 is the line number. 65000 Using 0 as a line number is not recommended. Error- and event-trapping statements (ON ERROR and ONevent) interpret the presence of line number 0 to mean that trapping is disabled (stopped). For example, the following statement disables error trapping but does not branch to line 0 if an error occurs: ON ERROR GOTO 0 In addition, RESUME 0 continues execution on the line where the error occurred, not at line number 0. 2. An alphanumeric line label may be any combination of from 1 to 40 letters and digits, starting with a letter and ending with a colon. BASIC keywords are not permitted. The following are valid alphanumeric line labels: Alpha: ScreenSub: Test3A: Case is not significant. The following line labels are equivalent: alpha: Alpha: ALPHA: Line numbers and labels may begin in any column, as long as they are the first characters other than blanks or tabs on the line. Blanks and tabs are also allowed between an alphanumeric label and the colon following it. A line can have only one label. BASIC does not require each line in a source program to have the same type of identifier, either a line number or label. You may mix alphanumeric labels and line numbers in the same program, and you may use alphanumeric labels as objects of any BASIC statement where line numbers are permitted, except as the object of an IF...THEN statement. In IF...THEN statements, BASIC permits only a line number, unless you explicitly use a GOTO statement. For example, the form of the following statement is correct: IF A = 10 THEN 500 However, if the object of the IF...THEN statement is a line label, a GOTO statement is required: IF A = 10 THEN GOTO IncomeData If you are trapping errors, the ERL function returns only the last line number located before the error. Neither RESUME nor RESUME NEXT requires line labels or line numbers. See the entries for ERL and RESUME for more information. Line numbers do not determine the order in which statements are executed in QuickBASIC. For example, QuickBASIC executes statements in the following program in the order 100, 10, 5: 100 PRINT "The first line executed." 10 PRINT "The second line executed." 5 PRINT "The third and final line executed." Some older BASICs, such as BASICA, would execute the lines in numerical order: 5, 10, 100. 1.2.2 BASIC Statements A BASIC statement is either "executable" or nonexecutable." An executable statement advances the flow of a program's logic by telling the program what to do next (telling it to read input, write output, add two numbers together and store the resulting value in a variable, open a file, branch to another part of the program, or take some other action). In contrast, a nonexecutable statement does not advance the flow of a program's logic. Instead, nonexecutable statements perform tasks such as allocating storage for variables, declaring and defining variable types, and designating variables to be shared among all the procedures in a source file. The following BASIC statements are nonexecutable: ■ COMMON ■ CONST ■ DATA ■ DECLARE ■ DEFtype ■ DIM (static arrays only) ■ OPTION BASE ■ SHARED ■ STATIC ■ TYPE...END TYPE Another type of nonexecutable statement is a "comment" used to clarify a program's operation and purpose. A comment is introduced by the REM statement or a single quote character ('). The following lines are equivalent: PRINT "Quantity remaining" : REM Print report label. PRINT "Quantity remaining" ' Print report label. More than one BASIC statement can be placed on a line, but colons (:) must separate statements, as illustrated below: FOR I=1 TO 5 : PRINT "G'day, mate." : NEXT I 1.2.3 BASIC Line Length If you enter your programs using QuickBASIC's built-in editor, you are limited to lines of 256 characters. The QuickBASIC editor does not recognize the underscore character (_) as a line continuation. If you use your own editor, you may use an underscore as the last character to create a program line, like the following, that extends across more than one physical line: IF (TestChar$ = " " OR TestChar$ = ".") AND _ LineNumber < 23 AND NOT EOF(FileNumber) THEN When QuickBASIC loads your program, the underscores are removed and the continued lines are joined to form a single line. The line-length limit is relaxed in this case. Underscores cannot be used to continue DATA or REM statements. ──────────────────────────────────────────────────────────────────────────── Chapter 2 Data Types 2.1 Data Types 2.1.1 Elementary Data Types──String 2.1.2 Elementary Data Types──Numeric 2.1.2.1 Integer Numbers 2.1.2.2 Floating-Point Numbers 2.1.3 User-Defined Data Types 2.2 Constants 2.2.1 Literal Constants 2.2.2 Symbolic Constants 2.3 Variables 2.3.1 Variable Names 2.3.2 Declaring Variable Types 2.3.2.1 Type-Declaration Suffix 2.3.2.2 AS Declaration Statements 2.3.2.3 DEFtype Declaration Statements 2.3.2.4 Declaring Array Variables 2.3.3 Variable Storage Allocation 2.4 Scope of Variables and Constants 2.4.1 Global Variables and Constants 2.4.2 Local Variables and Constants 2.4.3 Sharing Variables 2.4.4 DEF FN Functions 2.4.5 Summary of Scope Rules 2.5 Static and Dynamic Arrays 2.6 Automatic and Static Variables 2.7 Type Conversion This chapter contains seven sections that provide the following information about the data types, constants, and variables in BASIC: ■ The elementary data types (string and numeric) ■ The formation of literal and symbolic constants ■ The rules for naming a BASIC variable and for determining a variable's type, and how BASIC allocates variable storage ■ The scope rules that BASIC follows to decide to which object a variable name refers ■ The difference between static and dynamic arrays ■ The use of automatic and static variables in SUB and FUNCTION procedures ■ The conversions from one numeric type to another that BASIC may perform when doing calculations 2.1 Data Types Every variable in BASIC has a data type that determines what can be stored in the variable. There are two categories of data in BASIC: string data and numeric data. Each category includes elementary data types. The next section summarizes the elementary data types. 2.1.1 Elementary Data Types──String The two kinds of strings are as follows: ■ Variable-length string A variable-length string is a sequence of up to 32,767 characters. The codes for these characters range from 0-127 for American Standard Code for Information Interchange (ASCII) characters, and from 128-255 for non-ASCII characters (see Appendix A, "Keyboard Scan Codes and ASCII Character Codes"). ■ Fixed-length string A fixed-length string contains a declared number of characters. Fixed-length strings can be no longer than 32,767 characters. Fixed-length strings, like variable-length strings, contain characters with codes ranging from 0-255. 2.1.2 Elementary Data Types──Numeric BASIC has two types of integers and two types of floating-point values. Figure 2.1 shows the internal (memory) formats of these four different numeric types. The following table summarizes the types: Numeric Type Description ────────────────────────────────────────────────────────────────────────── Integer (2 bytes) Integers are stored as signed 16-bit binary numbers ranging in value from -32,768 to +32,767. Long integer (4 bytes) "Long" integers are stored as signed 32-bit binary numbers ranging in value from -2,147,483,648 to +2,147,483,647. Single-precision "Single-precision" numbers are accurate to seven floating point (4 bytes) decimal places, and have ranges of -3.402823E+38 to -1.40129E-45 for negative values and 1.40129E-45 to 3.402823E+38 for positive values. Double-precision "Double-precision" numbers are accurate to 15 or floating point (8 bytes) 16 digits and have an extended range: -1.797693134862316E+308 to -4.94065E-324 for negative numbers and 4.94065E-324 to 1.797693134862316E+308 for positive values. ────────────────────────────────────────────────────────────────────────── 2.1.2.1 Integer Numbers Integer 1514 0 ┌─┬───────────────────────┐ │ │ │ └─┴───────────────────────┘ │ sign Long integer 31 30 0 ┌─┬─────────────────────────────────┐ │ │ │ └─┴─────────────────────────────────┘ Single-precision real 31 30 23 22 0 ┌─┬─────┬───────────────────────────┐ │ │ │ │ └─┴─────┴───────────────────────────┘ │ └─┬─┘│└──────────┬──────────────┘ │ │ │ │ sign │Implied Mantissa │ bit │ Exponent Double Precision real 63 62 52 51 ┌─┬───────┬───────────────────────────────────────────────────────┐ │ │ │ │ └─┴───────┴───────────────────────────────────────────────────────┘ │ └─┬───┘│└──────────────────────┬──────────────────────────────┘ │ │ │ │ sign │Implied Mantissa │ bit │ Exponent Figure 2.1 BASIC Numeric Representations All BASIC integers are represented as two's complement values, the most common way of representing integers on a computer. Integers use 16 bits (2 bytes) and long integers use 32 bits (4 bytes). In two's complement representation, positive values are represented as straightforward binary numbers. For example, BASIC would store an integer value of 4 as a sequence of the following 16 bits: 0000000000000100 Negative values are represented as the two's complement of the corresponding positive value. To form the two's complement (the negative) of the integer value 4, first take the representation above and change all ones to zeroes and all zeroes to ones: 1111111111111011 Then add one to the result: 1111111111111100 The final result is how BASIC represents -4 as a binary number. Because of the way two's complement numbers are formed, every combination of bits representing a negative value has a 1 as the leftmost bit. 2.1.2.2 Floating-Point Numbers QuickBASIC Version 4.5 uses IEEE-format floating-point numbers rather than the Microsoft Binary format used in earlier versions. (IEEE is an acronym for Institute of Electrical and Electronics Engineers, Inc.) IEEE format gives more accurate results and makes it possible to use an 8087 or 80287 math coprocessor. Floating-point values are represented in a different format from integers. In floating-point format each number consists of three parts: the sign, the exponent, and the mantissa. You can think of this format as a variation of scientific notation. In scientific notation, the number 1000 would be represented as 1.0 x 10^3. To save space, you could just remember the exponent, 3, and the mantissa, 1.0, and reconstruct the value later by raising 10 to the power 3 and multiplying by the mantissa. Floating-point notation works by saving just the exponent and the mantissa. The only difference from scientific notation is that in this format the exponent represents a power of 2, not a power of 10. In a single-precision number, the sign takes 1 bit, the exponent takes 8 bits, and the mantissa uses the remaining 23 bits and an additional implied bit. Double-precision values occupy 8 bytes or 64 bits: 1 bit for the sign, 11 bits for the exponent, and an implied bit and 52 actual bits for the mantissa. The following program (included on the QuickBASIC distribution disks in the file FLPT.BAS) can be used to examine the internal format of single-precision values: DECLARE FUNCTION MHex$ (X AS INTEGER) ' Display how a given real value is stored in memory. DEFINT A-Z DIM Bytes(3) CLS PRINT "Internal format of IEEE number (in hexadecimal)" PRINT DO ' Get the value. INPUT "Enter the value (END to end): ", A$ IF UCASE$(A$) = "END" THEN EXIT DO RealValue! = VAL(A$) ' Convert the real value to a long without changing any of ' the bits. AsLong& = CVL(MKS$(RealValue!)) ' Make a string of hex digits, and add leading zeroes. Strout$ = HEX$(AsLong&) Strout$ = STRING$(8 - LEN(Strout$), "0") + Strout$ ' Save the sign bit, and then eliminate it so it doesn't ' affect breaking out the bytes. SignBit&=AsLong& AND &H80000000& AsLong&=AsLong& AND &H7FFFFFFF& ' Split the real value into four separate bytes. ' --the AND removes unwanted bits; dividing by 256 shifts ' the value right 8 bit positions. FOR I = 0 TO 3 Bytes(I) = AsLong& AND &HFF& AsLong& = AsLong& 256& NEXT I ' Display how the value appears in memory. PRINT PRINT "Bytes in Memory" PRINT " High Low" FOR I = 1 TO 7 STEP 2 PRINT " "; MID$(Strout$, I, 2); NEXT I PRINT:PRINT ' Set the value displayed for the sign bit. Sign = ABS(SignBit& <> 0) ' The exponent is the right seven bits of byte 3 and the ' leftmost bit of byte 2. Multiplying by 2 shifts left and ' makes room for the additional bit from byte 2. Exponent = Bytes(3) * 2 + Bytes(2) 128 ' The first part of the mantissa is the right seven bits ' of byte 2. The OR operation makes sure the implied bit ' is displayed by setting the leftmost bit. Mant1 = (Bytes(2) OR &H80) PRINT " Bit 31 Bits 30-23 Implied Bit & Bits 22-0" PRINT "Sign Bit Exponent Bits Mantissa Bits" PRINT TAB(4); Sign; TAB(17); MHex$(Exponent); PRINT TAB(33); MHex$(Mant1);MHex$(Bytes(1));MHex$(Bytes(0)) PRINT LOOP ' MHex$ makes sure we always get two hex digits. FUNCTION MHex$ (X AS INTEGER) STATIC D$ = HEX$(X) IF LEN(D$) < 2 THEN D$ = "0" + D$ MHex$ = D$ END FUNCTION Output Enter the value (END to end): 4 Bytes in Memory High Low 40 80 00 00 Bit 31 Bits 30-23 Implied Bit & Bits 22-0 Sign Bit Exponent Bits Mantissa Bits 0 81 800000 The program displays the sign, exponent, and mantissa of the single-precision value. The mantissa's implied bit is automatically included. All values are printed out in hexadecimal values (base 16 numbers), which are a shorthand way of writing binary numbers. Each hexadecimal digit represents a pattern of 4 bits: 0 hexadecimal represents 0000 binary, 8 hexadecimal represents 1000, and F hexadecimal (a digit for the value 15 in decimal) represents 1111. Looking at the output from the program, the decimal value 4 is represented in memory as a series of 4 bytes: 40 80 00 00 These 4 bytes break down into a single-sign bit of 0, a 1-byte exponent of &H81, and a mantissa of &H800000. The exponent value of &H81 represents a biased exponent, not the true exponent. With a biased exponent, a fixed value (a "bias") is added to the true exponent and the result is stored as part of the number. For single-precision values, the bias is &H7F or 127. Double-precision values use a bias of &H3FF or 1023. Using a biased exponent avoids having to use one of the exponent bits to represent the sign. In the output, 4 is a power of 2, so the true exponent is 2. Adding the bias (&H7F) gives the stored exponent value of &H81. A normalized mantissa refers to a mantissa that is multiplied by 2 (shifted to the left) and the exponent decreased until the leftmost bit is a 1. By eliminating leading zeroes from the mantissa, more significant bits can be stored. In memory, the mantissa for a value of 4 is all zeroes. This is so because the mantissa is normalized and the leftmost bit is assumed. Because the mantissa is always normalized, the leftmost bit is always a 1. And because the leftmost bit is always a 1, there is no reason to store it as part of the number. BASIC thus stores 23 bits (number 22 to 0) for the mantissa of a single-precision number but also includes a 24th, implied bit that is always a 1. There is an implied "binary point" (analogous to a decimal point) to the right of the implied bit. The binary point indicates that bits 22 to 0 in the mantissa are really a binary fraction. Thus, in the example, the mantissa is really a single 1 (the implied bit) followed by a zero binary fraction (bits 22 to 0). The mantissa of 1 multiplied by 2 taken to the power of the exponent, 2, is 1 x 2^2, or 4. 2.1.3 User-Defined Data Types BASIC lets you define new data types using the TYPE statement. A user-defined type is an aggregate type made up of elementary BASIC types. For example, the following TYPE statement defines a type, SymTabEntry: TYPE SymTabEntry Identifier AS STRING*40 LineNumber AS LONG Value AS LONG END TYPE The new type contains a fixed-length string and two long integers. A variable of a user-defined type occupies only as much storage as the sum of its components. A SymTabEntry takes up 48 bytes: 40 bytes for the fixed-length string and 4 bytes each for the two long integers. You may use any of the BASIC data types (except variable-length strings) in a user-defined type: short and long integers, single- and double-precision floating-point values, and fixed-length strings. However, user-defined types cannot include arrays. 2.2 Constants Constants are predefined values that do not change during program execution. There are two general types of constants: literal constants (such as numbers and strings) and symbolic constants. 2.2.1 Literal Constants BASIC has two kinds of literal constants: string and numeric. A string constant is a sequence of up to 32,767 alphanumeric characters enclosed by double quotation marks. These alphanumeric characters can be any of the characters (except the double quote character and any carriage-return and line-feed sequences) whose ASCII codes fall within the range 0-255. This range includes both the actual ASCII characters (0-127) and the extended characters (128-255). The following are all valid string constants: "HELLO" "$25,000.000" "Number of Employees" Numeric constants are positive or negative numbers. There are four types of numeric constants: integer, long integer, fixed point, and floating point. Table 2.1 below describes these types and provides examples. Fixed-point and floating-point numeric constants can be either single-precision or double-precision numbers. Single-precision numeric constants are stored with 7 digits of precision (plus the exponent). Double-precision numbers are stored with 15 or 16 digits of precision (plus the exponent). A single-precision constant is any numeric constant that has one of the following properties: ■ Exponential form denoted by "E" ■ A trailing exclamation mark (!) ■ A value containing a decimal point that does not have either a "D" in the exponent or a trailing number sign (#) and that has fewer than 15 digits ■ A value without a decimal point that has fewer than 15 digits but cannot be represented as a long-integer value A double-precision constant is any numeric constant that has one of the following properties: ■ Exponential form denoted by "D" ■ A trailing number sign (#) ■ A decimal point, no "E" in the exponent or trailing exclamation mark (!), and more than 15 digits Table 2.1 Types of Numeric Constants ╓┌─┌──────────────────┌─────────────────┌──────────────────┌─────────────────╖ Type Subtype Description Examples ────────────────────────────────────────────────────────────────────────── Integer Decimal One or more 68 +407 -1 decimal digits (0-9) with an optional sign prefix (+ or -). The range for integer decimal constants is -32,768 to +32,767. Integer Hexadecimal One or more &H76 &H32F hexadecimal digits Type Subtype Description Examples ────────────────────────────────────────────────────────────────────────── hexadecimal digits (0-9, a-f, or A-F) with the prefix &H or &h. The range for integer hexadecimal constants is &h0 to &hFFFF. Integer Octal One or more octal &o347 &1234 digits (0-7) with the prefix &O, &o, or &. The range for integer octal constants is &o0 to &o177777. Long integer Decimal One or more 95000000 -400141 decimal digits Type Subtype Description Examples ────────────────────────────────────────────────────────────────────────── decimal digits (0-9) with an optional sign prefix (+ or -) and the suffix &. The range for long decimal constants is -2,147,483,648 to +2,147,483,647. Long integer Hexadecimal One or more &H0& &H1AAAAA& hexadecimal digits (0-9, a-f, or A-F) with the prefix &H or &h and the suffix &. The range for long hexadecimal constants is &h0& Type Subtype Description Examples ────────────────────────────────────────────────────────────────────────── constants is &h0& to &hFFFFFFFF&. Long integer Octal One or more octal &o347& &555577733& digits (0-7) with the prefix &O, &o, or & and the suffix &. The range for long octal constants is &o0& to &o37777777777&. Fixed point Positive or 9.0846 negative real numbers──numbers containing decimal points. Type Subtype Description Examples ────────────────────────────────────────────────────────────────────────── Floating point Single precision Positive or 2235.988E-7 2359E6 negative numbers represented in exponential form (similar to scientific notation). A single-precision floating-point constant is an optionally signed integer or fixed-point number (the mantissa) followed by the letter E and an optionally signed integer (the Type Subtype Description Examples ────────────────────────────────────────────────────────────────────────── integer (the exponent). The constant's value is the mantissa multiplied by the power of ten represented by the exponent. The range for single-precision constants is -3.37E+38 to 3.37E+38. Floating point Double precision Double-precision 4.35D-10 floating-point constants have the same form as single-precision Type Subtype Description Examples ────────────────────────────────────────────────────────────────────────── single-precision floating-point constants, but use D, rather than E, to indicate the exponent. Double-precision constants have a range of -1.67D+308 to 1.67D+308. ────────────────────────────────────────────────────────────────────────── Numeric constants in BASIC cannot contain commas. The following are examples of numeric constants: Single Precision Double Precision ────────────────────────────────────────────────────────────────────────── 46.8 345692811.5375901 -1.09E-6 -1.09432D-06 3489.0 3489.0# 22! 987654321.1234567 ────────────────────────────────────────────────────────────────────────── 2.2.2 Symbolic Constants BASIC provides symbolic constants that can be used in place of numeric or string values. The following fragment declares two symbolic constants and uses one to dimension an array: CONST MAXCHARS%=254, MAXBUF%=MAXCHARS%+1 DIM Buffer%(MAXBUF%) The name of a symbolic constant follows the same rules as a BASIC variable name. You may include a type-declaration character (%, #, !, or $) in the name to indicate its type, but this character is not part of the name. For example, after the following declaration, the names N!, N#, N$, N%, and N& cannot be used as variable names because they have the same name as the constant: CONST N=45 A constant's type is determined either by an explicit type-declaration character or the type of the expression. Symbolic constants are unaffected by DEFtype statements. If you omit the type-declaration character, the constant is given a type based on the expression. Strings always yield a string constant. With numeric expressions, the expression is evaluated and the constant is given the simplest type that can represent it. For example, if the expression gives a result that can be represented as an integer, the constant is given an integer type. See Section 2.4 below, "Scope of Variables and Constants," for information about the scope of constants. See the entry for CONST in Part 2, "Statement and Function Reference," for more information about where and how to use symbolic constants. 2.3 Variables A variable is a name that refers to an object──a particular number, string, or record. (A record is a variable declared to be a user-defined type.) Simple variables refer to a single number, string, or record. Array variables refer to a group of objects, all of the same type. A numeric variable, whether simple or array, can be assigned only a numeric value (either integer, long integer, single precision, or double precision); a string variable can be assigned only a character-string value. You can assign one record variable to another only if both variables are the same user-defined type. However, you can always assign individual elements of a record to a variable of the corresponding type. The following list shows some examples of variable assignments: Variable Assignment Example ────────────────────────────────────────────────────────────────────────── A constant value A = 4.5 The value of another B$ = "ship of fools" A$ = B$ Profits = string or numeric NetEarnings variable The value of a record TYPE EmployeeRec EName AS STRING*25 SocSec AS element STRING*9 END TYPE DIM CurrentEmp AS EmployeeRec . . . OutSocSec$=CurrentEmp.SocSec The value of one record TYPE FileBuffer EName AS STRING*25 JobClass AS variable to another of INTEGER END TYPE DIM Buffer1 AS FileBuffer DIM the same type Buffer2 AS FileBuffer . . . Buffer2=Buffer1 The value obtained by CONST PI = 3.141593 Conversion = 180/PI TempFile$ combining other = FileSpec$+".BAK" variables, constants, and operators ────────────────────────────────────────────────────────────────────────── See Chapter 3, "Expressions and Operators," for more information on the operators used in BASIC for combining variables and constants. In any case, the variable must always match the type of data (numeric or string) assigned to it. Before a variable is assigned a value, its value is assumed to be zero (for numeric variables) or null (for string variables). All fields in a record, including string fields, are initialized to zero. 2.3.1 Variable Names A BASIC variable name may contain up to 40 characters. The characters allowed in a variable name are letters, numbers, the decimal point, and the type-declaration characters (%, &, !, #, and $). The first character in a variable name must be a letter. If a variable begins with FN, it is assumed to be a call to a DEF FN function. (As a general rule, the use of a FUNCTION is preferred over a DEF FN.) A variable name cannot be a reserved word, but embedded reserved words are allowed. For example, the following statement is illegal because LOG is a reserved word (BASIC is not case sensitive): Log = 8 However, the following statement is legal: TimeLog = 8 Reserved words include all BASIC commands, statements, function names, and operator names (see Appendix E, "BASIC Reserved Words," in Programming in BASIC for a complete list of reserved words). Variable names must also be distinct from both SUB and FUNCTION procedure names and symbolic constant (CONST) names. 2.3.2 Declaring Variable Types Simple variables can be numeric, string, or record variables. You may specify simple variable types by the use of a type-declaration suffix, in an AS declaration statement, or in a DEFtype declaration statement. Variables may also be declared as arrays. 2.3.2.1 Type-Declaration Suffix Append one of the following type-declaration suffixes to the variable name: % & ! # $ The dollar sign ($) is the type-declaration character for string variables; that is, it "declares" that the variable represents a string and that you can assign a string constant to it of up to 32,767 characters, as in the example below. A$ = "SALES REPORT" Numeric-variable names can declare integer values (denoted by the % suffix), long-integer values (denoted by the & suffix), single-precision values (denoted by the ! suffix), or double-precision values (denoted by the # suffix). Single precision is the default for variables without a type suffix. There is no type-declaration character for a user-defined type. 2.3.2.2 AS Declaration Statements Declare the variable in a declaration having the form declare variablename AS type where declare can be either DIM, COMMON, REDIM, SHARED, or STATIC, and type can be either INTEGER, LONG, SINGLE, DOUBLE, STRING, or a user-defined type. For example, the following statement declares the variable A as having a long-integer type: DIM A AS LONG String variables declared in an AS STRING clause can be either variable-length strings or fixed-length strings. Variable-length strings are "expandable": their length depends on the length of any string assigned to them. Fixed-length strings have a constant length, specified by adding * number to the AS STRING clause, where number is the length of the string in bytes. For example: ' String1 can have a variable length: DIM String1 AS STRING ' String2 has a fixed length of 7 bytes: DIM String2 AS STRING*7 String1 = "1234567890" String2 = "1234567890" PRINT String1 PRINT String2 Output 1234567890 1234567 For more on fixed-length and variable-length strings, see Chapter 4, "String Processing," in Programming in BASIC. Declare record variables by using the name of the user type in the AS clause: TYPE InventoryItem Description AS STRING*25 Number AS STRING*10 Quantity AS LONG OrderPoint AS LONG END TYPE DIM CurrentItem AS InventoryItem, PreviousItem AS InventoryItem Use the format variablename.elementname to refer to individual elements of the new variable, as in the following example: IF CurrentItem.Description = "Ergonomic Desk Chair" THEN PRINT CurrentItem.Number; CurrentItem.Quantity END IF If you declare a variable with an AS clause, every declaration of the variable must use the AS clause. For example, in the following fragment the AS clause is required in the COMMON statement because AS was also used in the DIM statement: CONST MAXEMPLOYEES=250 DIM EmpNames(MAXEMPLOYEES) AS STRING COMMON EmpNames() AS STRING . . . 2.3.2.3 DEFtype Declaration Statements Use the BASIC statements DEFINT, DEFLNG, DEFSTR, DEFSNG, and DEFDBL to declare the types for certain variable names. By using one of these DEFtype statements, you can specify that all variables starting with a given letter or range of letters are one of the elementary variable types, without using the trailing declaration character. DEFtype statements only affect variable names in the module in which they appear. See the DEFtype statement reference pages in Part 2, "Statement and Function Reference," for more information. The type-declaration suffixes for variable names, the type names accepted in AS type declarations, and the memory (in bytes) required for each variable type to store the variable's value are listed in Table 2.2. Table 2.2 Variable-Type Memory Requirements ╓┌─┌──────────────────┌─────────────────┌──────────────────┌─────────────────╖ AS Type Variable Size Suffix Name Type of Data AS Type Variable Size Suffix Name Type of Data ────────────────────────────────────────────────────────────────────────── % INTEGER Integer 2 & LONG Long integer 4 ! SINGLE Single precision 4 # DOUBLE Double precision 8 $ STRING Variable-length Takes 4 bytes for string descriptor, 1 byte for each character in string $ STRING*num Fixed-length Takes num bytes string None Declared Record variable Takes as many user-defined type bytes as the individual AS Type Variable Size Suffix Name Type of Data ────────────────────────────────────────────────────────────────────────── individual elements require ────────────────────────────────────────────────────────────────────────── 2.3.2.4 Declaring Array Variables An array is a group of objects referenced with the same variable name. The individual values in an array are elements. Array elements are also variables and can be used in any BASIC statement or function that uses variables. You "dimension" an array when you use it the first time or when you declare the name, type, and number of elements in the array. Each element in an array is referred to by an array variable subscripted with an integer or an integer expression. (You may use noninteger numeric expressions as array subscripts; however, they are rounded to integer values.) The name of an array variable has as many subscripts as there are dimensions in the array. For example, V(10) refers to a value in a one-dimensional array, while T$(1,4) refers to a value in a two-dimensional string array. The default upper subscript value for any array dimension is 10. The maximum subscript value and the number of dimensions can be set by using the DIM statement. (See the reference pages for DIM in Part 2, "Statement and Function Reference," for more information.) The maximum number of dimensions for an array is 60. The maximum number of elements per dimension is 32,767. You may have arrays of any simple variable type, including records. To declare an array of records, first declare the data type in a TYPE statement and then dimension the array: TYPE TreeNode LeftPtr AS INTEGER RightPtr AS INTEGER DataField AS STRING*20 END TYPE DIM Tree(500) AS TreeNode Each element of the array Tree is a record of type TreeNode. To use a particular element of a record in an array, use form variablename.elementname (dot notation form): CONST MAXEMPLOYEES=500 TYPE EmployeeRec EName AS STRING*25 SocSec AS STRING*9 END TYPE DIM Employees(MAXEMPLOYEES) AS EmployeeRec . . . PRINT Employees(I).EName;" ";Employees(I).SocSec Array names are distinct from simple variable names. The array variable T and the simple variable T in the following example are two different variables: DIM T(11) T = 2 : T(0) = 1 'T is simple variable. FOR I% = 0 TO 10 'T(0) is element of array. T(I% + 1) = T * T(I%) NEXT Array elements, like simple variables, require a certain amount of memory, depending on the variable type. See Table 2.2 for information on the memory requirements for storing individual array elements. To find the total amount of memory required by an array, multiply the number of elements by the bytes per element required for the array type. For example, consider the following two arrays: DIM Array1(1 TO 100) AS INTEGER DIM Array#(-5 TO 5) The first array, Array1, has 100 integer elements, so its values take 200 bytes of memory. The second array, Array2, has 11 double-precision elements, so its values require 88 bytes of memory. Because BASIC must store information about the array along with the array's values, arrays take more memory than just the space for the values. 2.3.3 Variable Storage Allocation BASIC stores different kinds of variables in different areas in memory. You need to worry about where variables are stored only if you are either doing mixed-language programming or using one of the following BASIC statements or functions: ■ CALL, CALLS (non-BASIC procedures) ■ DECLARE (non-BASIC procedures) ■ SADD ■ SETMEM ■ VARPTR ■ VARSEG ■ VARPTR$ BASIC stores variables either in an area called DGROUP or as far objects. (DGROUP is the name of the default data segment, the segment referenced when DEF SEG is used without an address.) Variables stored in DGROUP can be referenced by using near addresses or pointers. A near address consists of a single value or offset from the beginning of a segment or block of memory. Far objects are referenced by using far addresses or pointers. A far address consists of two parts: the starting address of a segment or block of memory and the offset within the segment. See the entries for the statements listed above for information about getting and using far pointers. Whether a variable is stored in DGROUP or as a far object depends first on whether it is a simple variable or an array. All simple variables are stored in DGROUP. Array storage is a little more complex and is slightly different between programs run as .EXE files and programs run within the QuickBASIC environment. In programs run as .EXE files, array variables are stored as follows: ■ All static arrays are stored in DGROUP and can be referenced with near addresses. ■ All dynamic arrays of variable-length strings are also stored in DGROUP and can also be referenced with near addresses. ■ All other dynamic arrays are stored as far objects and require far addresses. See Section 2.5 for a description of static and dynamic arrays. In programs run within the QuickBASIC environment, array variable storage follows these rules: ■ All static arrays in a COMMON block are stored in DGROUP and can be referenced with near addresses. ■ All arrays of variable-length strings are also stored in DGROUP and can also be referenced with near addresses. ■ All other arrays are stored as far objects and require far addresses. Because BASIC attempts to make the most efficient use of memory possible, several different things may cause a variable's memory location to change. These include a reference to a string literal or expression, the invocation of a DEF FN or FUNCTION, the use of a BASIC string or memory-related function, and a reference to an implicitly dimensioned array. To generate accurate results and because BASIC variables may move, use the results of VARPTR, VARSEG, VARTPR$, or SADD immediately after a function call that affects a variable. 2.4 Scope of Variables and Constants Any time a variable appears, BASIC follows a set of rules in determining to which object the variable refers. These rules describe a variable's scope──the range of statements over which the variable is defined. The BASICA interpreter has a very simple scope rule: a variable exists when you first use it and persists until the program ends. The scope of a variable is from its first use through the end of the program. In QuickBASIC, you can control the scope of variables and symbolic constants──which helps you write compact, well-defined SUB and FUNCTION procedures that don't interfere with each other. You can also make some variables available to all procedures in a module, and thereby share important data structures among procedures. You may think of variables and constants as having one of two scopes: global or local. Global variables, once declared, may be used anywhere in a module to refer to some single object. Local variables are local to some part of the module, the module-level code or one of the procedures. In addition, variables can be shared in such a way that they aren't quite global, nor are they completely local. The rest of this section discusses global and local scope, and shared variables. The following skeleton of a program is used in this discussion. The program, a main program and two procedures, replaces runs of blanks in a file with tab characters──a simple first step in compressing a file. (The program is included on the QuickBASIC release disks in the file ENTAB.BAS.) DEFINT a-z DECLARE FUNCTION ThisIsATab(Column AS INTEGER) CONST MAXLINE=255, TABSPACE=8 CONST NO=0, YES=NOT NO DIM SHARED TabStops(MAXLINE) . . . ' Set the tab positions (uses the global array TabStops). CALL SetTabPos . . . IF ThisIsATab(CurrentColumn) THEN PRINT CHR$(9); LastColumn=CurrentColumn END IF . . . '==================SUB SetTabPos========================= ' Set the tab positions in the array TabStops. ' SUB SetTabPos STATIC FOR I=1 TO MAXLINE TabStops(I)=((I MOD TABSPACE)=1) NEXT I END SUB '===============FUNCTION ThisIsATab====================== ' Answer the question, "Is this a tab position?" ' FUNCTION ThisIsATab(LastColumn AS INTEGER) STATIC IF LastColumn>MAXLINE THEN ThisIsATab=YES ELSE ThisIsATab=TabStops(LastColumn) END IF END FUNCTION 2.4.1 Global Variables and Constants Both variables and symbolic constants can be global in BASIC programs. A global variable or global symbolic constant is defined for the entire module. For a variable, the only way to make it global is to declare it in the module-level code with the SHARED attribute in a DIM, REDIM, or COMMON statement. A symbolic constant is a global constant if it is declared in the module-level code using a CONST statement. In the sample program, the array TabStops is a global variable. Because TabStops is declared in a DIM statement with the SHARED attribute, it is shared with every procedure in the module. Notice that both procedures in the program (ThisIsATab and SetTabPos) use TabStops by making a reference to it. Global variables do not require any additional declarations to be used in procedures in the module. Similarly, the symbolic constants MAXLINE and TABSPACE are global constants. If you use the name of a global variable or constant in a procedure, you are referring to the global variable and not a local variable of the same name. ──────────────────────────────────────────────────────────────────────────── NOTE The SHARED statement allows procedures to share variables with the module-level code. This is not the same as making the variable global. See Section 2.4.3 below, "Sharing Variables," for more information. ──────────────────────────────────────────────────────────────────────────── 2.4.2 Local Variables and Constants A local variable or constant exists only within a procedure or the module-level code. If the name of a local variable is used in another procedure in a module, the name represents a different variable and refers to a different object. The sample program ENTAB.BAS above includes many local variables. The variables CurrentColumn and LastColumn are local to the module-level code. The variable I is local to the subprogram SetTabPos. Finally, the variable LastColumn in the parameter list of ThisIsATab can be thought of as a local variable because it is a formal parameter. (Remember, however, that a formal parameter stands for the actual argument passed to the procedure. See Section 4.3, "Passing by Reference and Passing by Value," for additional information.) It is simplest to think of a local variable as any variable that isn't global. Any variable that appears in module-level code or in a procedure is local if it isn't declared in a DIM, REDIM, or COMMON statement with the SHARED attribute. (There is one exception. See Section 2.4.3, "Sharing Variables," below.) Even if a variable appears in one of these statements, you may still use a local variable of the same name in a procedure by declaring the variable in a STATIC statement. If the sample program had a DIM SHARED statement declaring I to be a global variable in the main program, you could make I a local variable in SetTabPos by adding a STATIC statement just after the SUB statement: SUB SetTabPos STATIC STATIC I . . . Any symbolic constant declared inside a SUB or FUNCTION procedure is a local constant. For example, in the following fragment, ENDOFLIST is a local symbolic constant that exists only in the function FindElement: FUNCTION FindElement(X()) CONST ENDOFLIST = -32767 . . . END FUNCTION ──────────────────────────────────────────────────────────────────────────── NOTE The STATIC statement not only declares a variable to be local: it also directs the compiler to save the value of the variable between procedure calls. Do not use STATIC statements in recursive procedures if you do not want a variable's value saved between calls. See Section 2.6, "Automatic and STATIC Variables," for more information. ──────────────────────────────────────────────────────────────────────────── 2.4.3 Sharing Variables You can share variables among parts of a module without making the variables global by using the SHARED statement. For example, to share TabStops without making it a global variable, you would remove the SHARED attribute in the module-level code and add SHARED statements to the two procedures: DIM TabStops(MAXLINE) . . . SUB SetTabPos STATIC SHARED TabStops() . . . FUNCTION ThisIsATab(LastColumn AS INTEGER) STATIC SHARED TabStops() . . . The SHARED statements indicate that the name TabStops in both procedures refers to the same variable defined at the module level. 2.4.4 DEF FN Functions The DEF FN function is an exception to the BASIC scope rules. Every variable in a DEF FN function that isn't in its parameter list is part of the module-level code. To make a variable local to a DEF FN, you must declare the variable in a STATIC statement. The STATIC statement in the following DEF FN function makes the variable I local: CONST NO = 0, YES = NOT NO DEF FNIsThereAZ (A$) STATIC I FOR I = 1 TO LEN(A$) IF UCASE$(MID$(A$, I, 1)) = "Z" THEN FNIsThereAZ = YES EXIT DEF END IF NEXT I FNIsThereAZ = NO END DEF Remember, as a general rule a FUNCTION is preferred over a DEF FN because of the improved portability and increased modularity the FUNCTION provides. 2.4.5 Summary of Scope Rules The following list summarizes BASIC's scope rules: ■ A variable declared in a DIM, REDIM, or COMMON statement with the SHARED attribute is a global variable. Any SUB or FUNCTION procedure can refer to the variable. ■ A symbolic constant is global if it is declared in a CONST statement in the module-level code. Symbolic constants declared in a SUB or FUNCTION are local. ■ A variable is a local variable if it appears in a procedure and is not declared as a global variable. You can use the name of a global variable as a local variable in a procedure by declaring it in the procedure with the STATIC statement or by using it as a formal parameter. ■ The SHARED statement lets you share a variable with the module-level code and other procedures with equivalent SHARED statements without making the variable a global variable. ■ All variables in a DEF FN function are part of the module-level code unless they are either explicitly made local in a STATIC statement or are formal parameters. 2.5 Static and Dynamic Arrays You can get better control of your program's use of memory by controlling when storage is set aside for arrays. Storage for arrays can be set aside when the program is compiled or when the program is running. Arrays given storage when the program is compiled are static arrays. Dynamic arrays have storage set aside when the program is run. The storage taken by dynamic arrays can be eliminated while the program is not running in order to free memory for other uses. See the entries for DIM, ERASE, and REDIM in Part 2, "Statement and Function Reference," for specific information about manipulating dynamic arrays. How an array is declared can determine whether the array is static or dynamic. By default, arrays dimensioned with constant subscripts or arrays that are implicitly dimensioned are static arrays. Arrays dimensioned with variable subscripts or that are first declared in a COMMON statement are dynamic arrays. In a SUB or FUNCTION not declared static, all arrays are dynamic. You can also use the ¢STATIC and ¢DYNAMIC metacommands to control how array storage is allocated. However, the ¢STATIC metacommand cannot force arays to be static in a procedure not declared static; in such a procedure all arrays are dynamic. See Appendix F, "Metacommands," in Programming in BASIC for more information. In some cases, you can allow more space for strings by replacing static arrays with dynamic arrays. In programs run as .EXE files, the space for static arrays is allocated from DGROUP, an area where strings are stored. On the other hand, dynamic arrays, other than variable-length string arrays, do not take any space in DGROUP; they are stored as far objects and require far addresses. 2.6 Automatic and Static Variables BASIC procedures can use both automatic and static variables. Automatic variables are initialized at the start of each call to the FUNCTION or SUB; static variables retain values between calls. You can control whether the default is automatic or static by using or omitting the STATIC keyword in the SUB or FUNCTION statement. If you omit STATIC, then the default for variables is automatic. When you use STATIC, the default for all variables in the procedure is static: the values of the variables are saved between procedure calls. You can make selected variables in a procedure static by making the default automatic (omitting STATIC from the SUB or FUNCTION statement) and using the STATIC statement. The following program uses a FUNCTION that has two static variables: Start% and SaveStr$. The other variables are automatic. The FUNCTION takes a string and returns one token──a string of characters──until the end of the string is reached. On the first call, StrTok$ makes a local copy of the string Srce$ in the static variable SaveStr$. After the first call, StrTok$ returns additional tokens from the string using the static variable Start% to remember where it left off. All of the other variables (BegPos%, Ln%, etc.) are automatic. (This program is included on the QuickBASIC distribution disks under the file name TOKEN.BAS.) DECLARE FUNCTION StrTok$(Source$,Delimiters$) LINE INPUT "Enter string: ",P$ ' Set up the characters that separate tokens. Delimiters$=" ,;:().?"+CHR$(9)+CHR$(34) ' Invoke StrTok$ with the string to tokenize. Token$=StrTok$(P$,Delimiters$) WHILE Token$<>"" PRINT Token$ ' Call StrTok$ with a null string so it knows this ' isn't the first call. Token$=StrTok$("",Delimiters$) WEND FUNCTION StrTok$(Srce$,Delim$) STATIC Start%, SaveStr$ ' If first call, make a copy of the string. IF Srce$<>"" THEN Start%=1 : SaveStr$=Srce$ END IF BegPos%=Start% : Ln%=LEN(SaveStr$) ' Look for start of a token (character that isn't ' delimiter). WHILE(BegPos%<=Ln% AND INSTR(Delim$,MID$(SaveStr$,BegPos%,1))<>0) BegPos%=BegPos%+1 WEND ' Test for token start found. IF BegPos% > Ln% THEN StrTok$="" : EXIT FUNCTION END IF ' Find the end of the token. End%=BegPos% WHILE(End%<=Ln%AND INSTR(Delim$,MID$(SaveStr$,End%,1))=0) End%=End%+1 WEND StrTok$=MID$(SaveStr$,BegPos%,End%-BegPos%) ' Set starting point for search for next token. Start%=End% END FUNCTION Output Enter string: Allen spoke: "What's a hacker, anyway?" Allen spoke What's a hacker anyway 2.7 Type Conversion When necessary, BASIC converts a numeric constant from one type to another, according to the following rules: ■ If a numeric constant of one type is set equal to a numeric variable of a different type, the numeric constant is stored as the type declared in the variable name, as in the following example: A% = 23.42 PRINT A% Output 23 If a string variable is set equal to a numeric value, or vice versa, an error message is generated that reads Type Mismatch. ■ During expression evaluation, the operands in an arithmetic or relational operation are converted to the same degree of precision, that of the most precise operand, as each operation is performed. Also, the result of an arithmetic operation is returned to the final degree of precision, as in this example: X% = 2 : Y! = 1.5 : Z# = 100 A! = X% / Y! PRINT A! * Z# Output 133.3333373069763 Although the preceding result is displayed in double precision (because of the double-precision variable Z#), it has only single-precision accuracy because the assignment to A! forced the result of X% / Y! to be reduced to single-precision accuracy. This explains the nonsignificant digits (73069763) after the fifth decimal place. Contrast this with the output from the following example in which the intermediate result of X% / Y! is retained in double-precision: X% = 2 : Y# = 1.5 : Z# = 100 PRINT X% / Y# * Z# Output 133.3333333333333 ■ Logical operators such as AND and NOT convert their operands to long integers if necessary. Operands must be in the range -2,147,483,648 to +2,147,483,647 or an Overflow error message is generated. See Chapter 3, "Expressions and Operators," for more information on logical operators. ■ When a floating-point value is converted to an integer, the fractional portion is rounded, as in this example: Total% = 55.88 PRINT Total% Output 56 ──────────────────────────────────────────────────────────────────────────── Chapter 3 Expressions and Operators 3.1 Expressions and Operators Defined 3.2 Hierarchy of Operations 3.3 Arithmetic Operators 3.3.1 Integer Division 3.3.2 Modulo Arithmetic 3.3.3 Overflow and Division by Zero 3.4 Relational Operators 3.5 Logical Operators 3.6 Functional Operators 3.7 String Operators This chapter discusses how to combine, modify, compare, or get information about expressions by using the operators available in BASIC. Anytime you do a calculation or manipulate a string, you are using expressions and operators. This chapter describes how expressions are formed, discusses the order in which BASIC uses operators, and concludes by describing the following five kinds of operators: ■ Arithmetic operators, used to perform calculations ■ Relational operators, used to compare strings and numeric values ■ Logical operators, used to test complex conditions or manipulate individual bits ■ Functional operators, used to supplement simpler operators ■ String operators, used to combine and compare strings 3.1 Expressions and Operators Defined An expression can be a string or numeric constant, a variable, or a single value obtained by combining constants, variables, and other expressions with operators. Operators perform mathematical or logical operations on values. The operators provided by BASIC can be divided into five categories, as follows: 1. Arithmetic 2. Relational 3. Logical 4. Functional 5. String 3.2 Hierarchy of Operations The BASIC operators have an order of precedence: when several operations take place within the same program statement, some operations are done before others. Operations are executed in the following order: 1. Arithmetic operations a. Exponentiation (^) b. Negation (-) c. Multiplication and division (*,/) d. Integer division (\) e. Modulo arithmetic (MOD) f. Addition and subtraction (+,-) 2. Relational operations (=, >, <, <>, <=, >=) 3. Logical operations a. NOT b. AND c. OR d. XOR e. EQV f. IMP An exception to the order of operations listed above occurs when an expression has adjacent exponentiation and negation operators. In this case, the negation is done first. For example, the following statement prints the value .0625 (equivalent to 4^-2), not -16 (equivalent to -(4^2)): PRINT 4 ^ - 2 If the operations are different and are of the same level, the leftmost one is executed first and the rightmost last, as explained below. A = 3 + 6 / 12 * 3 - 2 'A = 2.5 The order of operations in the preceding example is as follows: Operation Result ────────────────────────────────────────────────────────────────────────── 6 / 12 0.5 0.5 * 3 1.5 3 + 1.5 4.5 4.5 - 2 2.5 ────────────────────────────────────────────────────────────────────────── In a series of additions or a series of multiplications, there is no fixed evaluation order. Either 3 + 5 or 5 + 6 may be calculated first in the following statement: C = 3 + 5 + 6 Usually this does not cause problems. However, it may cause a problem if you have a series of FUNCTION procedure calls: C = Incr(X) + Decr(X) + F(X) If any of the three FUNCTION procedures modify X or change shared variables, the result depends on the order in which BASIC does the additions. You can avoid the situation by assigning the results of the FUNCTION calls to temporary variables and then performing the addition: T1 = Incr(X) : T2 = Decr(X) : T3 = F(X) C = T1 + T2 + T3 3.3 Arithmetic Operators Parentheses change the order in which arithmetic operations are performed. Operations within parentheses are performed first. Inside parentheses, the usual order of operation is maintained. Here are some sample algebraic expressions and their BASIC counterparts: Algebraic Expression BASIC Expression ────────────────────────────────────────────────────────────────────────── X - Y ----- (X-Y)/Z Z XZ --- X*Y/Z Z X + Y ----- (X+Y)/Z Z (X<^>2)<^>Y (X^2)^Y X<^>YZ X^(Y*Z) X(-Y) X*(-Y) ────────────────────────────────────────────────────────────────────────── :BTGenerally, two consecutive operators must be separated by parentheses. Exceptions to this rule are * - , * +, ^ -, and ^ + . The last expression in the right-hand column above could also be written X*-Y. See the preceding section for information about the order in which arithmetic operations are performed. 3.3.1 Integer Division Integer division is denoted by the backslash (\) instead of the forward slash (/), which indicates floating-point division. Before integer division is performed, operands are rounded to integers or long integers, and thus must be greater than -2,147,483,648.5 and less than +2,147,483,647.5. The quotient of an integer division is truncated to an integer, as illustrated below: PRINT 10\4, 10/4, -32768.499\10, -32768.499/10 Output 2 2.5 -3276 -3276.8499 3.3.2 Modulo Arithmetic Modulo arithmetic is denoted by the modulus operator MOD. Modulo arithmetic provides the remainder, rather than the quotient, of an integer division, as in this example: X% = 10.4\4 REMAINDER% = INT(10.4) - 4*X% '10\4 = 2, with remainder 2 PRINT REMAINDER%, 10.4 MOD 4 Output 2 2 3.3.3 Overflow and Division by Zero Dividing by zero, raising zero to a negative power, and arithmetic overflow produce run-time errors. These errors can be trapped by an error-trapping routine. See Chapter 6, "Error and Event Trapping," in Programming in BASIC for more information about writing error-trapping routines. 3.4 Relational Operators Relational operators are used to compare two values, as shown in Table 3.1. The result of the comparison is either "true" (nonzero) or "false" (zero). This result can then be used to make a decision regarding program flow. Although BASIC treats any nonzero value as true, true is usually represented by -1. Table 3.1 Relational Operators and Their Functions Operator Relation Tested Expression ────────────────────────────────────────────────────────────────────────── = Equality X = Y < > Inequality X < > Y < Less than X < Y > Greater than X > Y <= Less than or equal to X <= Y = Greater than or equal to X >= Y ────────────────────────────────────────────────────────────────────────── When arithmetic and relational operators are combined in one expression, the arithmetic operations are always done first. For example, the following expression is true if the value of X + Y is less than the value of (T - 1)/Z: X + Y < (T - 1)/Z Be careful using relational operators with single- and double-precision values. Calculations may give extremely close but not identical results. In particular, avoid testing for identity between two values. For example, the PRINT statement in the following IF statement is not executed unless A! is exactly equal to 0.0: IF A! = 0.0 THEN PRINT "Exact result." When A! is an extremely small value, for example 1.0E-23, the PRINT statement is not executed. In addition, a compiled program (an .EXE file) may give different results than the same program run in the QuickBASIC environment. Files with the .EXE extension23 contain more efficient code that may change the way single- and double-precision values are compared. For example, the following fragment prints Equal when run in the environment, but prints Not Equal when compiled: B!=1.0 A!=B!/3.0 IF A!=B!/3.0 THEN PRINT "Equal" ELSE PRINT "Not Equal" Because the .EXE file version makes more extensive use of a math coprocessor chip (or coprocessor emulation), A! and B!/3.0 are slightly different values. You can avoid problems in comparisons by performing calculations outside comparisons. The following rewritten fragment produces the same results in the environment and as an .EXE file: B!=1.0 A!=B!/3.0 Tmp!=B!/3.0 IF A!=Tmp! THEN PRINT "Equal" ELSE PRINT "Not Equal" 3.5 Logical Operators Logical operators perform tests on multiple relations, bit manipulations, or Boolean operations and return a true (nonzero) or false (zero) value to be used in making a decision. ■ Examples IF D < 200 AND F < 4 THEN 80 WHILE I > 10 OR K < 0 . . . WEND IF NOT P THEN PRINT "Name not found" There are six logical operators in BASIC; they are listed in Table 3.2 in order of precedence: Table 3.2 BASIC Logical Operators Operator Meaning ────────────────────────────────────────────────────────────────────────── NOT Logical complement AND Conjunction OR Disjunction (inclusive "or") XOR Exclusive "or" EQV Equivalence IMP Implication ────────────────────────────────────────────────────────────────────────── Each operator returns results as indicated in Table 3.3. A "T" indicates a true value and an "F" indicates a false value. Operators are listed in order of operator precedence. Table 3.3 Values Returned by Logical Operations Values of Value Returned by Logical Operator X X X X X NOT AND OR XOR EQV IMP X Y X Y Y Y Y Y ────────────────────────────────────────────────────────────────────────── T T F T T F T T T F F F T T F F F T T F T T F T F F T F F F T T ────────────────────────────────────────────────────────────────────────── In an expression, logical operations (also known as Boolean operations) are performed after arithmetic and relational operations. The operands of logical operators must be in the range -2,147,483,648 to +2,147,483,647. Operands are converted to integers (or, if necessary, long integers) before the logical operation is done. (If the operands are not in this range, an error results.) If the operands are either 0 or -1, logical operators return 0 or -1 as the result, as in the following example. (Note the similarity of the output from this program to Table 3.3: "T" becomes -1 and "F" becomes 0.) ■ Example PRINT " X Y NOT AND OR "; PRINT "XOR EQV IMP" PRINT I = 10 : J = 15 X = (I = 10) : Y = (J = 15) 'X is true (-1); Y is true (-1) CALL TruthTable (X,Y) X = (I > 9) : Y = (J > 15) 'X is true (-1); Y is false (0) CALL TruthTable (X,Y) X = (I <> 10) : Y = (J < 16) 'X is false (0); Y is true (-1) CALL TruthTable (X,Y) X = (I < 10) : Y = (J < 15) 'X is false (0); Y is false (0) CALL TruthTable (X,Y) END SUB TruthTable(X,Y) STATIC PRINT X " " Y " ";NOT X " " X AND Y " " X OR Y; PRINT " " X XOR Y " " X EQV Y " " X IMP Y PRINT END SUB Output X Y NOT AND OR XOR EQV IMP -1 -1 0 -1 -1 0 -1 -1 -1 0 0 0 -1 -1 0 0 0 -1 -1 0 -1 -1 0 -1 0 0 -1 0 0 0 -1 -1 Logical operators compare each bit of the first operand with the corresponding bit in the second operand to compute the bit in the result; in these "bit-wise" comparisons, a 0 bit is equivalent to a "false" value (F) in Table 3.3, while a 1 bit is equivalent to a "true" value (T). It is possible to use logical operators to test bytes for a particular bit pattern. For example, the AND operator can be used to mask all but one of the bits of a status byte, while the OR operator can be used to merge two bytes to create a particular binary value. ■ Example PRINT 63 AND 16 PRINT -1 AND 8 PRINT 10 OR 9 PRINT 10 XOR 10, 'Always 0 PRINT NOT 10, NOT 11, NOT 0 'NOT X = -(X + 1) Output 16 8 11 0 -11 -12 -1 The first PRINT statement uses AND to combine 63 (111111 binary) and 16 (10000). When BASIC calculates the result of an AND, it combines the numbers bit by bit, producing a one only when both bits are one. Because the only bit that is a one in both numbers is the fifth bit, only the fifth bit in the result is a one. The result is 16, or 10000 in binary. In the second PRINT statement, the numbers -1 (binary 1111111111111111) and 8 (binary 1000) are combined using another AND operation. The only bit that is a one in both numbers is the fourth bit, so the result is 8 decimal or 1000 binary. The third PRINT statement uses an OR to combine 10 (binary 1010) and 9 (binary 1001). An OR produces a one bit whenever either bit is a one, so the result of the OR in the third PRINT is 11 (binary 1011). The XOR in the fourth PRINT combines the number 10 (1010 binary) with itself. The result is a zero because an XOR produces a one only when either, but not both, bits are one. Performing a NOT on a number changes all one bits to zeros and all zero bits to ones. Because of the way two's complement numbers work, taking the NOT of a value is the same as adding one to the number and then negating the number. In the final PRINT statement, the expression NOT 10 yields a result of -11. 3.6 Functional Operators A function is used in an expression to call a predetermined operation to be performed on an operand. For example, SQR is a functional operator used twice in the following assignment statement: A = SQR (20.25) + SQR (37) BASIC incorporates two kinds of functions: intrinsic and user-defined. Many predefined (intrinsic) functions are built into the language. Examples are the SQR (square root) and SIN (sine) functions. You may define your own functions with the FUNCTION...END FUNCTION construction and the older, obsolete DEF FN...END DEF construction. Such functions are defined only for the life of the program (unless they are in a Quick library) and are not part of the BASIC language. In addition to FUNCTION and DEF FN, BASIC allows you to define subprograms with SUB. For more information on defining your own functions and subprograms, see the appropriate entries in Chapter 4, "Programs and Modules," and Part 2, "Statement and Function Reference," in this manual, as well as Chapter 2, "SUB and FUNCTION Procedures," in Programming in BASIC. 3.7 String Operators A string expression consists of string constants, string variables, and other string expressions combined by string operators. There are two classes of string operations: concatenation and string function. The act of combining two strings is called concatenation. The plus symbol (+) is the concatenation operator for strings. For example, the following program fragment combines the string variables A$ and B$ to produce the output shown: A$ = "FILE": B$ = "NAME" PRINT A$ + B$ PRINT "NEW " + A$ + B$ Output FILENAME NEW FILENAME Strings can be compared using the following relational operators (see Table 3.1): < > = < > <= >= Note that these are the same relational operators used with numbers. String comparisons are made by taking corresponding characters from each string and comparing their ASCII codes. If the ASCII codes are the same for all the characters in both strings, the strings are equal. If the ASCII codes differ, the lower code number precedes the higher. If the end of one string is reached during string comparison, the shorter string is smaller if they are equal up to that point. Leading and trailing blanks are significant. The following are examples of true string expressions: "AA" < "AB" "FILENAME" = "FILE"+"NAME" "X&" > "X#" "CL " > "CL" "kg" > "KG" "SMYTH" < "SMYTHE" B$ < "9/12/78" 'where B$ = "8/12/85" String comparisons can be used to test string values or to alphabetize strings. All string constants used in comparison expressions must be enclosed in quotation marks. See Appendix A, "Keyboard Scan Codes and ASCII Character Codes," for more information about the ASCII codes. ──────────────────────────────────────────────────────────────────────────── Chapter 4 Programs and Modules 4.1 Modules 4.2 Procedures 4.2.1 FUNCTION Procedures 4.2.2 SUB Procedures 4.2.3 DEF FN Functions 4.3 Passing by Reference and Passing by Value 4.4 Recursion This chapter discusses the largest parts of a program──modules and procedures. The chapter describes how modules are organized and how BASIC procedures communicate with other parts of a program. Specifically, the chapter explains how to ■ Organize modules ■ Understand different kinds of QuickBASIC procedures ■ Pass arguments to a procedure ■ Write recursive code 4.1 Modules BASIC programs consist of one or more modules. A module is a source file that can be separately compiled. Declarations, executable statements──any BASIC statement──can appear in a module. A module may contain SUB and FUNCTION procedures, as well as code not directly part of a SUB or FUNCTION. Statements that are not part of a SUB or FUNCTION are called module-level code. Module-level code includes declarative statements like DIM and TYPE as well as error- and event-handling code. A program has one special module, the main module. The main module contains the entry point of the program (the place where the program starts running). Each program contains only one main module; module-level code it contains corresponds to what is often called the main program. 4.2 Procedures This section discusses the two newer QuickBASIC procedures: FUNCTION procedures and SUB procedures. It also covers the older DEF FN function and compares it with the newer procedures. See Chapter 2, "SUB and FUNCTION Procedures," in Programming in BASIC for examples and information about when to use different kinds of procedures. 4.2.1 FUNCTION Procedures FUNCTION procedures provide a powerful alternative to DEF FN functions. Like DEF FN functions, FUNCTION procedures are used in expressions and directly return a single value. There are, however, important differences. FUNCTION procedures pass values by reference, so a FUNCTION procedure can return additional values by changing variables in its argument list. In addition, FUNCTION procedures can be used recursively──a function can call itself (see Section 4.4 below for more information). Unlike DEF FN functions, a FUNCTION procedure may be used outside the module in which it is defined. You must include a DECLARE statement if you use a FUNCTION defined in another module. QuickBASIC automatically generates DECLARE statements for FUNCTION procedures defined and used in the same module. You can also enter the DECLARE yourself: DECLARE FUNCTION Log10(X) INPUT "Enter a number: ",Num PRINT "10 ^ Log10(";Num;") is" 10.0^Log10(Num) END ' Function to find log base 10 of a number using ' BASIC's built-in natural logarithm function. FUNCTION Log10 (X) STATIC Log10=LOG(X)/LOG(10.0) END FUNCTION FUNCTION procedures also differ from DEF FN functions in that they are not part of the module-level code. 4.2.2 SUB Procedures Unlike DEF FN functions and FUNCTION procedures, SUB is invoked as a separate statement: ' Print a message in the middle of the screen. CLS CALL PrntMsg(12,40,"Hello!") END ' Print message at the designated row and column. SUB PrntMsg(Row%,Col%,Message$) STATIC ' Save current cursor position. CurRow%=CSRLIN CurCol%=POS(0) ' Print the message at the location. LOCATE Row%,Col% : PRINT Message$; ' Restore cursor location. LOCATE CurRow%,CurCol% END SUB SUB procedures can be used to return multiple values to a calling routine and are not invoked as part of an expression. All SUB arguments are passed by reference. This allows SUB procedures to return values by changing variables in the argument list──the only way a SUB can return a value. You can invoke SUB procedures without using the CALL keyword if the SUB is declared: DECLARE SUB PrntMsg (Row%,Col%,Msg$) ' Print a message in the middle of the screen. CLS PrntMsg 12,40,"Hello!" 'Note the missing parentheses. END . . . SUB procedures can be used recursively──that is, you can write a SUB procedure that calls itself. 4.2.3 DEF FN Functions DEF FN functions are always part of a program's module-level code. For this reason, their use is more limited than that of SUB or FUNCTION procedures. Like FUNCTION procedures, DEF FN functions return single values and are used like built-in BASIC functions: ' Function to find log base 10 of a number using ' BASIC's built-in natural logarithm function. DEF FNLog10 (X) FNLog10=LOG(X)/LOG(10.0) END DEF INPUT "Enter a number: ",Num PRINT "10 ^ Log10(";Num;") is" 10.0^FNLog10(Num) END DEF FN function arguments are passed by value (see Section 4.3 below for more information). The name of a DEF FN function always begins with FN. In addition, DEF FN functions cannot be used recursively and must be defined before they are used. DEF FN functions cannot be called from outside the module in which they are defined. 4.3 Passing by Reference and Passing by Value BASIC uses two different ways of passing arguments to a procedure. The phrase "passing by reference," used with SUB and FUNCTION procedures, means the address of each argument is passed to the procedure by placing the address on the stack. The phrase "passing by value," used in DEF FN functions, indicates that the value of the argument is placed on the stack, rather than the address. Because the procedure does not have access to the variable when an argument is passed by value, the procedure cannot change the variable's value. Sometimes passing an argument by value to a SUB or FUNCTION is more convenient. You can simulate a pass by value by using an expression in the SUB call or FUNCTION invocation: Xcoordinate=Transform((A#)) Because(A#) is an expression, BASIC calculates its value, A#, and passes the address of a temporary location containing the value. An address is still passed, but because it is the address of a temporary location, the action simulates a pass by value. 4.4 Recursion QuickBASIC lets you write recursive SUB or FUNCTION procedures (procedures that call themselves). For example, the following program uses a recursive FUNCTION to reverse a string of characters: DECLARE FUNCTION Reverse$ (StringVar$) LINE INPUT "Enter string to reverse: ", X$ PRINT Reverse$(X$) END FUNCTION Reverse$ (S$) C$ = MID$(S$, 1, 1) IF C$ = "" THEN ' The first character is null, so return ' null--there's no more string left. Reverse$ = "" ELSE ' The reverse of a nonnull string is the first ' character appended to the reverse of the remaining ' string. Reverse$ = Reverse$(MID$(S$, 2)) + C$ END IF END FUNCTION Output Enter string to reverse: abcdefgh...tuvwxyz zyxwvut...hgfedcba Reverse$ reverses a string by first testing for the simplest case──a null string. If the string is null, then a null string is returned. If the string is not null──there are characters──then Reverse$ simplifies the problem. The reverse of a non-null string is the rest of the string (C$) with the first character of the string concatenated to it. So Reverse$ calls itself to reverse the rest of the string and when this is done concatenates the first character to the reversed string. Recursion can use a lot of memory because automatic variables inside the FUNCTION or SUB must be saved in order to restart the procedure when the recursive call is finished. Because automatic variables are saved on the stack, you may need to increase the stack size with the CLEAR statement to keep from running out of stack space. Use the FRE function to determine by how many bytes you need to adjust the stack size. ──────────────────────────────────────────────────────────────────────────── PART 2 STATEMENT AND FUNCTION REFERENCE ──────────────────────────────────────────────────────────────────────────── Part 2 is a dictionary of BASIC statements and functions. Each entry includes information on the statement's action or effect and its syntax. The statement's arguments, options, and typical usage are explained further under "Remarks." The "See Also" sections refer you to related statements. Differences from BASICA are included where appropriate. Finally, a sample program (or a reference to one) is included for each QuickBASIC statement or function so you can see exactly how it works. ──────────────────────────────────────────────────────────────────────────── ABS Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the absolute value of a numeric expression ■ Syntax ABS(numeric-expression) ■ Remarks The absolute value function returns the unsigned magnitude of its argument. For example, ABS(-1) and ABS(1) are both 1. ■ Example The following example finds an approximate value for a cube root. It uses ABS to find the difference between two guesses to see if the current guess is accurate enough. DEFDBL A-Z FUNCTION CubeRoot(Value,Precision) STATIC ' Make the first two guesses. X1=0.0# : X2=Value ' Go until the difference between two guesses is ' less than the required precision. DO UNTIL ABS(X1-X2) < Precision X=(X1+X2)/2.0# ' Adjust the guesses. IF X*X*X-Value < 0.0# THEN X1=X ELSE X2=X END IF LOOP CubeRoot=X END FUNCTION INPUT "Enter a value: ",X PRINT "The cube root is ";CubeRoot(X,.0000001#) ■ Output Enter a value: 27 The cube root is 2.999999972060323 ──────────────────────────────────────────────────────────────────────────── ASC Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns a numeric value that is the ASCII code for the first character in a string expression ■ Syntax ASC(stringexpression) ■ Remarks If stringexpression is null, ASC produces a run-time error message (Illegal function call). ■ See Also CHR$; Appendix A, "Keyboard Scan Codes and ASCII Character Codes" ■ Example The following example uses ASC to calculate a hash value──an index value for a table or file──from a string: CONST HASHTABSIZE=101 FUNCTION HashValue(S$,Size) STATIC TmpVal=0 FOR I=1 TO LEN(S$) ' Convert the string to a number by summing the values ' of individual letters. TmpVal=TmpVal+ASC(MID$(S$,I,1)) NEXT I ' Divide the sum by the size of the table. HashValue=TmpVal MOD Size END FUNCTION INPUT "Enter a name: ",Nm$ PRINT "The hash value is ";HashValue(Nm$,HASHTABSIZE) ■ Output Enter a name: Bafflegab The hash value is 66 ──────────────────────────────────────────────────────────────────────────── ATN Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the arctangent of a numeric expression (the angle whose tangent is equal to the numeric expression) ■ Syntax ATN(numeric-expression) ■ Remarks The numeric-expression can be of any numeric type. The result is given in radians and is in the range -π/2 to π/2 radians, where π=3.141593. ATN is evaluated by default in single precision unless numeric-expression is a double-precision value. Then ATN is evaluated in double precision. ■ Example The following example first finds the tangent of π/4 and then takes the arctangent of the value. The result is π/4. CONST PI=3.141592653 PRINT ATN(TAN(PI/4.0)), PI/4.0 ■ Output .78539816325 .78539816325 ──────────────────────────────────────────────────────────────────────────── BEEP Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Sounds the speaker ■ Syntax BEEP ■ Remarks The BEEP statement makes a sound through the loudspeaker. This statement makes the same sound as the following statement: PRINT CHR$(7) ■ Example The following example uses BEEP to indicate an error in the response: DO INPUT "Continue (Y or N)";Response$ R$=UCASE$ (MID$ (Response$,1,1)) IF R$="Y" OR R$="N" THEN EXIT DO BEEP LOOP ──────────────────────────────────────────────────────────────────────────── BLOAD Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Loads a memory-image file, created by BSAVE, into memory from an input file or device ■ Syntax BLOAD filespec «,offset» ■ Remarks The BLOAD statement takes the following arguments: Argument Description ────────────────────────────────────────────────────────────────────────── filespec A string expression containing the file specification. Input devices other than the keyboard (KYBD:) are supported. offset The offset of the address where loading is to start. ────────────────────────────────────────────────────────────────────────── The BLOAD statement allows a program or data saved as a memory-image file to be loaded anywhere in memory. A memory-image file is a byte-for-byte copy of what was originally in memory. ──────────────────────────────────────────────────────────────────────────── NOTE Programs written in earlier versions of BASIC no longer work if they use VARPTR to access numeric arrays. ──────────────────────────────────────────────────────────────────────────── The starting address for loading is determined by the specified offset and the most recent DEF SEG statement. If offset is omitted, the segment address and offset contained in the file (the address used in the BSAVE statement) are used. Thus, the file is loaded at the address used when saving the file. If you supply an offset, the segment address used is the segment set by the most recently executed DEF SEG statement. If there has been no DEF SEG statement, the BASIC data segment (DS) is used as the default. If the offset is a single-precision or double-precision number it is coerced to an integer. If the offset is a negative number in the range -1 to -32,768, it is treated as an unsigned 2-byte offset. ──────────────────────────────────────────────────────────────────────────── NOTE Because BLOAD does not perform an address-range check, it is possible to load a file anywhere in memory. You must be careful not to write over BASIC or the operating system. Since different screen modes use memory differently, do not load graphic images in a screen mode other than the one used when they were created. Also, because BASIC program code and data items are not always stored in the same locations as they were in BASICA, do not use BLOAD with files created by BASICA programs. ──────────────────────────────────────────────────────────────────────────── ■ Differences From Basica BLOAD does not support the cassette device. ■ See Also BSAVE, DEF SEG, VARPTR, VARSEG ■ Example This example uses BLOAD to retrieve a drawing saved in a disk file using BSAVE. See the example for BSAVE to see how the drawing was saved. DIM Cube(1 TO 675) ' Set the screen mode--the mode should be the same as the ' mode used to create the original drawing. SCREEN 1 ' Load the drawing into the array Cube. DEF SEG=VARSEG(Cube(1)) ' Get the array's segment. BLOAD "magcube.grh",VARPTR(Cube(1)) DEF SEG ' Restore the default segment. ' Put the drawing on the screen. PUT (80,10),Cube ──────────────────────────────────────────────────────────────────────────── BSAVE Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Transfers the contents of an area of memory to an output file or device ■ Syntax BSAVE filespec,offset,length ■ Remarks The BSAVE statement has the following arguments: Argument Description ────────────────────────────────────────────────────────────────────────── filespec A string expression containing the file or device name. Output devices other than the console (SCRN: and CONS:) are supported. offset The offset of the starting address of the area in memory to be saved. length The number of bytes to save. This is a numeric expression returning an unsigned integer in the range 0-65,535. ────────────────────────────────────────────────────────────────────────── The BSAVE statement allows data or programs to be saved as memory-image files on disk. A memory-image file is a byte-for-byte copy of what is in memory along with control information used by BLOAD to load the file. ──────────────────────────────────────────────────────────────────────────── NOTE Programs written in earlier versions of BASIC no longer work if they use VARPTR to access numeric arrays. ──────────────────────────────────────────────────────────────────────────── The starting address of the area saved is determined by the offset and the most recent DEF SEG statement. If no DEF SEG statement is executed before the BSAVE statement, the program uses the default BASIC data segment (DS). Otherwise, BSAVE begins saving at the address specified by the offset and by the segment set in the most recent DEF SEG statement. If the offset is a single- or double-precision floating-point value, it is coerced to an integer. If the offset is a negative number in the range -1 to -32,768, it is treated as an unsigned 2- byte offset. ──────────────────────────────────────────────────────────────────────────── NOTE Because different screen modes use memory differently, do not load graphic images in a screen mode other than the one used when the images were created. ──────────────────────────────────────────────────────────────────────────── ■ Differences From Basica BSAVE does not support the cassette device. ■ See Also BLOAD ■ Example This example draws a graphic and then saves it as a memory-image file. See the example for the BLOAD statement to see how the file would be retrieved. ' This program draws on the screen, stores the drawing in an ' array, and then saves the drawing in a disk file using BSAVE. ' DIM Cube(1 TO 675) SCREEN 1 ' Draw a white box. LINE (140,25)-(140+100,125),3,b ' Draw the outline of a magenta cube inside the box. DRAW "C2 BM140,50 M+50,-25 M+50,25 M-50,25" DRAW "M-50,-25 M+0,50 M+50,25 M+50,-25 M+0,-50 BM190,75 M+0,50" ' Save the drawing in the array Cube. GET (140,25)-(240,125),Cube ' Store the drawing in a disk file. Note: 2700 is the number ' of bytes in Cube (4 bytes per array element * 675). DEF SEG=VARSEG(Cube(1)) ' Set segment to array's segment. BSAVE "magcube.grh",VARPTR(Cube(1)),2700 DEF SEG ' Restore BASIC segment. ──────────────────────────────────────────────────────────────────────────── CALL Statement (BASIC Procedures) ──────────────────────────────────────────────────────────────────────────── ■ Action Transfers control to a BASIC SUB ■ Syntax 1 CALL name«( argumentlist )» ■ Syntax 2 name« argumentlist » ■ Remarks The CALL statement takes the following arguments: Argument Description ────────────────────────────────────────────────────────────────────────── name The name, limited to 40 characters, of the BASIC SUB being called. The name must appear in a SUB statement if the SUB is in the same module. argumentlist The variables or constants passed to the subprogram. Arguments in the list are separated by commas. Arguments passed by reference can be changed by the subprogram. ────────────────────────────────────────────────────────────────────────── If the argumentlist includes an array argument, the array is specified by the array name followed by empty parentheses: DIM IntArray(1 TO 20) . . . CALL ShellSort(IntArray()) When you use the CALL statement, the CALL keyword is optional. However, if you omit the CALL keyword, you must declare the procedure in a DECLARE statement. Notice also that when you omit the CALL keyword, you also omit the parentheses around the argument list. See Chapter 2 , "SUB and FUNCTION Procedures," in Programming in BASIC for more information. Arguments are passed by reference: the subprogram is given the address of the argument. This allows subprograms to change the argument values. BASIC can also pass arguments by value. The following statement calls a subprogram and passes a single argument by value: CALL SolvePuzzle((StartValue)) Because StartValue is in parentheses, BASIC evaluates it as an expression. The result is stored in a temporary location, and the address of the temporary location is passed to the SUB. Any change made by the subprogram SolvePuzzle is made only to the temporary location and not to the variable. ■ See Also CALL, CALLS (Non BASIC); CALL ABSOLUTE; DECLARE (BASIC) ■ Example The program below copies a series of files into a new file, the last file in the series entered from the command line. In the program, the BASIC subprogram PRINTOUT is called after first splitting the command line into separate file names and storing them in the array FILE$. The PRINTOUT subprogram copies the contents of the files to the final file in the list and to the standard output device (default is to your screen). DEFINT A-Z CONST MAXFILES=5, ARRAYDIM=MAXFILES+1 DIM File$(1 TO ARRAYDIM) ' Separate command line into arguments. CALL Comline (Numargs,File$(),ARRAYDIM) ' Test for too many or too few files. IF Numargs < 3 OR Numargs >MAXFILES THEN ' Too many or too few files. PRINT "Use more than 3 and fewer than";MAXFILES;"files" ELSE ' Send all files to Printout. CALL Printout(File$(),Numargs) END IF END ' See the example under COMMAND$ for the definition of ' Comline. Comline would appear here. SUB Printout(F$(1),N) STATIC ' Open target file. OPEN F$(N) FOR OUTPUT AS #3 ' Loop executes once for each file. ' Copy the first N-1 files onto the Nth file. FOR File = 1 TO N-1 OPEN F$(File) FOR INPUT AS #1 DO WHILE NOT EOF(1) 'Read file. LINE INPUT #1, Temp$ 'Write data to target file. PRINT #3, Temp$ PRINT Temp$ 'Write file to standard LOOP 'output. CLOSE #1 NEXT CLOSE END SUB ──────────────────────────────────────────────────────────────────────────── CALL, CALLS Statement (Non-BASIC Procedures) ──────────────────────────────────────────────────────────────────────────── ■ Action Transfers control to a procedure written in another language ■ Syntax 1 CALL name «(call-argumentlist)» ■ Syntax 2 name «call-argumentlist» ■ Syntax 3 CALLS name «(calls-argumentlist)» ■ Remarks The following list describes the parts of the CALL statement: Argument Description ────────────────────────────────────────────────────────────────────────── name The name of the procedure being called. A name is limited to 40 characters. call-argumentlist The variables or constants passed to the procedure. The syntax of a call-argumentlist is described below. calls-argumentlist A list containing the variables and constants that CALLS passes to the procedure. Entries are separated by commas. Note that these arguments are passed by reference as far addresses, using the segment and offset of the variable. You cannot use BYVAL or SEG in a calls-argumentlist. ────────────────────────────────────────────────────────────────────────── A call-argumentlist has the following syntax: ««{BYVAL|SEG}»argument»«,«{BYVAL|SEG}»argument»... If argument is an array, parentheses are required: ««{BYVAL|SEG}»argument«()»»«,«{BYVAL|SEG}»argument»... Part Description ────────────────────────────────────────────────────────────────────────── BYVAL Indicates the argument is passed by value, rather than by near reference (the default) SEG Passes the argument as a segmented (far) address argument A BASIC variable, array, or constant passed to the procedure ────────────────────────────────────────────────────────────────────────── CALLS is the same as using CALL with a SEG before each argument: every argument in a CALLS statement is passed as a segmented address. ──────────────────────────────────────────────────────────────────────────── NOTE The syntax described above does not correctly invoke a BASIC procedure──only procedures in other languages. See also the separate entry for CALL (BASIC). ──────────────────────────────────────────────────────────────────────────── If the argument list of either statement includes an array argument, the array is specified by the array name and a pair of parentheses: DIM IntArray(20) AS INTEGER . . . CALL ShellSort(IntArray() AS INTEGER) When you use the CALL statement, the CALL keyword is optional. However, when you omit CALL, you must declare the procedure in a DECLARE statement. Notice also that when you omit CALL, you also omit the parentheses around the argument list. See Chapter 2, "SUB and FUNCTION Procedures," in Programming in BASIC for more information about invoking procedures without the CALL keyword. The result of the BYVAL keyword differs from BASIC's pass by value: CALL Difference (BYVAL A,(B)) For the first argument, only the value of A is passed to Difference. In contrast, (B) is evaluated, a temporary location is created for the value, and the address of the temporary location is passed to Difference. You can use BASIC's pass by value for an argument, but you must write the procedure in the other language so the procedure accepts an address. ──────────────────────────────────────────────────────────────────────────── NOTE If name refers to an assembly-language procedure, it must be a PUBLIC name (symbol). PUBLIC names beginning with "$" and "_" may conflict with names used by the BASIC run-time system. Duplicate names cause a linker error message (symbol already defined) to be generated. ──────────────────────────────────────────────────────────────────────────── Be careful using the SEG keyword to pass arrays because BASIC may move variables in memory before the called routine begins execution. Anything in an argument list that causes memory movement may create problems. You can safely pass variables using SEG if the CALL statement's argument list contains only simple variables, arithmetic expressions, or arrays indexed without the use of intrinsic or user-defined functions. See Section 2.3.3, "Variable Storage Allocation," for a list of things that cause variable movement and for information about when to use near or far addresses for variables. ■ Differences From Basica Assembly-language programs invoked from BASICA that have string arguments must be changed because the string descriptor is now four bytes long. The four bytes are the low byte and high byte of the length followed by the low byte and high byte of the address. To locate the routine being called, the BASICA CALLS statement uses the segment address defined by the most recently executed DEF SEG statement. There is no need to use DEF SEG with the CALLS statement because all arguments are passed as far (segmented) addresses. ■ See Also CALL (BASIC); DECLARE (BASIC); DECLARE (Non-BASIC) ■ Example See the example for VARPTR. ──────────────────────────────────────────────────────────────────────────── CALL ABSOLUTE Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Transfers control to a machine-language procedure ■ Syntax CALL ABSOLUTE («argumentlist,»integervariable) ■ Remarks The CALL ABSOLUTE statement takes the following arguments: Argument Description ────────────────────────────────────────────────────────────────────────── argumentlist Optional arguments passed to a machine-language procedure. integervariable An integer variable containing a value that is the offset from the beginning of the current code segment, set by DEF SEG, to the starting location of the procedure. The integervariable argument is not passed to the procedure. Your program may need to execute a DEF SEG statement before executing CALL ABSOLUTE to set the code segment for the called routine. Using a noninteger value for integervariable produces unpredictable results. ────────────────────────────────────────────────────────────────────────── Arguments in argumentlist are passed to the machine-language program as offsets (near pointers) from the current data segment. Although arguments are passed as offsets, the machine-language program is invoked with a far call. ──────────────────────────────────────────────────────────────────────────── NOTE The CALL ABSOLUTE statement is provided to maintain compatibility with earlier versions of BASIC. Mixed-language programming using the CALL statement extensions and the new DECLARE statement provide a simpler way to use assembly language with BASIC. In order to use CALL ABSOLUTE you must start QuickBASIC with the correct Quick library, link your program with QB.LIB, or use the QB.QLB Quick library. See the disk-contents list for the locations of these files. ──────────────────────────────────────────────────────────────────────────── ■ Differences From Basica Assembly-language programs that are invoked from BASICA and that have string arguments must be changed because string descriptors are now four bytes long. The four bytes are the low byte and high byte of the string length followed by the low byte and high byte of the string address. ■ See Also CALL, CALLS (Non-BASIC) ■ Example The following example uses CALL ABSOLUTE to execute a machine-language program stored in an array: CONST nASMBYTES=14 ' This program prints a message indicating whether or not ' a math coprocessor is installed. ' It uses a machine-language program stored in an array ' to get the information from the operating system. 'AsmBytes is a label; nASMBYTES is a symbolic constant. DEFINT A-Z DIM AsmProg(1 TO (nASMBYTES/2)) ' The machine-language program stored as data to read into ' the array. DATA &H55 :'PUSH BP Save base pointer. DATA &H8B, &HEC :'MOV BP,SP Get our own. DATA &HCD, &H11 :'INT 11H Make the ROM-BIOS call. DATA &H8B, &H5E, &H06 :'MOV BX,[BP+6] Get argument address. DATA &H89, &H07 :'MOV [BX],AX Save list in argument. DATA &H5D :'POP BP Restore base pointer. DATA &HCA, &H02, &H00 :'RET 2 Pop argument off stack ' and make far return. ' Get the starting offset of the array. P=VARPTR(AsmProg(1)) ' Poke the machine-language program into the array. DEF SEG=VARSEG(AsmProg(1)) ' Change the segment. Restore AsmBytes FOR I=0 TO nASMBYTES-1 READ J POKE(P+I),J NEXT I ' Execute the program. The program expects a single integer ' argument. CALL ABSOLUTE(X%,VARPTR(AsmProg(1))) DEF SEG ' Restore the segment. ' X% now contains bit-encoded equipment list returned by DOS. ' Mask off all but the coprocessor bit (bit 2). CoProcessor=X% AND &H2 ' Print the appropriate message. IF CoProcessor=2 THEN PRINT "Math coprocessor present." ELSE PRINT "No math coprocessor." END IF END ──────────────────────────────────────────────────────────────────────────── CALL INT86OLD Statements ──────────────────────────────────────────────────────────────────────────── ■ Action Allows programs to perform DOS system calls ■ Syntax CALL INT86OLD (int_no,in_array(),out_array()) CALL INT86XOLD (int_no,in_array(),out_array()) ■ Remarks The CALL INTERRUPT statement provides an easier way to make DOS system calls. See the entry for CALL INTERRUPT for more information. The following list describes the arguments to INT86OLD and INT86XOLD: Argument Description ────────────────────────────────────────────────────────────────────────── int_no The DOS interrupt to perform. It is an integer between 0 and 255. See your DOS documentation for the interrupt numbers. in_array() An integer array specifying the register values when the interrupt is performed. INT86OLD uses an eight-element array, while INT86XOLD uses a ten-element array. Table R.1 lists the array elements and the corresponding registers. out_array() Contains the postinterrupt register values. It has the same structure as in_array. ────────────────────────────────────────────────────────────────────────── If an error occurs, int_no = -1 and values in out_array are unchanged. Errors are caused by int_no not being in the range 0-255. Table R.1 INT86OLD and INT86XOLD Register Values Array Element Register ────────────────────────────────────────────────────────────────────────── in_array(x) AX in_array(x+1) BX in_array(x+2) CX in_array(x+3) DX in_array(x+4) BP in_array(x+5) SI in_array(x+6) DI in_array(x+7) FLAGS in_array(x+8) DS in_array(x+9) ES ────────────────────────────────────────────────────────────────────────── The INT86OLD and INT86XOLD routines alter all registers except BP and DS. INT86OLD and INT86XOLD provide compatibility with older programs using INT86 and INT86X. Like the INT86 and INT86X routines, INT86OLD and INT86XOLD are distributed in a Quick library (QB.QLB) and in a conventional library (QB.LIB) on the distribution disks. The disks also contain a header file (QB.BI) for use with the procedures. See the disk-contents list for specific information. Note that INT86OLD and INT86XOLD do not require the use of VARPTR. Also, the register values are stored in the arrays beginning with the first array element. ■ Example The following example uses INT86OLD to open a file and place some text in it: ' Include header file for INT86OLD, etc. ' ¢INCLUDE:'QB.BI' DIM INARY%(7),OUTARY%(7) 'Define input and output 'arrays for INT86. ' ' Define register-array indices to ' make program easier to understand. CONST AX=0, BX=1, CX=2, DX=3, BP=4, SI=5, DI=6, FL=7 ' INARY%(AX) = &H3C00 'DOS function to create a file. INARY%(CX) = 0 'DOS attribute for created file. INARY%(DX) = SADD("FOO.TXT"+CHR$(0)) 'Pointer to file-name string 'with zero byte termination. CALL INT86OLD(&H21,INARY%(),OUTARY%()) 'Perform the creation. ' INARY%(BX) = OUTARY%(AX) 'Move created file handle for write. INARY%(AX) = &H4000 'DOS function to write to file. TEXT$ = "hello, world"+CHR$(13)+CHR$(10) 'Define text to write to file. INARY%(CX) = LEN(TEXT$) 'Get length of text string. INARY%(DX) = SADD(TEXT$) 'Get address of text string. CALL INT86OLD(&H21,INARY%(),OUTARY%()) 'Perform the write. ' INARY%(AX) = &H3E00 'DOS function to close a file. CALL INT86OLD(&H21,INARY%(),OUTARY%()) 'Perform the close. ──────────────────────────────────────────────────────────────────────────── CALL INTERRUPT Statements ──────────────────────────────────────────────────────────────────────────── ■ Action Allows BASIC programs to perform DOS system calls ■ Syntax CALL INTERRUPT (interruptnum,inregs,outregs) CALL INTERRUPTX (interruptnum,inregs,outregs) ■ Remarks The following list describes the arguments for the CALL INTERRUPT and CALL INTERRUPTX statements: Argument Description ────────────────────────────────────────────────────────────────────────── interruptnum The DOS interrupt number. It is an integer between 0 and 255. See your DOS documentation for information about interrupts. inregs The inregs variable contains the register values used when the interrupt is performed. It is declared as type RegType. The user-defined type RegType is described below. outregs The outregs variable contains the register values after the interrupt is performed. It is declared as type RegType. The user-defined type RegType is described below. ────────────────────────────────────────────────────────────────────────── The CALL INTERRUPT and CALL INTERRUPTX statements replace the INT86 and INT86X routines used in earlier versions of BASIC. They provide a more convenient way for BASIC programs to use DOS interrupts and services. The register values before and after the interrupt are passed in variables declared as type RegType. The following statement defines the RegType user-defined type: TYPE RegType AX AS INTEGER BX AS INTEGER CX AS INTEGER DX AS INTEGER BP AS INTEGER SI AS INTEGER DI AS INTEGER FLAGS AS INTEGER DS AS INTEGER ES AS INTEGER END TYPE Each element of the type corresponds to a CPU register. INTERRUPTX uses the values in the DS and ES registers. To use the current values of these registers, set the record elements to -1. CALL INTERRUPT and CALL INTERRUPTX are available in a Quick Library (QB.QLB) and in a conventional library (QB.LIB) on your distribution disks. There is also a header file (QB.BI) on the disks with the necessary declarations for using these procedures. See the disk-contents list for specific information. To use CALL INTERRUPT or CALL INTERRUPTX when running a program within the QuickBASIC environment, the Quick library QB.QLB must be loaded with QuickBASIC. ■ Example The following program uses CALL INTERRUPT to change a file's attribute list so the file does not appear when you use the DIR command from DOS: DECLARE SUB TestError (AXReg%, flags%) ' ¢INCLUDE: 'QB.BI' DEFINT A-Z DIM InRegs AS RegType, OutRegs AS RegType ' Get the file name and action to perform. CLS PRINT "Hidden File Program": PRINT INPUT "Enter file name: ", FileName$ DO INPUT "Hide or unhide (H or U): ", Action$ Action$ = UCASE$(Action$) LOOP WHILE Action$ <> "H" AND Action$ <> "U" ' Tack a null (zero) byte onto the end of the string for the ' DOS function. FileName$ = FileName$ + CHR$(0) ' Get the current file attribute. ' Current attribute comes back in OutRegs.AX. InRegs.ax = &H4300 InRegs.dx = SADD(FileName$) CALL INTERRUPT(&H21, InRegs, OutRegs) CALL TestError(OutRegs.ax, OutRegs.flags) ' Change the hidden attribute bit in the old attribute value. IF Action$ = "U" THEN InRegs.cx = OutRegs.cx AND &HFD ELSE InRegs.cx = OutRegs.cx OR &H2 END IF ' Set AX to indicate the Change Attribute DOS function. InRegs.ax = &H4301 CALL INTERRUPT(&H21, InRegs, OutRegs) CALL TestError(OutRegs.ax, OutRegs.flags) END ' If carry flag set, print error message and end program. SUB TestError (AXReg, flags) STATIC IF (&H1 AND flags) <> 0 THEN ' Get the error number out of AX. SELECT CASE AXReg AND &HF CASE 2 PRINT "File not found." CASE 3 PRINT "Path not found." CASE 5 PRINT "Access denied." CASE ELSE PRINT "Unrecognized error." END SELECT END END IF END SUB ──────────────────────────────────────────────────────────────────────────── CDBL Function ──────────────────────────────────────────────────────────────────────────── ■ Action Converts a numeric expression to a double-precision number ■ Syntax CDBL(numeric-expression) ■ Remarks The numeric-expression may be any numeric expression. This function has the same effect as assigning the numeric expression to a double-precision variable. Note that the results of CDBL are no more accurate than the original expression. The added digits of precision are not significant unless the expression is calculated with double-precision accuracy. ■ Example The following example demonstrates how the precision of the numeric expression affects the result of using CDBL: X = 7/9 X# = 7/9 PRINT X 'Both X# and CDBL(X) will be accurate to only 7 decimal 'places, because 7/9 is evaluated in single precision. PRINT X# PRINT CDBL(X) 'Accurate to 15 decimal places. PRINT 7#/9# ■ Output .7777778 .7777777910232544 .7777777910232544 .7777777777777778 ──────────────────────────────────────────────────────────────────────────── CHAIN Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Transfers control from the current program to another program ■ Syntax CHAIN filespec ■ Remarks The filespec is a string expression that identifies the program to which control is passed. The filespec may include a path specification. Programs running within the QuickBASIC environment assume a .BAS extension (if no extension is given) and cannot chain to executable files (files with a .COM or .EXE extension). Programs running outside the QuickBASIC environment assume an .EXE extension and cannot chain to QuickBASIC source files (files with a .BAS extension). You can pass variables between programs using the COMMON statement to set up a blank COMMON block. See the entry for COMMON. If you are compiling a program outside the QuickBASIC environment, note that the BCOM45.LIB library does not support COMMON. There are two ways to use COMMON with chained programs outside the environment: ■ Use the default (BRUN45.EXE) by compiling the programs using the option in the Make EXE dialog box called EXE Requiring BRUN45.EXE. ■ Use BRUN45.LIB by compiling from the command line without the /O option. The behavior of CHAIN and RUN is almost identical. The principal differences are that RUN closes all open files and does not support COMMON data blocks. ──────────────────────────────────────────────────────────────────────────── NOTE When programs use BRUN45.LIB, files are left open during chaining unless they are explicitly closed with a CLOSE statement. ──────────────────────────────────────────────────────────────────────────── ■ Differences From Basica BASICA assumes the extension .BAS. QuickBASIC assumes an extension of either .BAS or .EXE, depending on whether the program is run within the environment or compiled and run outside the environment. If you omit the file extension, CHAIN works the same in both QuickBASIC and BASICA. BASIC does not support the ALL, MERGE, or DELETE options available in BASICA, nor does it allow you to specify a line number. Without the line-number option, execution always starts at the beginning of the chained-to program. Thus, a chained-to program that chains back to a carelessly written chaining program can cause an endless loop. ■ See Also CALL (BASIC), COMMON, RUN ■ Example See example for the COMMON statement. ──────────────────────────────────────────────────────────────────────────── CHDIR Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Changes the current default directory for the specified drive ■ Syntax CHDIR pathspec ■ Remarks The pathspec is a string expression identifying the directory that is to become the default directory. The pathspec must have fewer than 64 characters. It has the following syntax: «drive:»«\»directory«\directory»... The argument drive: is an optional drive specification. If you omit drive, CHDIR changes the default directory on the current drive. CHDIR differs from the CHDIR command in DOS in two ways: 1. The BASIC statement cannot be shortened to CD. 2. There is no form of the CHDIR statement that returns the current directory. ──────────────────────────────────────────────────────────────────────────── The CHDIR statement changes the default directory but not the default drive. For example, if the default drive is C, then the following CHDIR statement changes the default directory on drive D, but the default drive is still C: ──────────────────────────────────────────────────────────────────────────── CHDIR "D:\TMP" ■ See Also MKDIR, RMDIR ■ Examples ' Makes \HOME\SALES the current directory on the default ' drive. CHDIR "\HOME\SALES" 'Changes the current directory to USERS on drive B; it does 'not, however, change the default drive to B. CHDIR "B:USERS" ──────────────────────────────────────────────────────────────────────────── CHR$ Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns a one-character string whose ASCII code is the argument ■ Syntax CHR$(code) ■ Remarks CHR$ is commonly used to send a special character to the screen or printer. For example, you can send a form feed (CHR$(12)) to clear the screen and return the cursor to the home position. CHR$ can also be used to include a double quote (") in a string: Msg$=CHR$(34)+"Quoted string"+CHR$(34) This line adds a double-quote character to the beginning and the end of the string. ■ See Also ASC; Appendix A, "Keyboard Scan Codes and ASCII Character Codes" ■ Example The following example uses CHR$ to display graphics characters in the extended character set: DEFINT A-Z ' Display two double-sided boxes. CALL DBox(5,22,18,40) CALL DBox(1,4,4,50) END ' Subroutine to display boxes on the screen. ' ' Parameters ' Urow%, Ucol% : Row and column of upper-left corner. ' Lrow%, Lcol% : Row and column of lower-right corner. ' Use constants for the extended character set graphic ' characters. CONST ULEFTC=201, URIGHTC=187, VERTICAL=186, HORIZONTAL=205 CONST LLEFTC=200, LRIGHTC=188 SUB DBox (Urow%, Ucol%, Lrow%, Lcol%) STATIC ' Draw top of box, starting with the upper left corner. LOCATE Urow%, Ucol% : PRINT CHR$(ULEFTC); LOCATE ,Ucol%+1 : PRINT STRING$(Lcol%-Ucol%,CHR$(HORIZONTAL)); LOCATE ,Lcol% : PRINT CHR$(URIGHTC); ' Draw the body of the box. FOR I=Urow%+1 TO Lrow%-1 LOCATE I,Ucol% : PRINT CHR$(VERTICAL); LOCATE ,Lcol% : PRINT CHR$(VERTICAL); NEXT I ' Draw the bottom of the box. LOCATE Lrow%, Ucol% : PRINT CHR$(LLEFTC); LOCATE ,Ucol%+1 : PRINT STRING$(Lcol%-Ucol%,CHR$(HORIZONTAL)); LOCATE ,Lcol% : PRINT CHR$(LRIGHTC); END SUB ──────────────────────────────────────────────────────────────────────────── CINT Function ──────────────────────────────────────────────────────────────────────────── ■ Action Converts a numeric expression to an integer by rounding the expression's fractional part ■ Syntax CINT(numeric-expression) ■ Remarks If numeric-expression is not in the range -32,768 to 32,767, the function produces a run-time error message that reads Overflow. CINT differs from the FIX and INT functions, which truncate, rather than round, the fractional part. See the example for the INT function for an illustration of the differences among these functions. ■ See Also CDBL, CSNG, FIX, INT ■ Example The following example converts an angle in radians to an angle in degrees and minutes: 'Set up constants for converting radians to degrees. CONST PI=3.141593, RADTODEG=180./PI INPUT "Angle in radians = ",Angle 'Get the angle in radians. Angle = Angle * RADTODEG 'Convert radian input to degrees. Min = Angle - INT(Angle) 'Get the fractional part. 'Convert fraction to value between 0 and 60. Min = CINT(Min * 60) Angle = INT(Angle) 'Get whole number part. IF Min = 60 THEN '60 minutes = 1 degree. Angle = Angle + 1 Min = 0 END IF PRINT "Angle equals" Angle "degrees" Min "minutes" ■ Output Angle in radians = 1.5708 Angle equals 90 degrees 0 minutes ──────────────────────────────────────────────────────────────────────────── CIRCLE Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Draws an ellipse or circle with a specified center and radius ■ Syntax CIRCLE «STEP» (x,y),radius«,«color»«,«start»«,«end»«,aspect»»»» ■ Remarks The following list describes the parts of the CIRCLE statement: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Part Description ────────────────────────────────────────────────────────────────────────── STEP The STEP option specifies that x and y are offsets relative to the current graphics cursor position. x,y The x- and y-coordinates for the center of the Part Description ────────────────────────────────────────────────────────────────────────── x,y The x- and y-coordinates for the center of the circle or ellipse. radius The radius of the circle or ellipse in the current coordinate system. color The attribute of the desired color. See the entries for the COLOR and SCREEN statements for more information. The default color is the foreground color. start, end The start and end angles, in radians, for the arc to draw. The start and end arguments are used to draw partial circles or ellipses. The arguments may range in value from -2π radians to 2π radians, where π = appx. 3.141593. The default value for start is 0 radians. The default value for end is 2π radians. Part Description ────────────────────────────────────────────────────────────────────────── If start or end is negative, then CIRCLE draws a radius to that point on the arc and treats the angle it were positive. The start angle can be less than the end angle. If you specify end but not start, the arc is drawn from 2π to end; if you specify start but not end, the statement draws an arc from start to zero. aspect The aspect ratio, or the ratio of the y-radius to the x-radius. The default value for aspect is the value required to draw a round circle in the screen mode. This value is calculated as follows: 4 * (ypixels/xpixels)/3 where xpixels by ypixels is the screen Part Description ────────────────────────────────────────────────────────────────────────── where xpixels by ypixels is the screen resolution. For example, in screen mode 1, where the resolution is 320 x 200, the default for aspect is 4 * (200/320)/3, or 5/6. If the aspect ratio is less than one, radius is the x-radius. If aspect is greater than one, radius is equal to the y-radius. ────────────────────────────────────────────────────────────────────────── To draw a radius to angle 0 (a horizontal line segment to the right), do not give the angle as -0; use a very small nonzero value instead as shown: ' Draws a pie-shaped one-quarter wedge of a circle: SCREEN 2 CIRCLE (200,100),60,,-.0001,-1.57 You may omit an argument in the middle of the statement, but you must include the argument's commas. In the following statement, the color argument has been omitted: CIRCLE STEP (150,200),94,,0.0,6.28 If you omit the last argument, you do not include the commas. The last point that CIRCLE references, after drawing, is the center of the ellipse or circle. You may use coordinates that are outside the screen or viewport. You may show coordinates as absolutes, or you may use the STEP option to show the position of the center point in relation to the previous point of reference. For example, if the previous point of reference is (10,10), then the following statement causes a circle to be drawn with radius 75 and center offset 10 from the current x coordinate and 5 from the current y coordinate. The circle's center is (20,15). CIRCLE STEP (10,5), 75 ■ Example The following program first draws a circle with the upper left quarter missing. It then uses relative coordinates to position a second circle within the missing quarter circle. Finally, it uses a different aspect ratio to draw a small ellipse inside the small circle. CONST PI=3.141593 SCREEN 2 ' Draw a circle with the upper-left quarter missing. ' Use negative numbers so radii are drawn. CIRCLE (320,100), 200,, -PI, -PI/2 ' Use relative coordinates to draw a circle within the missing ' quarter. CIRCLE STEP (-100,-42),100 ' Draw a small ellipse inside the circle. CIRCLE STEP(0,0), 100,,,, 5/25 ' Display the drawing until a key is pressed. LOCATE 25,1 : PRINT "Press any key to end."; DO LOOP WHILE INKEY$="" ──────────────────────────────────────────────────────────────────────────── CLEAR Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Reinitializes all program variables, closes files, and sets the stack size ■ Syntax CLEAR «,,stack» ■ Remarks The CLEAR statement performs the following actions: ■ Closes all files and releases the file buffers ■ Clears all COMMON variables ■ Sets numeric variables and arrays to zero ■ Sets all string variables to null ■ Reinitializes the stack and, optionally, changes its size The stack parameter sets aside stack space for your program. QuickBASIC takes the amount of stack space it requires, adds the number of bytes specified by stack, and sets the stack size to the result. ──────────────────────────────────────────────────────────────────────────── NOTE Two commas are used before stack to keep QuickBASIC compatible with BASICA. BASICA included an additional argument that set the size of the data segment. Because QuickBASIC automatically manages the data segment, the first parameter is no longer required . ──────────────────────────────────────────────────────────────────────────── If your program has deeply nested subroutines or procedures, or if you use recursive procedures, you may want to use a CLEAR statement to increase the stack size. You may also want to increase the stack size if your procedures have a large number of arguments. Clearing the stack destroys the return addresses placed on the stack during the execution of a GOSUB. This makes it impossible to execute a RETURN statement correctly and produces a RETURN without GOSUB run-time error message. Using a CLEAR statement in a SUB or FUNCTION produces a run-time error message that reads Illegal function call. ■ Differences From Basica BASICA programs using CLEAR may require modification. In BASICA programs, any DEF FN functions or data types declared with DEFtype statements are lost after a CLEAR statement. In compiled programs, this information is not lost because these declarations are fixed at compile time. ■ See Also FRE, SETMEMGT ■ Example The following statement clears all program variables and sets aside 2,000 bytes on the stack for the program: CLEAR ,,2000 ──────────────────────────────────────────────────────────────────────────── CLNG Function ──────────────────────────────────────────────────────────────────────────── ■ Action Converts a numeric expression to a long (4-byte) integer by rounding the fractional part of the expression ■ Syntax CLNG(numeric-expression) ■ Remarks If numeric-expression is not in the range -2,147,483,648 to 2,147,483,647, the function produces an error message that reads Overflow. ■ Example The following example shows how CLNG rounds before converting the number: A=32767.45 B=32767.55 PRINT CLNG(A); CLNG(B) ■ Output 32767 32768 ──────────────────────────────────────────────────────────────────────────── CLOSE Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Concludes I/O to a file or device ■ Syntax CLOSE ««#» filenumber «,«#» filenumber»...» ■ Remarks The CLOSE statement complements the OPEN statement. The filenumber is the number under which the file was opened. A CLOSE statement with no arguments closes all open files and devices. The association of a file with a file number ends when a CLOSE statement is executed. You may then reopen the file using the same or a different file number. Once you close a file, you may use that file's number for any unopened file. A CLOSE for a file or device that was opened for sequential output writes the final buffer of output to that file or device. CLOSE releases all buffer space associated with the closed file or files. The CLEAR, END, RESET, RUN, and SYSTEM statements automatically close all files. ■ Example See the example for CALL (BASIC). ──────────────────────────────────────────────────────────────────────────── CLS Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Clears the screen ■ Syntax CLS «{0 | 1 | 2}» ■ Remarks There are several ways to use the CLS statement, as described in the following list: Statement Description ────────────────────────────────────────────────────────────────────────── CLS 0 Clears the screen of all text and graphics. CLS 1 Clears only the graphics viewport if a VIEW statement has been executed. Otherwise, CLS 1 clears the entire screen. CLS 2 Clears only the text viewport, leaving the bottom screen line (line 25, 30, 43, or 60 depending on the screen mode) unchanged. CLS Clears either the graphics viewport or the text viewport. If the graphics viewport is active, then CLS with no argument clears only the viewport. If the graphics viewport is inactive, then CLS clears the text viewport and refreshes the function key display line (the bottom screen line). ────────────────────────────────────────────────────────────────────────── The CLS statement also returns the cursor to the home position in the top left corner of the screen. ■ See Also VIEW, VIEW PRINT, WINDOW ■ Example The following program draws random circles in a graphics viewport and prints in a text viewport. The graphics viewport is cleared after 30 circles have been drawn. The program clears the text viewport after printing to it 45 times. RANDOMIZE TIMER SCREEN 1 ' Set up a graphics viewport with a border. VIEW (5,5)-(100,80),3,1 ' Set up a text viewport. VIEW PRINT 12 TO 24 ' Print a message on the screen outside the text viewport. LOCATE 25,1 : PRINT "Press any key to stop." Count=0 DO ' Draw a circle with a random radius. CIRCLE (50,40),INT((35-4)*RND+5),(Count MOD 4) ' Clear the graphics viewport every 30 times. IF (Count MOD 30)=0 THEN CLS 1 PRINT "Hello. "; ' Clear the text viewport every 45 times. IF (Count MOD 45)=0 THEN CLS 2 Count=Count+1 LOOP UNTIL INKEY$<>"" ──────────────────────────────────────────────────────────────────────────── COLOR Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Selects display colors ■ Syntax COLOR «foreground»«,«background»«,border»» Screen mode 0 COLOR «background»«,palette» Screen mode 1 COLOR «foreground»«,background» Screen modes 7-10 COLOR «foreground» Screen modes 12-13 ■ Remarks With the COLOR statement, you can set the foreground and background colors for the display. In screen mode 0 a border color can also be selected. In screen mode 1 no foreground color can be selected, but one of two four-color palettes can be selected for use with graphics statements. In screen modes 12-13 only the foreground color can be set. The values of foreground in screen modes 7-10, 12, and 13 are attribute numbers (not color numbers) and display the color assigned to that attribute. See the PALETTE statement for a description of attributes. The COLOR statement does not determine the range of available colors. The combination of adapter, display, and the mode set by the SCREEN statement determine the color range. See the SCREEN statement for more information. The different syntaxes and their effects in different screen modes are described below: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Screen Mode Description ────────────────────────────────────────────────────────────────────────── Screen Mode Description ────────────────────────────────────────────────────────────────────────── 0 Modifies the current default text foreground and background colors and the screen border. The foreground color must be an integer expression in the range 0-31. It determines the "foreground" color in text mode──the default color of text. Sixteen colors can be selected with the integers 0-15. You can select a blinking version of a color by adding 16 to the color number. For example, a blinking color 7 is equal to 7 + 16, or 23. The background color is an integer expression in the range 0-7 and is the color of the background for each text character. Blinking background colors are not supported. The border color──the color used to draw the screen border──is an integer expression in the range 0-15. The IBM Enhanced Graphics Adapter Screen Mode Description ────────────────────────────────────────────────────────────────────────── range 0-15. The IBM Enhanced Graphics Adapter (EGA), the IBM Video Graphics Array adapter (VGA), and the IBM Multicolor Graphics Array adapter (MCGA) do not support the border argument. 1 In mode 1, the COLOR statement has a unique syntax that includes a palette argument that is an odd or even integer expression in the range 0 to 255. This argument determines which of two sets of colors to use when displaying particular color numbers. The default colors for the palette parameter are equivalent to the following PALETTE statements on a system equipped with an EGA: COLOR ,0 'Same as the next three 'PALETTE statements. Screen Mode Description ────────────────────────────────────────────────────────────────────────── 'PALETTE statements. PALETTE 1,2 'Attribute 1 = color 2 (green) PALETTE 2,4 'Attribute 2 = color 4 (red) PALETTE 3,6 'Attribute 3 = color 6 (yellow) COLOR ,1 'Same as the next three 'PALETTE statements. PALETTE 1,3 'Attribute 1 = color 3 (cyan) PALETTE 2,5 'Attribute 2 = color 5 (magenta) PALETTE 3,7 'Attribute 3 = color 7 (white) Note that in screen mode 1, a COLOR statement overrides previous PALETTE statements. 2 An Illegal function call message results if COLOR is used in this mode. 7-10 In these modes, no border color can be specified. The graphics background is given by the Screen Mode Description ────────────────────────────────────────────────────────────────────────── The graphics background is given by the background color number, which must be in the range of valid color numbers for the screen mode. The foreground color argument is the default line-drawing color. In screen modes 7 to 10 foreground is an attribute number, while background is a color number. See the SCREEN statement for more details. 11 Use the PALETTE statement to set color in screen mode 11. 12, 13 No background color can be specified in these modes. The foreground argument is the attribute used for the foreground graphics color. The attribute must be in the correct range for the screen mode. See the SCREEN statement for more information. ────────────────────────────────────────────────────────────────────────── Screen Mode Description ────────────────────────────────────────────────────────────────────────── ────────────────────────────────────────────────────────────────────────── Arguments that are outside the valid ranges produce error messages that read Illegal function call. The foreground can be the same color as the background, making displayed characters invisible. The default background is black, or color number 0 for all display hardware configurations and all screen modes. In screen modes 12 and 13 you can set the background color by assigning a color to attribute 0 with a PALETTE statement. For example, to make the background color 8224 (a light violet), you would use the following PALETTE statement: PALETTE 0,8224 In screen mode 11 you can set both the foreground and background color by assigning a color to attribute 0 with a PALETTE statement. With an EGA, VGA, or MCGA installed, the PALETTE statement gives you flexibility in assigning different display colors to the actual color-number ranges for the foreground, background, and border colors discussed above. See the PALETTE statement reference pages for more details. ■ See Also PAINT, PALETTE, SCREEN ■ Examples The following series of examples show COLOR statements and their effects in the various screen modes: SCREEN 0 'foreground=1, background=2, border=3 COLOR 1, 2, 3 SCREEN 1 'background=1, even palette number COLOR 1,0 'background=2, odd palette number COLOR 2,1 ──────────────────────────────────────────────────────────────────────────── COM Statements ──────────────────────────────────────────────────────────────────────────── ■ Action Enables, disables, or inhibits event trapping of communications activity on a specified port ■ Syntax COM(n) ON COM(n) OFF COM(n) STOP ■ Remarks The parameter n is the number of the communications port; n can be either 1 or 2. The COM ON statement enables communications event trapping. If a character arrives at a communications port after a COM ON statement, then the subroutine specified in the ON COM statement is executed. COM OFF disables communications event trapping. No communications trapping takes place until another COM ON statement is executed. Events occurring while trapping is off are ignored. COM STOP inhibits communications event trapping so no trapping takes place until a COM ON statement is executed. Events occurring while trapping is inhibited are remembered and processed when the next COM ON statement is executed. See Chapter 6, "Error and Event Trapping," in Programming in BASIC for an outline of event trapping. ■ See Also ON event ■ Example See the event-trapping examples in Chapter 6, "Error and Event Trapping," in Programming in BASIC for an illustration of how to do event trapping. ──────────────────────────────────────────────────────────────────────────── COMMAND$ Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the command line used to invoke the program ■ Syntax COMMAND$ ■ Remarks The COMMAND$ function returns the complete command line entered after your BASIC program name, including optional parameters. COMMAND$ removes all leading blanks from the command line and converts all letters to uppercase (capital letters). The COMMAND$ function can be used in stand-alone executable files or, if you are executing from the QuickBASIC environment, by using the /CMD command line option or by selecting Modify COMMAND$ on the Run menu. ■ Example The Comline subprogram in the following example breaks the command line into separate arguments and stores them in an array. Each argument is separated from adjoining arguments by one or more blanks or tabs on the command line. ' Default variable type is integer in this module. DEFINT A-Z ' Declare the Comline subprogram, as well as the number and ' type of its parameters. DECLARE SUB Comline(N, A$(),Max) DIM A$(1 TO 15) ' Get what was typed on the command line. CALL Comline(N,A$(),10) ' Print out each part of the command line. PRINT "Number of arguments = ";N PRINT "Arguments are: " FOR I=1 TO N : PRINT A$(I) : NEXT I ' Subroutine to get command line and split into arguments. ' Parameters: NumArgs : Number of command line args found. ' Args$() : Array in which to return arguments. ' MaxArgs : Maximum number of arguments array ' can return. SUB Comline(NumArgs,Args$(),MaxArgs) STATIC CONST TRUE=-1, FALSE=0 NumArgs=0 : In=FALSE ' Get the command line using the COMMAND$ function. Cl$=COMMAND$ L=LEN(Cl$) ' Go through the command line a character at a time. FOR I=1 TO L C$=MID$(Cl$,I,1) 'Test for character being a blank or a tab. IF (C$<>" " AND C$<>CHR$(9)) THEN ' Neither blank nor tab. ' Test to see if you're already ' inside an argument. IF NOT In THEN ' You've found the start of a new argument. ' Test for too many arguments. IF NumArgs=MaxArgs THEN EXIT FOR NumArgs=NumArgs+1 In=TRUE END IF ' Add the character to the current argument. Args$(NumArgs)=Args$(NumArgs)+C$ ELSE ' Found a blank or a tab. ' Set "Not in an argument" flag to FALSE. In=FALSE END IF NEXT I END SUB The following is a sample command line and output for a stand-alone executable file (assumes program name is arg.exe): arg one two three four five six ■ Output Number of arguments = 6 Arguments are: ONE TWO THREE FOUR FIVE SIX ──────────────────────────────────────────────────────────────────────────── COMMON Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Defines global variables for sharing between modules or for chaining to another program ■ Syntax COMMON «SHARED» «/blockname/» variablelist ■ Remarks The following list describes the parts of the COMMON statement: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Part Description ────────────────────────────────────────────────────────────────────────── SHARED An optional attribute indicating that the variables are to be shared with all SUB or FUNCTION procedures in the module. SHARED can eliminate the need for a SHARED statement inside SUB or FUNCTION procedures. blockname A valid BASIC identifier (up to 40 characters) used to identify a group of variables. Use a blockname to share only specific groups of variables. When a blockname is used, the COMMON block is a named COMMON block. When blockname is omitted, the block is a blank COMMON block. Items in a named COMMON block are not preserved across a chain to a new program. See "Using Named COMMON" and "Using COMMON with Chain," below. Part Description ────────────────────────────────────────────────────────────────────────── variablelist A list of variables to be shared between modules or chained-to programs. The same variable may not appear in more than one COMMON statement in a module. ────────────────────────────────────────────────────────────────────────── A variablelist has the following syntax: variable«( )»«AS type»«, variable«( )»«AS type»»... The following list describes the parts of a variablelist: Argument Description ────────────────────────────────────────────────────────────────────────── variable Any valid BASIC variable name. AS type Declares variable to be of type type. The type may be INTEGER, LONG, SINGLE, DOUBLE, STRING, or a user-defined type. ────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── NOTE Older versions of BASIC required the number of dimensions to appear after the name of a dynamic array in a COMMON statement. The number of dimensions is no longer required, although QuickBASIC accepts the older syntax to maintain compatibility with earlier versions. ──────────────────────────────────────────────────────────────────────────── A COMMON statement establishes storage for variables in a special area that allows them to be shared between modules or with other programs invoked with a CHAIN statement. Because COMMON statements establish global variables for an entire program, they must appear before any executable statements. All statements are executable, except the following: ■ COMMON ■ CONST ■ DATA ■ DECLARE ■ DEFtype ■ DIM (for static arrays) ■ OPTION BASE ■ REM ■ SHARED ■ STATIC ■ TYPE...END TYPE ■ All metacommands Variables in COMMON blocks are matched by position and type, not by name. Thus, variable order is significant in COMMON statements. In the following fragment, it is the order of the variables in the COMMON statements that links the variables, not the names: ' Main program. COMMON A, D, E A = 5 : D = 8 : E = 10 . . . ' Common statement in another module. COMMON A, E, D 'A = 5, E = 8, D = 10 . . . Both static and dynamic arrays are placed in COMMON by using the array name followed by parentheses. A static array must be dimensioned with integer-constant subscripts in a DIM statement preceding the COMMON statement. A dynamic array must be dimensioned in a later DIM or REDIM statement. The elements of a dynamic array are not allocated in the COMMON block. Only an array descriptor is placed in common. (See Chapter 2, "Data Types," in this manual and Appendix F, "Metacommands," in Programming in BASIC for more information about static and dynamic arrays.) The size of a common area can be different from that in another module or chained program if a blank COMMON block has been used. When a BASIC program shares COMMON blocks with a routine in the user library, the calling program may not redefine the COMMON block to a larger size. Errors caused by mismatched COMMON statements are subtle and difficult to find. An easy way to avoid this problem is to place COMMON declarations in a single "include" file and use the ¢INCLUDE metacommand in each program. See Appendix F, "Metacommands," in Programming in BASIC for a discussion of ¢INCLUDE. The following program fragment shows how to use the ¢INCLUDE metacommand to share a file containing COMMON statements among programs: 'This file is menu.bas. '¢INCLUDE:'COMDEF.BI' . . . CHAIN "PROG1" END 'This file is prog1.bas. '¢INCLUDE:'COMDEF.BI' . . . END 'This file is comdef.bi. DIM A(100),B$(200) COMMON I,J,K,A() COMMON A$,B$(),X,Y,Z 'End comdef.bi. The next three sections discuss using named COMMON blocks, using the SHARED keyword, and using COMMON when chaining programs. USING NAMED COMMON A named COMMON block provides a convenient way to group variables so that different modules have access only to the common variables that they need. The following program, which calculates the volume and density of a rectangular prism, uses named COMMON blocks to share different sets of data with two subprograms. The subprogram VOLUME needs to share only the variables representing the lengths of the sides (in COMMON block SIDES). The subprogram DENSITY also needs variables representing the weight (in COMMON block WEIGHT). 'Main program. DIM S(3) COMMON /Sides/ S() COMMON /Weight/ C C=52 S(1)=3:S(2)=3:S(3)=6 CALL Volume CALL Density END 'Subprogram VOLUME in a separate module. DIM S(3) COMMON SHARED /Sides/ S() SUB Volume STATIC Vol=S(1)*S(2)*S(3) PRINT "The volume is "; Vol END SUB 'Subprogram DENSITY in a separate module. DIM S(3) COMMON SHARED /Sides/ S() COMMON SHARED /Weight/ W SUB Density STATIC Vol=S(1)*S(2)*S(3) Dens=W/Vol PRINT "The density is "; Dens END SUB ──────────────────────────────────────────────────────────────────────────── NOTE Named COMMON blocks are not preserved across chained programs. Use blank COMMON blocks to pass variables to a chained program. ──────────────────────────────────────────────────────────────────────────── USING COMMON WITH CHAIN The COMMON statement provides the only way to pass the values of variables directly to a chained program. To pass variables, both programs must contain COMMON statements. Remember that variable order and type are significant, not variable names. The order and type of variables must be the same for all COMMON statements communicating between chaining programs. Although the order and type of variables is critical for making sure the right values are passed, the COMMON blocks do not have to be the same size. If the COMMON block in the chained-to program is smaller than the COMMON block in the chaining program, the extra COMMON variables in the chaining program are ignored. If the size of the COMMON block in the chained-to program is larger, then additional COMMON numeric variables are initialized to zero. Additional string variables are initialized to null strings. Static arrays passed in COMMON by the chaining program must be declared as static in the chained-to program. Similarly, dynamic arrays placed in common by the chaining program must be dynamic in the chained-to program. ──────────────────────────────────────────────────────────────────────────── NOTE To use COMMON with CHAIN when you are compiling outside the BASIC environment, you must use the BRUN45.EXE module. This module is used when you compile from the command line without the /O option or when you use the option from the Make EXE dialog box called EXE Requiring BRUN45.EXE. ──────────────────────────────────────────────────────────────────────────── ■ See Also CALL (BASIC), CHAIN, FUNCTION, SUB ■ Examples The following example uses a COMMON statement to pass variables between two chained programs. The first program reads in a series of numeric values, stores the values in an array, and then chains to the other program. The second program finds and prints the average of the values. DIM Values(1 TO 50) COMMON Values(), NumValues PRINT "Enter values one per line. Enter END to quit." NumValues=0 DO INPUT "-> ",N$ IF I>=50 OR UCASE$(N$)="END" THEN EXIT DO NumValues=NumValues+1 Values(NumValues)=VAL(N$) LOOP CHAIN "average" The program named average appears as follows (notice that average is an entirely separate program): DIM X(1 TO 50) COMMON X(), N IF N>0 THEN Sum=0 FOR I=1 TO N Sum=Sum+X(I) NEXT I PRINT "The average of the values is";Sum/N END IF ──────────────────────────────────────────────────────────────────────────── CONST Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Declares symbolic constants for use in place of numeric or string values ■ Syntax CONST constantname = expression «,constantname = expression»... ■ Remarks Argument Description ────────────────────────────────────────────────────────────────────────── constantname A name following the same rules as a BASIC variable name. You may add to the name a type-declaration character (%, &, !, #, or $) to indicate its type, but this character is not part of the name. expression An expression consisting of literals (such as 1.0), other constants, or any of the arithmetic and logical operators except exponentiation (^). You may also use a single literal string such as "Error on input". You cannot use string concatenation, variables, user-defined functions, or intrinsic functions like SIN or CHR$ in expressions assigned to constants. ────────────────────────────────────────────────────────────────────────── If you use a type-declaration character in the name, you may omit the character when the name is used, as shown in the following example: CONST MAXDIM% = 250 . . . DIM AccountNames$(MAXDIM) If you omit the type-declaration character, the constant is given a type based on the expression in the CONST statement. Strings always yield a string constant. With numeric expressions, the expression is evaluated and the constant is given the simplest type that can represent the constant. For example, if the expression gives a result that can be represented as an integer, the constant is given an integer type. ──────────────────────────────────────────────────────────────────────────── NOTE Names of constants are not affected by DEFtype statements such as DEFINT. A constant's type is determined either by an explicit type-declaration character or by the type of the expression. ──────────────────────────────────────────────────────────────────────────── Constants must be defined before they are referenced. The following example produces an error because the constant ONE is not defined before it is used to define TWO (constants are defined from left to right): CONST TWO = ONE + ONE, ONE = 1 Constants declared in a SUB or FUNCTION are local to the SUB or FUNCTION. A constant declared outside a procedure is defined throughout the module. You can use constants anywhere that you would use an expression. A common programming practice is to use a statement like the following (recall that any nonzero value represents "true"): TRUE=-1 Constants offer several advantages over using variables for constant values: ■ Constants need to be defined only once for an entire module. ■ Constants cannot be inadvertently changed. ■ In stand-alone programs, using constants produces more efficient code than using variables. ■ Constants make programs easier to modify. ■ Examples The following program uses the CONST statement to declare symbolic constants for the ASCII values of nonprinting characters such as tab and line feed: ' This program counts words, lines, and characters. ' A word is any sequence of nonblank characters. DEFINT a-z CONST BLANK = 32, ENDFILE = 26, CR = 13, LF = 10 CONST TABC = 9, YES = -1, NO = 0 ' Get the file name from the command line. FileName$=COMMAND$ IF FileName$="" THEN INPUT "Enter input file name: ",FileName$ IF FileName$="" THEN END END IF OPEN FileName$ FOR INPUT AS #1 Words=0 Lines=0 Characters=0 ' Set a flag to indicate you're not looking at a ' word, then get the first character from the file. InaWord=NO DO UNTIL EOF(1) C=ASC(INPUT$(1,#1)) Characters=Characters+1 IF C=BLANK or C=CR or C=LF or C=TABC THEN ' If the character is a blank, carriage return, ' line feed, or tab, you're not in a word. IF C=CR THEN Lines=Lines+1 InaWord=NO ELSEIF InaWord=NO THEN ' The character is a printing character, ' so this is the start of a word. ' Count the word and set the flag. InaWord=YES Words=Words+1 END IF LOOP PRINT Characters, Words, Lines END Constants also make programs easier to modify. The following program fragment declares a single constant to dimension a series of arrays. To increase or decrease the size of the arrays, it is necessary to change only the value in the CONST statement. CONST MAXCUSTOMERS = 250 . . . DIM AccountNumber$(MAXCUSTOMERS), Balance(MAXCUSTOMERS) DIM Contact$(MAXCUSTOMERS), PastDueAmount(MAXCUSTOMERS) . . . ──────────────────────────────────────────────────────────────────────────── NOTE Using a variable here, instead of a symbolic constant, makes the arrays dynamic arrays. Using a symbolic constant, as in the previous example, declares these arrays as static arrays. See Chapter 2, "Data Types," in this manual and Appendix F, "Metacommands," in Programming in BASIC for more information about static and dynamic arrays. ──────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── COS Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the cosine of an angle given in radians ■ Syntax COS(numeric-expression) ■ Remarks The expression, numeric-expression, can be any numeric type. By default, the cosine is calculated in single precision. If numeric-expression is a double-precision value, the cosine is calculated in double precision. You can convert an angle measurement from degrees to radians by multiplying the degrees by π/180, where π = 3.141593. ■ See Also ATN, SIN, TAN ■ Example The following program plots the graph of the polar equation r = nq for values of n from 0.1-1.1. This program uses the conversion factors x = cos(q) and y = sin(q) to change polar coordinates to Cartesian x,y coordinates. The figure plotted is sometimes known as the Spiral of Archimedes. CONST PI = 3.141593 'Gray background. SCREEN 1 : COLOR 7 'Define window large enough for biggest spiral. WINDOW (-4,-6)-(8,2) 'Draw line from origin to the right. LINE (0,0)-(2.2*PI,0),1 'Draw ten spirals. FOR N = 1.1 TO .1 STEP -.1 'Plot starting point. PSET (0,0) FOR Angle = 0 TO 2*PI STEP .04 'Polar equation for spiral. R = N * Angle 'Convert polar coordinates to Cartesian coordinates. X = R * COS(Angle) Y = R * SIN(Angle) 'Draw line from previous point to new point. LINE -(X,Y),1 NEXT NEXT ──────────────────────────────────────────────────────────────────────────── CSNG Function ──────────────────────────────────────────────────────────────────────────── ■ Action Converts a numeric expression to a single-precision value ■ Syntax CSNG(numeric-expression) ■ Remarks The CSNG function has the same effect as assigning the numeric-expression to a single-precision variable. CSNG rounds the value, if necessary, before converting it. ■ See Also CDBL, CINT ■ Example The following example shows how CSNG rounds before converting the value: A#=975.3421115# B#=975.3421555# PRINT A#; CSNG(A#); B#; CSNG(B#) ■ Output 975.3421115 975.3421 975.3421555 975.3422 ──────────────────────────────────────────────────────────────────────────── CSRLIN Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the current line (row) position of the cursor ■ Syntax CSRLIN ■ Remarks To return the current column position, use the POS function. ■ See Also LOCATE, POS ■ Example The following program uses a subprogram that prints a message on the screen without disturbing the current cursor position: ' Move cursor to center of screen, then print message. ' Cursor returned to center of screen. LOCATE 12,40 CALL MsgNoMove("A message not to be missed.",9,35) INPUT "Enter anything to end: ",A$ ' Print a message without disturbing current ' cursor position. SUB MsgNoMove (Msg$,Row%,Col%) STATIC ' Save the current line. CurRow%=CSRLIN ' Save the current column. CurCol%=POS(0) ' Print the message at the given position. LOCATE Row%,Col% : PRINT Msg$; ' Move the cursor back to original position. LOCATE CurRow%, CurCol% END SUB ──────────────────────────────────────────────────────────────────────────── CVSMBF, CVDMBF Functions ──────────────────────────────────────────────────────────────────────────── ■ Action Converts strings containing Microsoft Binary format numbers to IEEE-format numbers ■ Syntax CVSMBF (4-byte-string) CVDMBF (8-byte-string) ■ Remarks The CVSMBF and CVDMBF functions allow you to read old random-access files containing real numbers stored as strings in Microsoft Binary format. These functions convert the string read from the old file to an IEEE-format number: Function Description ────────────────────────────────────────────────────────────────────────── CVSMBF Converts 4-byte-string containing a Microsoft Binary format number to a single-precision IEEE-format number. CVDMBF Converts 8-byte-string containing a Microsoft Binary format number to a double-precision IEEE-format number. ────────────────────────────────────────────────────────────────────────── The example below shows you how to read data from an old file by using CVSMBF and user-defined types for records. See Appendix B, "Differences from Previous Versions of QuickBASIC," in Programming in BASIC for more information about converting old data files. ■ See Also FIELD; MKSMBF$, MKDMBF$ ■ Example The following program reads records from a random-access file containing Microsoft Binary format real numbers stored as strings. Each record contains a student's name and a test score. ' Define a user type for the data records. TYPE StudentRec NameField AS STRING*20 Score AS STRING*4 END TYPE ' Define a variable of the user type. DIM Rec AS StudentRec ' Open the file. OPEN "TESTDAT.DAT" FOR RANDOM AS #1 LEN=LEN(Rec) Max=LOF(1)/LEN(Rec) ' Read and print all of the records. FOR I=1 TO Max ' Read a record into the user-type variable Rec. GET #1,I,Rec ' Convert the score from a string containing a Microsoft ' Binary format number to an IEEE-format number. ScoreOut=CVSMBF(Rec.Score) ' Display the name and score. PRINT Rec.NameField,ScoreOut NEXT I CLOSE #1 ──────────────────────────────────────────────────────────────────────────── CVI, CVS, CVL, CVD Functions ──────────────────────────────────────────────────────────────────────────── ■ Action Converts strings containing numeric values to numbers ■ Syntax CVI(2-byte-string) CVS(4-byte-string) CVL(4-byte-string) CVD(8-byte-string) ■ Remarks CVI, CVS, CVL, and CVD are used with a FIELD statement to read real numbers from a random-access file. The functions take strings defined in the FIELD statement and convert them to a value of the corresponding numeric type. The functions are the inverse of MKI$, MKS$, MKL$, and MKD$: Function Description ────────────────────────────────────────────────────────────────────────── CVI Converts 2-byte-string created with MKI$ back to an integer. CVS Converts 4-byte-string created with MKS$ back to a single-precision number. CVL Converts 4-byte-string created with MKL$ back to a long integer. CVD Converts 8-byte-string created with MKD$ back to a double-precision number. ────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── NOTE The new BASIC record variables provide a more efficient and convenient way of reading and writing random-access files. See Chapter 3, "File and Device I/O," in Programming in BASIC for a complete example. ──────────────────────────────────────────────────────────────────────────── ■ See Also FIELD; LSET; MKD$, MKI$, MKL$, MKS$ ■ Example The following program illustrates the use of MKS$ and CVS: OPEN "ACCOUNT.INF" FOR RANDOM AS #2 LEN = 29 FIELD #2, 25 AS Name$, 4 AS Check$ Format$ = "$$#####.##" DO PRINT DO INPUT "Enter account # to update: ",Rec% GET #2, Rec% 'Get the record PRINT "This is the account for "; Name$ INPUT "Is this the account you wanted"; R$ LOOP WHILE UCASE$(MID$(R$,1,1)) <> "Y" 'Convert string to single-precision number. Checkamt! = CVS(Check$) PRINT PRINT "The opening balance for this account is"; PRINT USING Format$; Checkamt! PRINT "Enter the checks and cash withdrawals for this" PRINT "account below. Enter 0 when finished." DO INPUT Checkout! : Checkamt! = Checkamt! - Checkout! LOOP UNTIL Checkout! = 0 PRINT PRINT "Enter the deposits for this account below." PRINT "Enter 0 when finished." DO INPUT Checkin! : Checkamt! = Checkamt! + Checkin! LOOP UNTIL Checkin! = 0 PRINT PRINT "The closing balance for this account is"; PRINT USING Format$; Checkamt! 'Convert single-precision number to string. LSET Check$ = MKS$(Checkamt!) PUT #2, Rec% 'Store the record. INPUT "Update another"; R$ LOOP UNTIL UCASE$(MID$(R$,1,1)) <> "Y" CLOSE #2 END ──────────────────────────────────────────────────────────────────────────── DATA Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Stores the numeric and string constants used by a program's READ statements ■ Syntax DATA constant1 «,constant2»... ■ Remarks The constant1, constant2, and so on in a DATA statement can be any valid numeric or string constant. Names of symbolic constants (defined in a CONST statement) appearing in DATA statements are interpreted as strings, rather than names of constants. For example, in the following program fragment the second data item is a string, "PI", and not the value 3.141593: CONST PI=3.141593 . . . DATA 2.20, PI,45,7 . . . A DATA statement may contain as many constants as will fit on a line. The constants are separated by commas. You may use any number of DATA statements. ──────────────────────────────────────────────────────────────────────────── NOTE String constants in DATA statements require double quotes only if they contain commas, colons, or significant leading or trailing spaces. ──────────────────────────────────────────────────────────────────────────── Null data items (indicated by a missing value) can appear in a data list: DATA 1,2,,4,5 When a null item is read into a numeric variable, the variable has the value 0. When a null item is read into a string variable, the variable has the null string value (""). When working in the QuickBASIC environment, DATA statements can only be entered in the module-level code. QuickBASIC moves all DATA statements not in the module-level code to the module-level code when it reads a source file. READ statements using the DATA statements can appear anywhere in the program. DATA statements are used in the order in which they appear in the source file. You may think of the items in several DATA statements as one continuous list of items, regardless of how many items are in a statement or where the statement appears in the program. You may reread DATA statements by using the RESTORE statement. ■ See Also READ RESTORE ■ Examples The following example displays the current date by converting the date returned by the DATE$ function: ' Get the date. C$ = DATE$ ' Use VAL to split the month off the string returned by ' DATE$. FOR I% = 1 TO VAL(C$) READ Month$ NEXT DATA January, February, March, April, May, June, July DATA August, September, October, November, December ' Get the day. Day$ = MID$(C$,4,2) IF LEFT$(Day$,1) = "0" THEN Day$ = RIGHT$(Day$,1) ' Get the year. Year$ = RIGHT$(C$,4) PRINT "Today is " Month$ " " Day$ ", " Year$ ■ Output Today is September 21, 1988 The following example shows how null data items are handled: DATA abc,,def DATA 1,,2 READ A$, B$, C$ 'B$ = "" PRINT A$, B$, C$ PRINT READ A, B, C 'B = 0 PRINT A, B, C OUTPUT abc def 1 0 2 ──────────────────────────────────────────────────────────────────────────── DATE$ Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns a string containing the current date ■ Syntax DATE$ ■ Remarks The DATE$ function returns a ten-character string in the form mm-dd-yyyy, where mm is the month (01-12), dd is the day (01-31), and yyyy is the year (1980-2099). ■ See Also DATE$ Statement ■ Example Note that the DATE$ function in the following example prints a zero in front of the month: PRINT DATE$ ■ Output 09-21-88 ──────────────────────────────────────────────────────────────────────────── DATE$ Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Sets the current date ■ Syntax DATE$ = stringexpression ■ Remarks The DATE$ statement is the complement of the DATE$ function. The stringexpression must have one of the following forms, where mm (01-12) and dd (01-31) are the month and day, and yy and yyyy (1980-2099) are the year: mm-dd-yy mm-dd-yyyy mm/dd/yy mm/dd/yyyy ■ Example The following program sets the current date from an input numeric date: PRINT "Enter the date below (default year is 1989)." INPUT " Month: ",Month$ INPUT " Date: ",Day$ INPUT " Year: ",Year$ IF Year$ = "" THEN Year$ = "89" DATE$ = Month$ + "/" + Day$ + "/" + Year$ ──────────────────────────────────────────────────────────────────────────── DECLARE Statement (BASIC Procedures) ──────────────────────────────────────────────────────────────────────────── ■ Action Declares references to BASIC procedures and invokes argument type checking ■ Syntax DECLARE {FUNCTION | SUB } name «(«parameterlist»)» ■ Remarks The DECLARE statement uses the following arguments: Argument Description ────────────────────────────────────────────────────────────────────────── name The procedure's name. The name is limited to 40 characters. FUNCTION names can end in one of the type-declaration characters (%, &, !, #, or $) to indicate the type of value returned. parameterlist A list of parameters indicating the number and type of arguments used when calling the procedure. Syntax is shown below. Only the number and the type of the arguments are significant. ────────────────────────────────────────────────────────────────────────── For calls within BASIC, the DECLARE statement is required only if you call SUB procedures without the CALL keyword, or if you invoke a FUNCTION defined in another module. See Chapter 2, "SUB and FUNCTION Procedures," in Programming in BASIC, for more information about invoking subprograms without CALL. A DECLARE statement also causes the compiler to check the number and type of arguments used to invoke the procedure. QuickBASIC automatically generates DECLARE statements when you save your program while you are working in the environment. The DECLARE statement can appear only in module-level code (not in a SUB or FUNCTION) and affects the entire module. The parameterlist serves as a prototype for checking the number and type of the arguments in SUB and FUNCTION calls. It has the following syntax: variable«AS type» «,variable«AS type»»... A variable is any valid BASIC variable name. If the variable is an array, it may be followed by the number of dimensions in parentheses: DECLARE SUB DisplayText (A(2) AS STRING) DIM Text$(100,5) . . . CALL DisplayText(Text$()) The number of dimensions is optional. The type is either INTEGER, LONG, SINGLE, DOUBLE, STRING, or a user-defined type. Again, only the number and types of arguments are significant. ──────────────────────────────────────────────────────────────────────────── NOTE You cannot have fixed-length strings in DECLARE statements because only variable-length strings can be passed to SUB and FUNCTION procedures. Fixed-length strings can appear in an argument list but are converted to variable-length strings before being passed. ──────────────────────────────────────────────────────────────────────────── A variable's type can also be indicated by including an explicit type character (%, &, !, #, or $) or by relying on the default type. The form of the parameter list determines whether or not argument checking is done, as shown in the following list: Declaration Meaning ────────────────────────────────────────────────────────────────────────── DECLARE SUB First You may only omit the parentheses if the SUB or FUNCTION is separately compiled. No argument checking is done. DECLARE SUB First () First has no parameters. Arguments in a CALL to First are flagged as an error. An empty parameter list indicates that the SUB or FUNCTION has no parameters. DECLARE SUB First (X AS LONG) First has one long-integer parameter. The number and type of the arguments in each CALL or invocation are checked when the parameter list appears in the DECLARE. ────────────────────────────────────────────────────────────────────────── ■ See Also CALL, CALLS (Non-BASIC); FUNCTION; SUB ■ Example In the following example, the DECLARE statement allows Sort to be invoked without the CALL keyword: ' Generate 20 random numbers, store them in an array, and sort. ' The sort subprogram is called without the CALL keyword. DECLARE SUB Sort(A(1) AS SINGLE, N AS INTEGER) DIM Array1(1 TO 20) ' Generate 20 random numbers. RANDOMIZE TIMER FOR I=1 TO 20 Array1(I)=RND NEXT I ' Sort the array and call Sort without the CALL keyword. ' Notice the absence of parentheses around the arguments in ' the call to Sort. Sort Array1(), 20% ' Print the sorted array. FOR I=1 TO 20 PRINT Array1(I) NEXT I END ' Sort subroutine. SUB Sort(A(1), N%) STATIC FOR I= 1 TO N%-1 FOR J=I+1 TO N% IF A(I)>A(J) THEN SWAP A(I), A(J) NEXT J NEXT I END SUB ──────────────────────────────────────────────────────────────────────────── DECLARE Statement (Non-BASIC Procedures) ──────────────────────────────────────────────────────────────────────────── ■ Action Declares calling sequences for external procedures written in other languages ■ Syntax 1 DECLARE FUNCTION name «CDECL» «ALIAS "aliasname"»«(«parameterlist»)» ■ Syntax 2 DECLARE SUB name «CDECL» «ALIAS "aliasname"»«(«parameterlist»)» ■ Remarks The following list describes the parts of the DECLARE statement: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Part Description ────────────────────────────────────────────────────────────────────────── FUNCTION Indicates that the external procedure returns a Part Description ────────────────────────────────────────────────────────────────────────── FUNCTION Indicates that the external procedure returns a value and can be used in an expression. SUB Indicates that the external procedure is invoked in the same way as a BASIC SUB. name The name used in the BASIC program to invoke the procedure. Names may have up to 40 characters. FUNCTION names can include an explicit type character (%, &, !, #, or $) indicating the type of value the FUNCTION returns. CDECL Indicates that the procedure uses the C-language argument order. CDECL passes the arguments from right to left, rather than using the BASIC convention of left to right. CDECL also affects the name used in searches of object files and libraries. If there is no ALIAS Part Description ────────────────────────────────────────────────────────────────────────── object files and libraries. If there is no ALIAS in the DECLARE, the name of the procedure (name) is converted to lowercase, the type-declaration character is removed, and an underscore is added to the beginning. This becomes the name used when searching libraries and external files. If CDECL is used with an ALIAS, the aliasname is used. ALIAS Indicates that the procedure has another name in the .OBJ or library file. aliasname The name the procedure has in the file or library. ────────────────────────────────────────────────────────────────────────── A parameterlist has the following syntax: «{BYVAL|SEG}» variable «AS type» «,«{BYVAL|SEG}» variable «AS type»»... The following list describes the parts of a parameterlist: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Part Description ────────────────────────────────────────────────────────────────────────── BYVAL BYVAL indicates that the parameter is passed by value, rather than by reference. Reference is the default. BYVAL can be used only with INTEGER, LONG, SINGLE, and DOUBLE parameters. When BYVAL appears in front of a parameter, the actual argument is converted to the type indicated in the DECLARE statement before being passed. SEG Indicates the parameter is passed as a segmented address (far pointer). variable A valid BASIC variable name. Only the variable's type is significant. If the variable is an array Part Description ────────────────────────────────────────────────────────────────────────── type is significant. If the variable is an array it may be followed by the number of dimensions in parentheses (to maintain compatibility with older versions of BASIC): DECLARE SUB EigenValue (A(2) AS DOUBLE) The number of dimensions is optional. AS type Indicates the variable's type. The type element may be either INTEGER, LONG, SINGLE, DOUBLE, STRING, ANY, or a user type. You can also indicate the variable's type by including an explicit type character (%, &, !, #, or $) in the variable name or by relying on the default type. When declaring external procedures written in other languages, you can use the ANY keyword in the AS clause. ANY overrides type checking for Part Description ────────────────────────────────────────────────────────────────────────── the AS clause. ANY overrides type checking for that argument. You cannot use ANY with arguments passed by value. ────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── NOTE When neither BYVAL nor SEG is used, arguments are passed as near addresses (offsets). ──────────────────────────────────────────────────────────────────────────── This form of the DECLARE statement lets you reference procedures written in other languages. The DECLARE statement also causes the compiler to check the number and type of arguments used to invoke the procedure. A DECLARE statement can appear only in module-level code and affects the entire source file. The form of the parameter list determines whether or not argument type checking is done: Declaration Meaning ────────────────────────────────────────────────────────────────────────── DECLARE SUB First CDECL No argument checking is done when there is no parameter list. DECLARE SUB First CDECL () First has no parameters. Arguments in a CALL to First are flagged as an error. Empty parentheses indicate that the SUB or FUNCTION has no parameters. DECLARE SUB First CDECL (X AS LONG) First takes one long integer argument. When a parameter list appears, the number and type of the arguments are checked in each invocation. ────────────────────────────────────────────────────────────────────────── A procedure that appears in a DECLARE statement can be invoked without the CALL keyword. See the entry for DECLARE (BASIC) for more information. ──────────────────────────────────────────────────────────────────────────── NOTE You cannot have fixed-length strings in DECLARE statements because only variable-length strings can be passed to SUB and FUNCTION procedures. Fixed-length strings can appear in an argument list but are converted to variable-length strings before being passed. ──────────────────────────────────────────────────────────────────────────── Be careful when using the SEG keyword to pass arrays because BASIC may move variables in memory before the called routine begins execution. Anything in a CALL statement's argument list that causes memory movement may create problems. You can safely pass variables using SEG if the CALL statement's argument list contains only simple variables, arithmetic expressions, or arrays indexed without the use of intrinsic or user-defined functions. See Section 2.3.3, "Variable Storage Allocation," for a list of things that cause variable movement and for information about when to use near or far addresses for variables. ■ See Also CALL, CALLS (Non-BASIC); DECLARE (BASIC) ■ Example The following example shows a BASIC program that calls a short C function. The C program would be separately compiled and stored in a Quick library or explicitly linked to form the .EXE file. DEFINT a-z ' The function addone uses C argument passing and takes ' a single integer argument passed by value. DECLARE FUNCTION addone CDECL (BYVAL n AS INTEGER) INPUT x y=addone(x) PRINT "x and y are ";x;y END /* C function addone. Returns one more than the value of its integer argument. */ int far addone(n) int n; { return(++n); } ──────────────────────────────────────────────────────────────────────────── DEF FN Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Defines and names a function ■ Syntax 1 DEF FNname«(parameterlist)» = expression ■ Syntax 2 DEF FNname«(parameterlist)» . . . FNname = expression . . . END DEF ■ Remarks The DEF FN statement takes the following arguments: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Argument Description ────────────────────────────────────────────────────────────────────────── name A legal variable name, up to 40 characters long. This name, combined with FN, is the name of the Argument Description ────────────────────────────────────────────────────────────────────────── This name, combined with FN, is the name of the function. The name can include an explicit type-declaration character to indicate the type of value returned. Names that are the same except for the type-declaration character are distinct names. For example, the following are names of three different DEF FN functions: FNString$ FNString% FNString# To return a value from a DEF FN function, assign the value to the full function name: FNString$ = "No answer." Argument Description ────────────────────────────────────────────────────────────────────────── parameterlist A list of variable names, separated by commas. The syntax is explained below. When the function is called, BASIC assigns the value of each argument to its corresponding parameter. Function arguments are passed by value. DEF FN functions do not accept arrays, records, or fixed-length strings as arguments. expression In both syntaxes, expression is evaluated and the result is the function's value. In Syntax 1, expression is the entire body of the function and is limited to one logical line. When no expression is assigned to the name, the default return values are zero for a numeric DEF FN function, and the null string ("") for a string DEF FN function. ────────────────────────────────────────────────────────────────────────── Argument Description ────────────────────────────────────────────────────────────────────────── ────────────────────────────────────────────────────────────────────────── A parameterlist has the following syntax: variable «AS type» «, variable «AS type»»... A variable is any valid BASIC variable name. The type is INTEGER, LONG, SINGLE, DOUBLE, or STRING. You may also indicate a variable's type by including a type-declaration character (%, &, !, #, or $) in the name. ──────────────────────────────────────────────────────────────────────────── NOTE The FUNCTION procedure offers greater flexibility and control than the DEF FN function. See the entry for FUNCTION and Chapter 2, "SUB and FUNCTION Procedures," in Programming in BASIC for more information. ──────────────────────────────────────────────────────────────────────────── You must define a DEF FN function with a DEF FN statement before the function is used. Calling a DEF FN function before it is defined produces an error message that reads Function not defined. DEF FN function definitions cannot appear inside other DEF FN definitions. In addition, DEF FN functions cannot be recursive. You must use the EXIT DEF statement to leave a multiline DEF FN early. DEF FN functions can only be used in the module in which they are defined. They cannot be referenced from other modules. A DEF FN function may share variables with the module-level code. Variables not in the parameterlist are global──their values are shared with the calling program. To keep a variable value local to a function definition, declare it in a STATIC statement. See Chapter 2, "Data Types," for a discussion of local and global variables. DEF FN can return either numeric or string values. DEF FN returns a string value if name is a string variable name, and a numeric value if name is a numeric variable name. Assigning a numeric value to a string function name or assigning a string value to a numeric function name produces the error message Type mismatch. If the function is numeric, DEF FNname returns a value with the precision specified by name. For example, if name specifies a double-precision variable, then the value returned by DEF FNname is double precision, regardless of the precision of expression. Because BASIC may rearrange arithmetic expressions for greater efficiency, avoid using DEF FN functions that change program variables in expressions that may be reordered. The following example may give different results: DEF FNShort I=10 FNShort=1 END DEF I=1 : PRINT FNShort + I + I If BASIC reorders the expression so FNShort is called after calculating (I+I), the result is 3 rather than 21. You can usually avoid this problem by isolating the DEF FN function call: I = 1 : X = FNShort : PRINT X + I + I Doing I/O operations in DEF FN functions used in I/O statements or doing graphics operations in DEF FN functions in graphics statements may cause similar problems. ■ See Also EXIT, FUNCTION, STATIC ■ Example The following example uses a DEF FN function to calculate the factorial of an input number (the factorial of 3 is 3*2*1): DEF FNFactorial#(X) STATIC Tmp#, I Tmp#=1 FOR I=2 TO X Tmp#=Tmp#*I NEXT I FNFactorial#=Tmp# END DEF INPUT "Enter a number: ",Num PRINT Num "factorial is" FNFactorial#(Num) ■ Output Enter a number: 3 3 factorial is 6 ──────────────────────────────────────────────────────────────────────────── DEF SEG Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Sets the current segment address for a subsequent PEEK function or a BLOAD, BSAVE, CALL ABSOLUTE, or POKE statement ■ Syntax DEF SEG «=address» ■ Remarks For BLOAD, BSAVE, CALL ABSOLUTE, PEEK, and POKE, address is used as the segment. The address is a numeric expression returning an unsigned integer in the range 0-65,535. A value outside this range produces the error message Illegal function call. The previous segment is retained if an error occurs. If you omit address, the BASIC data segment is used. Be sure to separate DEF and SEG with a space. Otherwise, BASIC interprets the statement to mean "assign a value to the variable DEFSEG." ■ Differences From Basica In QuickBASIC, the CALL and CALLS statements do not use the segment address set by DEF SEG. ■ Example The following program uses DEF SEG, PEEK, and POKE statements to turn the CAPS LOCK on and off: ──────────────────────────────────────────────────────────────────────────── NOTE This program contains hardware-specific instructions. It works correctly on IBM PC, PC/XT(R), and PC/AT(R) computers. ──────────────────────────────────────────────────────────────────────────── DECLARE SUB CapsOn () DECLARE SUB CapsOff () DECLARE SUB PrntMsg (R%,C%,M$) CLS ' Turn Caps Lock on. CapsOn PrntMsg 24,1,"<Caps Lock On>" ' Prompt for input to show keyboard has changed. LOCATE 12,10 LINE INPUT "Enter a string (all characters are caps): ",S$ ' Turn Caps Lock off. CapsOff PrntMsg 24,1," " PrntMsg 25,1,"Press any key to continue..." DO WHILE INKEY$="" : LOOP CLS END ' Turn Caps Lock on. SUB CapsOn STATIC ' Set segment to low memory. DEF SEG = 0 ' Set Caps Lock on (turn on bit 6 of &H0417). POKE &H0417,PEEK(&H0417) OR &H40 ' Restore segment. DEF SEG END SUB ' Turn Caps Lock off. SUB CapsOff STATIC DEF SEG=0 ' Set Caps Lock off (turn off bit 6 of &H0417). POKE &H0417,PEEK(&H0417) AND &HBF DEF SEG END SUB ' Print message at Row%, Col% without changing cursor. SUB PrntMsg (Row%, Col%, Message$) STATIC ' Save current cursor position. CurRow%=CSRLIN : CurCol%=POS(0) LOCATE Row%,Col% : PRINT Message$; ' Restore cursor position. LOCATE CurRow%,CurCol% END SUB ──────────────────────────────────────────────────────────────────────────── DEFtype Statements ──────────────────────────────────────────────────────────────────────────── ■ Action Set the default data type for variables, DEF FN functions, and FUNCTION procedures ■ Syntax DEFINT letterrange «,letterrange»... DEFSNG letterrange «,letterrange»... DEFDBL letterrange «,letterrange»... DEFLNG letterrange «,letterrange»... DEFSTR letterrange «,letterrange»... ■ Remarks The letterrange has the form: letter1«-letter2» where letter1 and letter2 are any of the uppercase or lowercase letters of the alphabet. Names beginning with the letters in letterrange have the type specified by the last three letters of the statement: integer (INT), long integer (LNG), single precision (SNG), double precision (DBL), or string (STR). For example, in the following program fragment, Message is a string variable: DEFSTR A-Q . . . Message="Out of stack space." The case of the letters in letterrange is not significant. All of the following statements are equivalent: DEFINT I-N DEFINT i-n DEFINT i-N A type-declaration character (%, &, !, #, or $) always takes precedence over a DEFtype statement. DEFtype statements do not affect record elements. ──────────────────────────────────────────────────────────────────────────── NOTE I!, I#, I&, I$, and I% are all distinct variables, and each may hold a different value. ──────────────────────────────────────────────────────────────────────────── ■ Differences From Basica BASICA handles DEFtype statements differently. BASICA scans a statement each time before executing it. If the statement contains a variable without an explicit type (indicated by !, #, &, $, or %), the interpreter uses the current default type. In the example below, when BASICA interprets line 20, it determines that the current default type for variables beginning with I is integer. Line 30 changes the default type to single precision. When BASICA loops back to line 20, it rescans the line and uses IFLAG as a single-precision variable. 10 DEFINT I 20 PRINT IFLAG 30 DEFSNG I 40 GOTO 20 In contrast, QuickBASIC scans the text only once; once a variable appears in a program line, its type cannot be changed. ■ Example See the example for the ABS function. ──────────────────────────────────────────────────────────────────────────── DIM Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Declares a variable and allocates storage space ■ Syntax DIM «SHARED» variable«(subscripts)»«AS type»«,variable«(subscripts)»«AStype ■ Remarks The following list describes the parts of the DIM statement: Part Description ────────────────────────────────────────────────────────────────────────── SHARED The optional SHARED attribute allows all procedures in a module to share arrays and simple variables. This differs from the SHARED statement, which affects only variables within a single SUB or FUNCTION. variable A BASIC variable name. subscripts The dimensions of the array. Multiple dimensions can be declared. The subscript syntax is described below. AS type Declares variable to be an elementary or user-defined type. The elementary types are INTEGER, LONG, SINGLE, DOUBLE, and STRING (variable or fixed). ────────────────────────────────────────────────────────────────────────── Subscripts in DIM statements have the following form: «lower TO» upper «, «lower TO» upper»... The TO keyword provides a way to indicate both the lower and the upper bounds of an array's subscripts. The following statements are equivalent (if there is no OPTION BASE statement): DIM A(8,3) DIM A(0 TO 8, 0 TO 3) DIM A(8,0 TO 3) With the TO keyword, you are no longer restricted to positive subscripts. You can use TO to specify any range of subscripts from -32,768 to 32,767: DIM A(-4 TO 10) DIM B(-99 TO -5,-3 TO 0) If you use an array in your program without including the array in a DIM statement, the maximum value of each subscript of the array is 10. If you use a subscript that is greater than the specified maximum, an error message appears that says Subscript out of range. The DIM statement initializes all elements of numeric arrays to zero and all the elements of string arrays to null strings. The fields of record variables are initialized to zero, including fixed-string fields. The maximum number of dimensions allowed in a DIM statement is 60. If you try to dimension an array variable with a DIM statement after you have referred to the array, an error message results that reads Array already dimensioned. It is good programming practice to put the required DIM statements at the beginning of a program, outside of any loops. STATIC AND DYNAMIC ARRAYS How you declare an array also determines whether it is static (allocated when the program is translated) or dynamic (allocated when the program is run). ■ An array declared first in a COMMON statement is dynamic. ■ Implicitly dimensioned arrays are static. ■ Arrays dimensioned with numeric constants or CONST statement constants are static. ■ Arrays dimensioned with variables as subscripts are dynamic. The following list shows the different combinations and results: Statement Result ────────────────────────────────────────────────────────────────────────── DIM A(0 TO 9) The array A is allocated as a static array if ¢DYNAMIC is not in effect. DIM A(MAXDIM) If MAXDIM is defined in a CONST statement, A is a static array. If MAXDIM is a variable, then the array is a dynamic array and is only allocated when the program reaches the DIM statement. ────────────────────────────────────────────────────────────────────────── See Appendix F, "Metacommands," in Programming in BASIC and Chapter 2, "Data Types," in this manual for more information about static and dynamic arrays. ──────────────────────────────────────────────────────────────────────────── NOTE If the array size exceeds 64K, if the array is not dynamic, and if the /AH option was not used, you may get an error message that reads Subscript out of range or one that reads Array too big. Reduce the size of the array or make the array dynamic and use the /AH command-line option. ──────────────────────────────────────────────────────────────────────────── TYPE DECLARATIONS In addition to declaring the dimensions of an array, the DIM statement may also be used to declare the type of a variable. For example, this statement declares the variable to be an integer, even though there is no type declaration character or DEFINT statement: DIM NumberOfBytes AS INTEGER The DIM statement provides a mechanism for declaring specific variables to be records. In the following example, the variable TopCard is declared as a record variable: TYPE Card Suit AS STRING*9 Value AS INTEGER END TYPE DIM TopCard AS Card You may also declare arrays of records: TYPE Card Suit AS STRING*9 Value AS INTEGER END TYPE DIM Deck(1 TO 52) AS Card See Appendix F, "Metacommands," in Programming in BASIC and Chapter 2, "Data Types," in this manual for more information. ■ Differences From Basica BASICA executes a DIM statement when it encounters the statement in the program. The array is only allocated when the statement is executed, so all arrays in BASICA are dynamic. ■ See Also ERASE, OPTION BASE, REDIM, SHARED ■ Example The following example finds and prints the maximum and minimum of a set of values: ' Find the maximum and minimum of up to 20 values. ' ' Dimension an array to hold the values. CONST MAXDIM=20 DIM A(1 TO MAXDIM) ' Use DIM to set up two integer variables. ' All other variables are SINGLE. DIM NumValues AS INTEGER, I AS INTEGER ' Get the values. NumValues=0 PRINT "Enter values one per line. Type END to end." DO INPUT A$ IF UCASE$(A$)="END" OR NumValues>=MAXDIM THEN EXIT DO NumValues=NumValues+1 A(NumValues)=VAL(A$) LOOP ' Find the maximum and minimum values. IF NumValues>0 THEN Max=A(1) Min=A(1) FOR I=1 TO NumValues IF A(I)>Max THEN Max=A(I) IF A(I)<Min THEN Min=A(I) NEXT I PRINT "The maximum is ";Max;" The minimum is ";Min ELSE PRINT "Too few values." END IF ■ Output Enter values one per line. Type END to end. ? 23.2 ? 11.3 ? 1.6 ? end The maximum is 23.2 The minimum is 1.6 ──────────────────────────────────────────────────────────────────────────── DO...LOOP Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Repeats a block of statements while a condition is true or until a condition becomes true ■ Syntax 1 DO «statementblock » LOOP «{WHILE | UNTIL} booleanexpression» ■ Syntax 2 DO «{WHILE | UNTIL} booleanexpression» «statementblock » LOOP ■ Remarks The following list describes the arguments of the DO...LOOP statement: Argument Description ────────────────────────────────────────────────────────────────────────── statementblock One or more BASIC statements to be repeated booleanexpression Any expression that evaluates to true (nonzero) or false (zero) ────────────────────────────────────────────────────────────────────────── You can use a DO...LOOP statement instead of a WHILE...WEND statement. The DO...LOOP is more versatile because it can test for a condition at the beginning or at the end of a loop. ■ Examples The first two examples below show you how placement of the condition affects the number of times the block of statements is executed. The third example illustrates testing at the end of a loop and presents a sort subprogram where an ending test is appropriate. In the following example, the test is done at the beginning of the loop. Because I is not less than 10, the body of the loop (the statement block) is never executed. ' DO...LOOP with test at the top of the loop. ' Output shows that loop was not executed. I = 10 PRINT "Value of I at beginning of loop is ";I DO WHILE I < 10 I = I + 1 LOOP PRINT "Value of I at end of loop is ";I ■ Output Value of I at beginning of loop is 10 Value of I at end of loop is 10 The following example tests I at the end of the loop, so the statement block executes at least once. ' DO...LOOP with test at the bottom of the loop. ' Output shows loop was executed once. I = 10 DO PRINT "Value of I at beginning of loop is ";I I = I + 1 LOOP WHILE I < 10 PRINT "Value of I at end of loop is ";I ■ Output Value of I at beginning of loop is 10 Value of I at end of loop is 11 The following sort subprogram tests at the end of the loop because the entire array must be examined at least once to see if it is in order. In general, test at the end of a loop only if you know that you always want the statement block executed at least once. ' Bubble sort subroutine ' Exes is array to sort ' N is number of elements in Exes ' ' Note: sort assumes the first element of ' Exes is Exes(1). ' Set up a special value to indicate no exchanges. CONST NOEXCH=-1 SUB sort(Exes(1),N) STATIC Limit=N DO Exchange=NOEXCH FOR I=1 TO Limit-1 ' Make one pass over the array. IF Exes(I) > Exes(I+1) THEN SWAP Exes(I),Exes(I+1) 'Exchange array elements. Exchange=I 'Record location of most END IF 'recent exchange. NEXT I Limit=Exchange 'Sort on next pass only to where 'last exchange was done. LOOP UNTIL Exchange=NOEXCH 'Sort until no elements 'are exchanged. END SUB ──────────────────────────────────────────────────────────────────────────── DRAW Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Draws an object defined by stringexpression ■ Syntax DRAW stringexpression ■ Remarks The DRAW statement combines many of the capabilities of the other graphics statements into a graphics macro language, as described below under "Cursor-Movement Commands" and "Angle, Color, and Scale-Factor Commands." This macro language defines a set of characteristics that can be used to describe an image. These characteristics include motion (up, down, left, right), color, rotation angle, and scale factor. The stringexpression consists of these macro commands. CURSOR-MOVEMENT COMMANDS The following prefix commands can precede any of the movement commands: Prefix Description ────────────────────────────────────────────────────────────────────────── B Move, but do not plot any points. N Move, but return to original position when done. ────────────────────────────────────────────────────────────────────────── The following commands specify movement in units. The default unit size is one point; this unit size can be modified by the S command, which sets the scale factor. (S is described in "Angle, Color, and Scale-Factor Commands.") If no argument is supplied, the cursor is moved one unit. Each of the movement commands initiates movement from the current graphics position, which is usually the coordinate of the last graphics point plotted with another graphics macro-language command. The current position defaults to the center of the screen when a program is run. ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Movement Description ────────────────────────────────────────────────────────────────────────── U «n» Move up n units. D «n» Move down n units. L «n» Move left n units. R «n» Move right n units. E «n» Move diagonally up and right n units. F «n» Move diagonally down and right n units. Movement Description ────────────────────────────────────────────────────────────────────────── G «n» Move diagonally down and left n units. H «n» Move diagonally up and left n units. M x,y Move absolute or relative. If x is preceded by a plus (+) or minus (-), the movement is relative to the current point; that is, x and y are added to (or subtracted from) the coordinates of the current graphics position and connected with that position by a line. If no sign precedes x, the movement is absolute; that is, a line is drawn from the current cursor position to the point with coordinates x,y. ────────────────────────────────────────────────────────────────────────── ANGLE, COLOR, AND SCALE-FACTOR COMMANDS The following commands let you change the appearance of a drawing by rotating it, changing colors, or scaling it: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Command Description ────────────────────────────────────────────────────────────────────────── A n Set angle of rotation n. The value of n may range from 0 to 3, where 0 is 0°, 1 is 90°, 2 is 180°, and 3 is 270°. Figures rotated 90° or 270° are scaled so they appear the same size using 0° or 180° on a monitor screen with a standard screen width-to-height ratio of 4/3. TA n Turn an angle of n degrees; n must be in the range -360 to 360. If n is positive, rotation is counterclockwise; if n is negative, rotation is clockwise. The following example uses TA to draw spokes: SCREEN 1 Command Description ────────────────────────────────────────────────────────────────────────── SCREEN 1 FOR D=0 TO 360 STEP 10 DRAW "TA="+VARPTR$(D)+"NU50" NEXT D C n Set color to n. See COLOR, PALETTE, and SCREEN statements for discussions of valid colors, numbers, and attributes. S n Set scale factor n, which may range from 1 to 255. The scale factor multiplied by the distances given with U, D, L, R, or relative M commands gives the actual distance traveled. P paintcolor, The paintcolor is the paint color for a figure's bordercolor interior, while bordercolor is the paint color for the figure's border. Tile painting (painting an area with a graphic pattern) is not supported in DRAW. Command Description ────────────────────────────────────────────────────────────────────────── in DRAW. X stringexpression Execute substring. This powerful command allows you to execute a second substring from a string. You may have one string expression execute another, which executes a third, and so on. Numeric arguments can be constants like 123 or variable names. QuickBASIC requires the "X" + VARPTR$(stringexpression) form of this command. (See "Differences from BASICA" below.) ────────────────────────────────────────────────────────────────────────── ■ Differences From Basica The DRAW statement requires modification of BASICA programs when used with QuickBASIC. Specifically, the compiler requires the VARPTR$ form for variables. Statements such as the following: DRAW "XA$" DRAW "TA = ANGLE" (where A$ and ANGLE are variables) must be changed as follows: DRAW "X" + VARPTR$(A$) DRAW "TA =" + VARPTR$(ANGLE) when using the compiler. The compiler does not support the Xstringexpression command. However, you may execute a substring by appending the character form of the address to X. For example, the following two statements are equivalent. The first statement works when within the environment and when using the compiler; the second works only within the environment. DRAW "X" + VARPTR$(A$) DRAW "XA$" ■ Examples The following program draws a triangle's outline in magenta and paints the interior cyan: SCREEN 1 DRAW "C2" 'Set color to magenta. DRAW "F60 L120 E60" 'Draw a triangle. DRAW "BD30" 'Move down into the triangle. DRAW "P1,2" 'Paint interior. The following example shows different ways of using the M macro command: with absolute movement and relative movement; using string-variable arguments; and using numeric-variable arguments: SCREEN 2 'Absolute movement DRAW "M 50,80" DRAW "M 80,50" 'Relative movement DRAW "M+40,-20" DRAW "M-40,-20" DRAW "M-40,+20" DRAW "M+40,+20" 'Using a string variable. X$ = "400" : Y$ = "190" DRAW "M" + X$ + "," + Y$ 'Using numeric variables (note the two "=" signs). A = 300 : B = 120 DRAW "M="+VARPTR$(A)+",="+VARPTR$(B) The following example draws a clock on the screen using the TIME$ function: ' Declare procedure. DECLARE SUB Face (Min$) ' Select 640 x 200 pixel high-resolution graphics screen. SCREEN 2 DO ' Clear the screen. CLS ' Get the string containing the minutes value. Min$ = MID$(TIME$,4,2) ' Draw the clock face. Face Min$ ' Wait until the minute changes or a key is pressed. DO ' Print the time at the top of the screen. LOCATE 2,37 PRINT TIME$ ' Test for a key press. Test$ = INKEY$ LOOP WHILE Min$ = MID$(TIME$,4,2) AND Test$ = "" ' End the program when a key is pressed. LOOP WHILE Test$ = "" END ' Draw the clock face. SUB Face (Min$) STATIC LOCATE 23,30 PRINT "Press any key to end" CIRCLE (320,100),175 ' Convert strings to numbers. Hr = VAL(TIME$) Min = VAL(Min$) ' Convert numbers to angles. Little = 360 - (30 * Hr + Min/2) Big = 360 - (6*Min) ' Draw the hands. DRAW "TA=" + VARPTR$(Little) + "NU40" DRAW "TA=" + VARPTR$(Big) + "NU70" END SUB ──────────────────────────────────────────────────────────────────────────── END Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Ends a BASIC program, procedure, or block ■ Syntax END «{DEF | FUNCTION | IF | SELECT | SUB | TYPE}» ■ Remarks There are several ways to use the END statement, as described in the following list: Statement Description ────────────────────────────────────────────────────────────────────────── END DEF Ends a multiline DEF FN function definition. You must use END DEF with a multiline DEF FN. END FUNCTION Ends a FUNCTION procedure definition. You must use END FUNCTION with FUNCTION. END IF Ends a block IF...THEN...ELSE statement. You must use END IF with block IF...THEN...ELSE. END SELECT Ends a SELECT CASE block. You must use END SELECT with a SELECT CASE statement. END SUB Ends a BASIC subprogram. You must use END SUB with SUB. END TYPE Ends a user-defined type definition. You must use END TYPE with TYPE. ────────────────────────────────────────────────────────────────────────── By itself, the END statement stops program execution and closes all files. In a stand-alone program, END returns control to the operating system. When running inside the QuickBASIC environment, END returns you to that environment. The compiler always assumes an END statement at the conclusion of any program, so omitting an END statement at the end of a program still produces proper program termination. You may place END statements anywhere in the program to end program execution. ■ See Also DEF FN; FUNCTION; IF...THEN...ELSE; SELECT CASE; SUB; TYPE ■ Example The following example uses a subprogram to query the user about continuing some action. If the user enters n or N the subprogram ends the program. DO . . . CALL ContinueQuery LOOP SUB ContinueQuery STATIC DO INPUT "Continue (Y or N)"; Response$ R$=UCASE$(LEFT$(Response$,1)) IF R$="N" THEN END IF R$="Y" THEN EXIT DO BEEP LOOP END SUB ──────────────────────────────────────────────────────────────────────────── ENVIRON$ Function ──────────────────────────────────────────────────────────────────────────── ■ Action Retrieves an environment string from the DOS environment-string table ■ Syntax ENVIRON$ (environmentstring) ENVIRON$ (n) ■ Remarks The environmentstring is a string constant or variable containing the name of an environment variable. The argument n is a numeric expression. If you specify an environmentstring name, but it cannot be found in the environment-string table, or there is no text following it, then ENVIRON$ returns a null string. Otherwise, ENVIRON$ returns the text following the equal sign in the environment-string table. If you specify a numeric argument (n), the nth string in the environment-string table is returned. In this case, the string includes all of the text, including the environmentstring name. If the nth string does not exist, ENVIRON$ returns a null string. The n argument can be any numeric expression; it is rounded to an integer. ■ Example The following example prints the current environment-string table settings: I = 1 DO WHILE ENVIRON$(I) <> "" PRINT ENVIRON$(I) I = I + 1 LOOP ■ Output COMSPEC=C:\COMMAND.COM TMP=c:\tmp PATH=C:\TOOLS;C:\BIN PROMPT=¢ec4$l¢ec7$p¢ec4$g¢ec7¢eb1 INIT=c:\tools LIB=c:\lib INCLUDE=c:\include ──────────────────────────────────────────────────────────────────────────── ENVIRON Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Modifies a parameter in the DOS environment-string table ■ Syntax ENVIRON stringexpression ■ Remarks The stringexpression must be of the form parameterid=text, or the form parameterid text. Everything to the left of the equal sign or space is assumed to be a parameter, and everything to the right, text. If the parameterid has not previously existed in the environment-string table, it is appended to the end of the table. If a parameterid exists in the table when the ENVIRON statement is executed, it is deleted and the new parameterid is appended to the end of the table. The text string is the new parameter text. If the text is a null string ("") or a semicolon (";"), then the existing parameter is removed from the environment-string table and the remaining body of the table is compressed. DOS discards the environment-string table modified by this function when your program ends. The environment-string table is the same as it was before your program ran. You may use this statement to change the PATH parameter for a "child" process (a program or command started by a SHELL statement) or to pass parameters to a child by inventing a new environment parameter. Errors in environment-string tables include parameters that are not strings and lack of free space. An Out of memory error message is printed when no more space can be allocated to the environment-string table. The amount of free space in the table is usually quite small. ■ See Also ENVIRON$, SHELL ■ Example The following example changes the value of the PATH environment variable to that shown: 'Change value of PATH environment variable. ENVIRON "PATH=A:\SALES;A:\ACCOUNTING" ──────────────────────────────────────────────────────────────────────────── EOF Function ──────────────────────────────────────────────────────────────────────────── ■ Action Tests for the end-of-file condition ■ Syntax EOF(filenumber) ■ Remarks The EOF function returns -1 (true) if the end of a sequential file has been reached. Use the EOF function to test for end-of-file while inputting data. In this way you may avoid the Input past end error message. When EOF is used with random-access or binary files, it returns "true" if the last executed GET statement was unable to read an entire record. This happens because of an attempt to read beyond the end of the file. EOF cannot be used with the BASIC devices SCRN:, KYBD:, CONS:, and LPTn:. When you use EOF with a communications device, the definition of the end-of-file condition is dependent on the mode (ASCII or binary) in which you opened the device. In ASCII mode, EOF is false until you receive CTRL+Z, after which it remains true until you close the device. In binary mode, EOF is true when the input queue is empty (LOC(n)=0). It becomes "false" when the input queue is not empty. ■ Example The fragment below reads single-precision values from a file until all values have been read: DIM M(0 TO 2000) OPEN "DATA" FOR INPUT AS 1 C = 0 DO WHILE NOT EOF(1) AND C <= 2000 INPUT #1, M(C) C = C+1 LOOP . . . ──────────────────────────────────────────────────────────────────────────── ERASE Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Reinitializes the elements of static arrays; deallocates dynamic arrays ■ Syntax ERASE arrayname «,arrayname...» ■ Remarks The arrayname arguments are the names of arrays to erase. ERASE has different effects on static and dynamic arrays. The ERASE statement sets the elements of a static array to zeros in the case of a numeric array or null strings ("") in the case of a string array. If the array is an array of records, the ERASE statement sets all elements of each record to zeros, including fixed-string elements. However, using ERASE on a dynamic array frees the memory used by the array. Before your program can refer to the dynamic array again, it must first redimension the array with a DIM or REDIM statement. Redimensioning an array with a DIM statement without first erasing it produces a duplicate definition run-time error message that reads Array already dimensioned. The ERASE statement is not required when arrays are redimensioned with REDIM. See Chapter 2, "Data Types," in this manual and Appendix F, "Metacommands," in Programming in BASIC for more information on declaring dynamic and static arrays. ■ See Also DIM, REDIM ■ Example The following program fragment shows the use of ERASE with the ¢DYNAMIC and ¢STATIC metacommands: REM ¢DYNAMIC DIM A(100,100) . . . 'This deallocates array A. ERASE A 'Redimension array A. REDIM A(5,5) REM ¢STATIC DIM B(50,50) . . . 'This sets all elements of B equal to zero. 'B still has the dimensions assigned by DIM. ERASE B ──────────────────────────────────────────────────────────────────────────── ERDEV, ERDEV$ Functions ──────────────────────────────────────────────────────────────────────────── ■ Action Provides device-specific status information after an error ■ Syntax ERDEV ERDEV$ ■ Remarks ERDEV is an integer function that returns an error code from the last device to declare an error. ERDEV$ is a string function that returns the name of the device generating the error. Because ERDEV and ERDEV$ return meaningful information only after an error, they are usually used in error handlers specified by an ON ERROR statement. ERDEV and ERDEV$ cannot be used on the left side of an assignment. ERDEV is set by the critical error handler (interrupt 24H) when DOS detects an error that prevents continuing. The value of ERDEV is a bit-encoded value containing the DOS error information. The lower eight bits (first byte) contain the DOS error code, a value from 0 to 12. The upper eight bits (second byte) contain bits 15, 14, 13, XX, 3, 2, 1, and 0, in that order, of the device-attribute word. XX indicates the bit is always zero. See the Microsoft MS-DOS Programmer's Reference for more information about device-attribute words. ■ See Also ERR, ERL; ON ERROR ■ Example The following example prints the values of ERDEV and ERDEV$ when an error occurs: DEFINT A-Z ' Indicate first line of error handler. ON ERROR GO TO ErrorHandler ' Attempt to open the file. OPEN "A:JUNK.DAT" FOR INPUT AS #1 END ' Error handling routine. ' Prints values of ERDEV and ERDEV$ and dies. ErrorHandler: PRINT "ERDEV value is ";ERDEV PRINT "Device name is ";ERDEV$ ON ERROR GOTO 0 ■ Output Running the program with drive A unlatched produces the following output (2 is the error code for "Drive not ready"): ERDEV value is 2 Device name is A: ──────────────────────────────────────────────────────────────────────────── ERR, ERL Functions ──────────────────────────────────────────────────────────────────────────── ■ Action Return error status ■ Syntax ERR ERL ■ Remarks After an error, the function ERR returns the code for the error, and the ERL function returns the line number where the error occurred. Because ERR and ERL return meaningful values only after an error, they are usually used in error-handling routines to determine the error and the corrective action. Because ERL and ERR are functions, you cannot use them on the left-hand side of an assignment statement. However, you may indirectly set them with the ERROR statement. ■ Differences From Basica The ERL function returns only the line number, not line label, located before the line producing the error. If your program has no line numbers, ERL always returns 0. ■ See Also ERDEV, ERROR, ON ERROR, RESUME ■ Example See the example for ON ERROR. ──────────────────────────────────────────────────────────────────────────── ERROR Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Simulates the occurrence of a BASIC error or allows the user to define error codes ■ Syntax ERROR integerexpression ■ Remarks The integerexpression represents the error code. It must be greater than 0 and less than or equal to 255. If the integerexpression is an error code already used by BASIC, then the ERROR statement simulates the occurrence of that error and prints the corresponding error message. To define your own error code, use a value that is greater than any used by the standard BASIC error codes. (Start at 255 and work down to maintain compatibility with future Microsoft BASIC error codes.) If an ERROR statement specifies a code for which no error message has been defined, the message Unprintable error is printed. Executing an ERROR statement for which there is no error-handling routine causes an error message to be printed and execution to halt. ■ See Also ERR, ERL; ON ERROR; RESUME ■ Example The following fragment uses an ERROR statement to trap a user input error: ON ERROR GOTO Handler OpenFile: INPUT "Name of file to update";FileSpec$ IF FileSpec$ = "" THEN END OPEN FileSpec$ FOR INPUT AS #1 PRINT "The first five lines of ";FILESPEC$;" are:" : PRINT FOR I = 1 TO 5 LINE INPUT #1, Temp$ PRINT Temp$ NEXT PRINT : INPUT "Is this the correct file";R$ 'Define error 200. IF LEFT$(R$,1) <> "y" THEN ERROR 200 . . . END Handler: 'Error-handling routine. Number = ERR 'Run-time error for "file not found." IF Number = 53 THEN CLOSE #1 PRINT "File not in this directory" PRINT "Enter new file spec ([d:]xxx...xxx) or" PRINT "press <RETURN> to end program" RESUME OpenFile ELSEIF Number = 200 THEN 'User entered "n" CLOSE #1 RESUME OpenFile ELSE ERROR Number 'Error other than 53 or 200. ON ERROR GOTO 0 'Print message, disable error END IF 'handling, and stop program. ■ Output Name of file to update? c:novelallenadv.txt File not in this directory Enter new file spec ([d:]xxx...xxx) or press <RETURN> to end program Name of file to update? c:toryallenadv.txt The first five lines of c:toryallenadv.txt are: Allen gripped the microphone. Small beads of perspiration glistened on his forehead like cheap pearls. He knew that what he said would change his life and the lives of those he loved. In a trembling voice, Is this the correct file? y ──────────────────────────────────────────────────────────────────────────── EXIT Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Exits a DEF FN function, DO...LOOP or FOR...NEXT loop, FUNCTION, or SUB ■ Syntax EXIT {DEF | DO | FOR | FUNCTION | SUB } ■ Remarks There are several ways to use the EXIT statement as described in the following list: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Statement Description ────────────────────────────────────────────────────────────────────────── EXIT DEF Causes an immediate exit from the executing DEF FN function. Program execution continues where the DEF FN function was invoked. EXIT DO Provides an alternative exit from a DO...LOOP. Can be used only inside a DO...LOOP statement; EXIT DO transfers control to the statement following the LOOP statement. When used within nested DO...LOOP statements, transfers out of the immediately enclosing loop. Statement Description ────────────────────────────────────────────────────────────────────────── EXIT FOR Provides another way to exit a FOR...NEXT loop. May appear only in a FOR...NEXT loop; transfers control to the statement following the NEXT statement. When used within nested FOR...NEXT loops, transfers out of the immediately enclosing loop. EXIT FUNCTION Causes an immediate exit from a FUNCTION procedure. Program execution continues where the FUNCTION was invoked. Can only be used in a FUNCTION procedure. EXIT SUB Immediately exits a SUB procedure. Program execution continues with the statement after the CALL statement. Can only be used in a SUB procedure. ────────────────────────────────────────────────────────────────────────── Statement Description ────────────────────────────────────────────────────────────────────────── None of the EXIT statements define the end of the structure in which they are used. EXIT statements only provide an alternative exit from the structure. ■ See Also DEF FN; DO...LOOP; FOR...NEXT; FUNCTION; SUB ■ Examples See the third example for STATIC for a use of EXIT SUB. The following subprogram is an extended RTRIM$ that removes trailing blanks, tabs, carriage returns, and line feeds from a string. The subprogram begins looking at the end of the string and uses EXIT FOR to jump out of the loop when the first printing character is found. ' Rtrim removes trailing blanks, tabs, carriage returns, ' and line feeds from a string. SUB Rtrim(S$) STATIC J=0 ' Begin at the end of the string and find the first ' character that isn't a blank, tab, carriage return, or ' line feed. FOR I=LEN(S$) TO 1 STEP -1 C$=MID$(S$,I,1) IF C$<>" " AND C$<>CHR$(9) AND C$<>CHR$(10) AND C$<>CHR$(13) THEN J=I EXIT FOR END IF NEXT I ' Remove the unwanted trailing characters. S$=LEFT$(S$,J) END SUB ──────────────────────────────────────────────────────────────────────────── EXP Function ──────────────────────────────────────────────────────────────────────────── ■ Action Calculates the exponential function ■ Syntax EXP(x) ■ Remarks The EXP function returns e (the base of natural logarithms) to the power of x. The exponent x must be less than or equal to 88.02969. A value of x greater than 88.02969 produces an Overflow error message. The calculation of EXP is performed in single precision by default; if the argument x is double precision, EXP is calculated in double precision. ■ See Also LOG ■ Example The following program uses the EXP function to calculate the growth of a bacterial colony over a 15-day period. Since the growth of the population is related to its ever-changing size, its growth is exponential. INPUT "Initial bacterial population"; Colony0 INPUT "Growth rate per day as a percentage of population"; Rate R = Rate/100 : Form$="## ###,###" PRINT : PRINT "Day Population" FOR T = 0 TO 15 STEP 5 PRINT USING Form$; T, Colony0 * EXP(R*T) NEXT ■ Output Initial bacterial population? 10000 Growth rate per day as a percentage of population? 10 Day Population 0 10,000 5 16,487 10 27,183 15 44,817 ──────────────────────────────────────────────────────────────────────────── FIELD Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Allocates space for variables in a random-access file buffer ■ Syntax FIELD «#»filenumber, fieldwidth AS stringvariable... ■ Remarks The following list describes the FIELD statement's arguments: Argument Description ────────────────────────────────────────────────────────────────────────── filenumber The number used in the file's OPEN statement fieldwidth The width of the field in the record stringvariable The string variable that contains the date read from a record or data that is used in an assignment when information is written to a record ────────────────────────────────────────────────────────────────────────── The total number of bytes that you allocate in a FIELD statement must not exceed the record length that you had specified when opening the file. Otherwise, an error message is generated that reads FIELD overflow. (The default record length is 128 bytes.) Any number of FIELD statements may be executed for the same file. All FIELD statements that have been executed remain in effect at the same time. All field definitions for a file are removed when the file is closed; that is, all strings defined as fields associated with the file are set to null. Do not use a variable name defined as a field in an INPUT or assignment statement if you wish the variable to remain a field. Once a variable name is a field, it points to the correct place in the random-access file buffer. If a subsequent INPUT or assignment statement with that variable name is executed, the variable's pointer no longer refers to the random-access record buffer, but to string space. ──────────────────────────────────────────────────────────────────────────── NOTE BASIC's record variables and extended OPEN statement syntax provide a more convenient way to use random-access files. See Chapter 3, "File and Device I/O," in Programming in BASIC for an extended discussion of using record variables for file I/O. ──────────────────────────────────────────────────────────────────────────── ■ Differences From Basica When a random-access file is closed with a CLOSE or RESET statement in a compiled program, all variables that are fields associated with that file are reset to null strings. When a random-access file is closed in a BASICA program, variables that are fields retain the last value assigned to them by a GET statement. ■ See Also GET, LSET, OPEN, PUT, RSET ■ Example This example illustrates a random-access file buffer with multiple definitions. In the first FIELD statement, the 67-byte buffer is broken up into five separate variables for name, address, city, state, and zip code. In the second FIELD statement, the same buffer is assigned entirely to one variable, PLIST$. The remainder of this example checks to see if ZIP$, which contains the zip code, falls within a certain range; if it does, the complete address string is printed. ' Define field and record lengths with constants. CONST LNAML=25, ADDRL=25, CTYL=10, STL=2, ZIPL=5 CONST RECLEN=LNAML+ADDRL+CTYL+STL+ZIPL OPEN "MAILLIST" FOR RANDOM AS #1 LEN=RECLEN FIELD #1, LNAML AS Lnam$, ADDRL AS Addr$, CTYL AS Cty$, STL AS St$, ZIPL AS Zip$ FIELD #1, RECLEN AS Plist$ GET #1, 1 ' Read the file, looking for zip codes in the range 85699 to ' 85801. DO WHILE NOT EOF(1) Zcheck$ = Zip$ IF (Zcheck$ >= "85699" AND Zcheck$ <= "85801") THEN Info$ = Plist$ PRINT LEFT$(Info$,25) PRINT MID$(Info$,26,25) PRINT RIGHT$(Info$,17) END IF GET #1 LOOP ──────────────────────────────────────────────────────────────────────────── FILEATTR Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns information about an open file ■ Syntax FILEATTR(filenumber,attribute) ■ Remarks The FILEATTR function takes the following arguments: Argument Description ────────────────────────────────────────────────────────────────────────── filenumber The number of an open file. This is the same number used in the OPEN statement. You can use a numeric expression as long as it evaluates to the number of an open file. attribute Indicates the type of information to return. When attribute is 1, FILEATTR returns a code indicating a file's mode (see below). When attribute is 2, FILEATTR returns the file's DOS file handle. ────────────────────────────────────────────────────────────────────────── Table R.2 lists the return values and corresponding file modes when attribute is 1. Table R.2 FILEATTR Mode Codes Return Value Mode ────────────────────────────────────────────────────────────────────────── 1 INPUT 2 OUTPUT 4 RANDOM 8 APPEND 32 BINARY ────────────────────────────────────────────────────────────────────────── ■ See Also OPEN ■ Example The following example opens two files and prints out the DOS file handles and modes returned by FILEATTR: OPEN "tempfile.dat" FOR APPEND AS #1 OPEN "tempfl2.dat" FOR RANDOM AS #2 PRINT "Number Handle Mode" PRINT TAB(2);1;TAB(10);FILEATTR(1,2);TAB(15);FILEATTR(1,1) PRINT TAB(2);2;TAB(10);FILEATTR(2,2);TAB(15);FILEATTR(2,1) END ■ Output Number Handle Mode 1 5 8 2 6 4 ──────────────────────────────────────────────────────────────────────────── FILES Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Prints the names of files residing on the specified disk ■ Syntax FILES «filespec» ■ Remarks The filespec is a string variable or constant that includes either a file name or a path name, and an optional device designation. If you omit filespec, the FILES statement lists all the files in the current directory. You may use the DOS wild card characters──question marks (?) or asterisks (*). A question mark matches any single character in the file name or extension. An asterisk matches one or more characters starting at that position. If you use a filespec without an explicit path, the current directory is the default. Note that, regardless of the path name contained in filespec, the header printed by FILES is always the current directory. ■ Examples The following statements illustrate the use of FILES: FILES 'Shows all files on the current directory. FILES "*.BAS" 'Shows all files with the extension .BAS. FILES "B:*.*" 'Shows all files on drive B. FILES "B:" 'Equivalent to "B:*.*". FILES "TEST?.BAS" 'Shows all five-letter files whose names 'start with "TEST" and end with the .BAS 'extension. FILES "\SALES" 'If SALES is a directory, this statement 'displays all files in SALES; if SALES is 'a file in the current directory, this 'statement displays the name SALES. ──────────────────────────────────────────────────────────────────────────── FIX Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the truncated integer part of x ■ Syntax FIX(x) ■ Remarks The x is a numeric expression. FIX(x) is equivalent to SGN(x)*INT(ABS(x)). The difference between FIX and INT is that for negative x, FIX returns the first negative integer greater than x, while INT returns the first negative integer less than x. ■ See Also CINT, INT ■ Example The following four statements illustrate the differences between INT and FIX: PRINT INT(-99.8) PRINT FIX(-99.8) PRINT INT(-99.2) PRINT FIX(-99.2) ■ Output -100 -99 -100 -99 ──────────────────────────────────────────────────────────────────────────── FOR...NEXT Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Repeats a group of instructions a specified number of times ■ Syntax FOR counter = start TO end «STEP increment» . . . NEXT «counter «,counter...»» ■ Remarks The FOR statement takes the following arguments: Argument Description ────────────────────────────────────────────────────────────────────────── counter A numeric variable used as the loop counter. The variable cannot be an array element or a record element. start The initial value of the counter. end The final value of the counter. increment The amount the counter is incremented each time through the loop. If you do not specify STEP, increment defaults to one. ────────────────────────────────────────────────────────────────────────── A FOR...NEXT loop executes only if start and end are consistent with increment. If end is greater than start, increment must be positive. If end is less than start, increment must be negative. This is checked at run-time by comparing the sign of (end - start) with the sign of step. If both have the same sign, the FOR...NEXT loop is entered. If not, the entire loop is skipped over. Within the FOR...NEXT loop, the program lines following the FOR statement are executed until the NEXT statement is encountered. Then counter is changed by the amount specified by STEP, and compared with the final value, end. If counter is less than or equal to end, control returns to the statement after the FOR statement and the process repeats. If counter is greater than end, the loop is exited; execution continues with the statement following the NEXT statement. (If STEP is negative, the loop repeats until counter is less than end.) If start and end have the same value, the loop executes once, regardless of the value of STEP. If STEP is zero, the loop repeats indefinitely. Avoid changing the value of counter within the loop. Changing the loop counter is poor programming practice; it makes the program more difficult to read and debug. You can nest FOR...NEXT loops; that is, you can place a FOR...NEXT loop within another FOR...NEXT loop. To ensure that nested loops work properly, give each loop a unique variable name as its counter. The NEXT statement for the inside loop must appear before the NEXT statement for the outside loop. The following construction is correct: FOR I = 1 TO 10 FOR J = 1 TO 10 FOR K = 1 TO 10 . . . NEXT K NEXT J NEXT I A NEXT statement with the form NEXT K, J, I is equivalent to the following sequence of statements: NEXT K NEXT J NEXT I The EXIT FOR statement is a convenient alternative exit from FOR...NEXT loops. See the EXIT FOR statement. ──────────────────────────────────────────────────────────────────────────── NOTE If you omit the variable in a NEXT statement, the NEXT statement matches the most recent FOR statement. If a NEXT statement is encountered before its corresponding FOR statement, an error message is generated that reads NEXT without FOR. ──────────────────────────────────────────────────────────────────────────── ■ Differences From Basica Unlike BASICA, QuickBASIC supports double-precision control values (start, end, and counter) in its FOR...NEXT loops. However, if the control values fall within the range for integers, you should use integer control values for maximum speed. ■ Example The following example prints the first 11 columns of Pascal's triangle: 'Print the first MAXCOL columns of Pascal's Triangle, in which 'each number is the sum of the number immediately above it 'and the number immediately below it in the preceding column. CONST MAXCOL=11 DIM A(MAXCOL,MAXCOL) FOR M = 1 TO MAXCOL A(M,1) = 1 : A(M,M) = 1 'Top and bottom of each column is 1. NEXT FOR M = 3 TO MAXCOL FOR N = 2 TO M-1 A(M,N) = A(M-1,N-1) + A(M-1,N) NEXT NEXT Startrow = 13 'Go to the middle of the screen. FOR M = 1 TO MAXCOL Col = 6 * M Row = Startrow FOR N = 1 TO M LOCATE Row,Col : PRINT A(M,N) Row = Row + 2 'Go down 2 rows to print next number. NEXT PRINT Startrow = Startrow - 1 'Next column starts 1 row above NEXT 'preceding column. ■ Output 1 1 1 10 1 9 1 8 45 1 7 36 1 6 28 120 1 5 21 84 1 4 15 56 210 1 3 10 35 126 1 2 6 20 70 252 1 3 10 35 126 1 4 15 56 210 1 5 21 84 1 6 28 120 1 7 36 1 8 45 1 9 1 10 1 1 ──────────────────────────────────────────────────────────────────────────── FRE Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the amount of available memory ■ Syntax 1 FRE(numeric-expression) ■ Syntax 2 FRE(stringexpression) ■ Remarks The FRE function returns the following values when it has a numeric argument (numeric-expression): Argument Value Returned ────────────────────────────────────────────────────────────────────────── -1 The size, in bytes, of the largest nonstring array that could be dimensioned -2 The amount, in bytes, of unused stack space available to the program Any other numeric value The size of the next free block of string storage ────────────────────────────────────────────────────────────────────────── When the argument is a string expression (stringexpression), FRE returns the size, in bytes, of the free string storage. Before FRE returns the number of free bytes, it compacts the free string storage into a single block. ──────────────────────────────────────────────────────────────────────────── NOTE FRE(-2) returns meaningful values only when a program is executing. Values returned by FRE(-2) are not accurate when the function is called from the Immediate window, during program tracing, or when watching a variable. ──────────────────────────────────────────────────────────────────────────── ■ Example The following example shows some of the values FRE returns before and after dimensioning an array: ' ¢DYNAMIC PRINT "Before dimensioning arrays: " FRE(""),FRE(0),FRE(-1) DIM LARGE%(150,150), BIG$(5000) PRINT "After dimensioning arrays: " FRE(""),FRE(0),FRE(-1) ■ Output The actual values FRE will return on your own computer may be different. Before dimensioning arrays: 58420 58420 322120 After dimensioning arrays: 38404 38404 276496 ──────────────────────────────────────────────────────────────────────────── FREEFILE Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the next free BASIC file number ■ Syntax FREEFILE ■ Remarks The FREEFILE function returns the next valid unused file number. You can use this function to avoid having SUB or FUNCTION procedures use file numbers that are already in use. ■ Example The example below uses FREEFILE to obtain a file number for opening a file: INPUT "Enter file name ", Filename$ Filenum = FREEFILE OPEN Filename$ for Input as Filenum PRINT Filename$;" Opened as File # "; Filenum ■ Output Enter file name: Data.dat Data.dat Opened as File # 1 ──────────────────────────────────────────────────────────────────────────── FUNCTION Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Declares the name, the parameters, and the code that form the body of a FUNCTION procedure ■ Syntax FUNCTION name «(parameterlist)»«STATIC» . . . name = expression . . . END FUNCTION ■ Remarks The following list describes the parts of the FUNCTION statement: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Part Description Part Description ────────────────────────────────────────────────────────────────────────── name The name of the function. FUNCTION names follow the same rules as BASIC variable names and can include a type-declaration character (%, &, !, #, or $). Note that the type of the name determines the type of value the function returns. For example, to create a function that returns a string, you would include a dollar sign in the name or give it a name defined as a string name by a DEFSTR statement. parameterlist The list of variables, separated by commas, passed to the FUNCTION. The parameters are passed by reference, so any change to a parameter's value inside the function changes its value in the calling program. STATIC Indicates that the function's local variables are to be saved between calls. Without STATIC, the local variables are allocated each time the Part Description ────────────────────────────────────────────────────────────────────────── local variables are allocated each time the function is invoked, and the variables' values are lost when the function returns to the calling program. The STATIC attribute does not affect variables that are used in a FUNCTION but declared outside the FUNCTION in DIM or COMMON statements by use of the SHARED attribute. expression The return value of the function. A FUNCTION returns a value by assigning a value to the function name. If no value is assigned to the FUNCTION name, the FUNCTION returns a default value: a numeric function returns a value of zero, and a string function returns the null string (""). ────────────────────────────────────────────────────────────────────────── A parameterlist has the following syntax: variable«( )»« AS type»«, variable«( )»« AS type»...» A variable is any valid BASIC variable. The optional type can be either INTEGER, LONG, SINGLE, DOUBLE, STRING, or a user-defined type. Earlier versions of BASIC required the number of dimensions in parentheses after an array name. The number of dimensions is no longer required. Only the parentheses are required to indicate the parameter is an array. For example, the following statement indicates that both Keywords$ and KeywordTypes are arrays: FUNCTION ParseLine(Keywords$(),KeywordTypes()) A FUNCTION procedure is like a SUB procedure: it can accept parameters, perform a series of statements, and change the values of its parameters. Unlike a SUB, a FUNCTION is used in an expression in the same manner as a BASIC intrinsic function. Like SUB procedures, FUNCTION procedures use local variables. Any variable not in the parameter list is local to the FUNCTION unless it is declared as a shared variable in a SHARED statement, or unless the variable appears in a DIM or COMMON statement with the SHARED attribute. To return a value from a function, assign the value to the function name. For example, in a function named BinarySearch, you might assign the value of the constant FALSE to the name to indicate the value was not found: FUNCTION BinarySearch(...) CONST FALSE=0 . . . ' Value not found. Return a value of FALSE. IF Lower>Upper THEN BinarySearch=FALSE EXIT FUNCTION END IF . . . END FUNCTION Using the STATIC keyword slightly increases execution speed. STATIC is not usually used with recursive FUNCTION procedures. See the examples below. The EXIT FUNCTION statement provides an alternative exit from a FUNCTION. See the EXIT statement. Because BASIC may rearrange arithmetic expressions to attain greater efficiency, avoid using FUNCTION procedures that change program variables in arithmetic expressions. Also avoid using FUNCTION procedures that perform I/O in I/O statements. QuickBASIC FUNCTION procedures are recursive──they can call themselves to perform a given task. See the second example below and Chapter 4, "Programs and Modules." ■ See Also DECLARE (BASIC), DEF FN, EXIT, STATIC, SUB ■ Examples The following example uses a function to count the number of vowels in a string: ' Function definition. FUNCTION NumVowels (A$) STATIC Num = 0 ' Go through A$ a character at a time. FOR I = 1 TO LEN (A$) C$ = UCASE$ (MID$(A$,I,1)) IF INSTR ("AEIOU",C$)<> 0 THEN ' Find a vowel--count it. Num = Num + 1 END IF NEXT I NumVowels = Num END FUNCTION A$ = "The ultimate answer to the ultimate question is 42" PRINT CHR$(34)+A$+CHR$(34) PRINT "The number of vowels in the string is :";NumVowels (A$) ■ Output "The ultimate answer to the ultimate question is 42" The number of vowels in the string is : 18 The following example uses a recursive function (a function that calls itself) to find the length of a string. Notice that the STATIC keyword is not used. FUNCTION StrLen(X$) IF X$ = "" THEN ' The length of a null string is zero. StrLen=0 ELSE ' Non-null string--make a recursive call. ' The length of a non-null string is 1 ' plus the length of the rest of the string. StrLen=1+StrLen(MID$(X$,2)) END IF END FUNCTION LINE INPUT "Enter a string: ",InString$ PRINT "The string length is"; StrLen(InString$) ■ Output Enter a string: Once upon a time The string length is 16 ──────────────────────────────────────────────────────────────────────────── GET Statement──Graphics ──────────────────────────────────────────────────────────────────────────── ■ Action Stores graphic images from the screen ■ Syntax GET «STEP»(x1,y1) - «STEP»(x2,y2),arrayname«(indices)» ■ Remarks The list below describes the parts of the GET statement: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Part Description ────────────────────────────────────────────────────────────────────────── x1,y1,x2,y2 Coordinates marking a rectangular area on the screen. The placeholders x1, y1, x2, and y2 are numeric expressions that are the coordinates of diagonally opposite corners of the rectangle. STEP Keyword indicating that coordinates are relative to the most recently plotted point. For example, if the last point plotted were (10,10), then the actual coordinates referred to by STEP (5,10) would be (5+10,10+10) or (15,20). If the second coordinate pair in a GET statement has a STEP argument, it is relative to the first coordinate Part Description ────────────────────────────────────────────────────────────────────────── argument, it is relative to the first coordinate pair in the statement. arrayname Name assigned to the array that holds the image. This array can be of any numeric type; its dimensions must be large enough to hold the entire image. indices Numeric constants or variables indicating the element of the array where the saved image starts. ────────────────────────────────────────────────────────────────────────── The GET statement transfers a screen image into the array specified by arrayname. The PUT statement, associated with GET, transfers the image stored in the array onto the screen. The following formula gives the required size of the array in bytes: 4 + INT(((x2 - x1 + 1) * (bits-per-pixel-per-plane) + 7)/8) * planes * ((y2 - y1) + 1) The bits-per-pixel-per-plane and planes values depend on the specification set in the SCREEN statement. Table R.3 shows the number of bits per pixel per plane and the number of planes for each screen mode. Table R.3 Values for Bits per Pixel per Plane and for Planes ╓┌─┌────────────────────────┌───────────────────────┌────────────────────────╖ Bits per Pixel Screen Mode per Plane Planes ────────────────────────────────────────────────────────────────────────── 1 2 1 2 1 1 7 1 4 8 1 4 Bits per Pixel Screen Mode per Plane Planes ────────────────────────────────────────────────────────────────────────── 8 1 4 9 1 2 (if 64K of EGA memory) 4 (if > 64K EGA memory) 10 1 2 11 1 1 12 1 4 13 8 1 ────────────────────────────────────────────────────────────────────────── The bytes per element of an array are as follows: ■ Two bytes for an integer array element ■ Four bytes for a long-integer array element ■ Four bytes for a single-precision array element ■ Eight bytes for a double-precision array element For example, suppose you wanted to use the GET statement to store an image in high resolution (SCREEN 2). If the coordinates of the upper-left corner of the image are (0,0), and the coordinates of the lower- right corner are (32,32), then the required size of the array in bytes is 4 + INT((33 * 1 + 7)/8) * 1 * (33), or 169. This means an integer array with 85 elements would be large enough to hold the image. Unless the array type is integer or long, the contents of an array after a GET appear meaningless when inspected directly. Examining or manipulating noninteger arrays containing graphics images may cause run-time errors. One of the most useful things that can be done with GET and PUT is animation. See Chapter 5, "Graphics," in Programming in BASIC for a discussion of animation. ■ See Also PUT (Graphics) ■ Example See the example for BSAVE. ──────────────────────────────────────────────────────────────────────────── GET Statement──File I/O ──────────────────────────────────────────────────────────────────────────── ■ Action Reads from a disk file into a random-access buffer or variable ■ Syntax GET «#»filenumber«,«recordnumber»«,variable»» ■ Remarks The following list describes the GET statement's arguments: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Argument Description ────────────────────────────────────────────────────────────────────────── filenumber The number used in the OPEN statement to open the file. recordnumber For random-access files, the number of the record to be read. For binary-mode files, the byte position in the file where reading starts. The first record or byte position in a file is 1. If you omit recordnumber, the next record or byte (the one after the last GET or PUT, or the one pointed to by the last SEEK) is read into the buffer. The largest possible record number is 2^31-1, or 2,147,483,647. Argument Description ────────────────────────────────────────────────────────────────────────── 2^31-1, or 2,147,483,647. variable The variable used to receive input from the file. If you use a variable, you do not need to use CVD, CVL, CVI, or CVS to convert record fields to numbers. You may not use a FIELD statement with the file if you use the variable argument. For random-access files, you can use any variable as long as the length of the variable is less than or equal to the length of the record. Usually, a record variable defined to match the fields in a data record is used. For binary-mode files, you can use any variable. The GET statement reads as many bytes as there are in the variable. When you use a variable-length string variable, the statement reads as many bytes as there are Argument Description ────────────────────────────────────────────────────────────────────────── the statement reads as many bytes as there are characters in the string's value. For example, the following two statements read 10 bytes from file number 1: VarStrings$=STRING$ (10, " ") GET #1,,VarString$ See the examples and Chapter 3, "File and Device I/O," in Programming in BASIC for more information about using variables rather than FIELD statements for random-access files. A record cannot be longer than 32,767 bytes. ────────────────────────────────────────────────────────────────────────── You may omit the recordnumber, the variable, or both. If you omit the recordnumber but include the variable, you must still include the commas: GET #4,,FileBuffer If you omit both arguments, you do not include the commas: GET #4 The GET and PUT statements allow fixed-length input and output for BASIC communications files. Use GET carefully because if there is a communications failure, GET waits indefinitely for recordnumber characters. ──────────────────────────────────────────────────────────────────────────── NOTE When you use GET with the FIELD statement, you can use either INPUT # or LINE INPUT # after a GET statement to read characters from the random-access file buffer. You may use the EOF function after GET to see if the GET went beyond the end of the file. ──────────────────────────────────────────────────────────────────────────── ■ See Also CVI, CVS, CVL, CVD; FIELD; INPUT #; LINE INPUT #; LSET; MKD$, MKI$, MKL$, MKS$; PUT (File I/O); RSET; TYPE ■ Example The following program opens the file TESTDAT.DAT for random access and displays the contents on the screen: ' Read and display the contents of a file containing a ' name of up to 20 characters and a test score. ' Define record fields. TYPE TestRecord NameField AS STRING*20 ScoreField AS SINGLE END TYPE ' Open the test data file. DIM FileBuffer AS TestRecord OPEN "TESTDAT.DAT" FOR RANDOM AS #1 LEN=LEN(FileBuffer) ' Calculate number of records in the file. Max=LOF(1)/LEN(FileBuffer) ' Read and print contents of each record. FOR I=1 TO Max GET #1,I,FileBuffer PRINT FileBuffer.NameField,FileBuffer.ScoreField NEXT I CLOSE #1 ──────────────────────────────────────────────────────────────────────────── GOSUB...RETURN Statements ──────────────────────────────────────────────────────────────────────────── ■ Action Branches to, and returns from, a subroutine ■ Syntax GOSUB {linelabel1 | linenumber1 } . . . RETURN «linelabel2 | linenumber2 » ■ Remarks The GOSUB...RETURN statements take the following arguments: Argument Description ────────────────────────────────────────────────────────────────────────── linelabel1, linenumber1 The line number or line label that is the first line of the subroutine. linelabel2, linenumber2 The line label or line number where the subroutine returns. ────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── NOTE BASIC's SUB and FUNCTION procedures provide a more well-structured alternative to GOSUB... RETURN subroutines. ──────────────────────────────────────────────────────────────────────────── In addition to RETURN with no argument, BASIC supports RETURN with a line label or line number allowing a return from a subroutine to the statement having the specified line number or label, instead of returning to the statement after the GOSUB statement. Use this line-specific type of return with care. You may call a subroutine any number of times in a program. You may also call a subroutine from within another subroutine. How deeply you can nest subroutines is limited only by the available stack space (you may increase the stack space with the CLEAR statement). Subroutines that call themselves (recursive subroutines) can easily run out of stack space. RETURN with a line label or line number can only return control to a statement in the module-level code, not procedure-level code. See the example program. A subroutine may contain more than one RETURN statement. Simple RETURN statements (without the linelabel2, linenumber2 option) in a subroutine make BASIC branch back to the statement following the most recent GOSUB statement. Subroutines may appear anywhere in the program, but it is good programming practice to make them readily distinguishable from the main program. To prevent inadvertent entry into a subroutine, precede it with a STOP, END, or GOTO statement that directs program control around the subroutine. ──────────────────────────────────────────────────────────────────────────── IMPORTANT The preceding discussion of subroutines applies only to the targets of GOSUB statements, not subprograms delimited by SUB statements. Entering and exiting SUB blocks with GOSUB...RETURN statements is not supported. ──────────────────────────────────────────────────────────────────────────── ■ See Also RETURN, SUB ■ Example The following example shows the use of RETURN linelabel statements in module-level code: PRINT "in module-level code" GOSUB Sub1 PRINT "this line in main routine should be skipped" Label1: PRINT "back in module-level code" END Sub1: PRINT "in subroutine one" GOSUB Sub2 PRINT "this line in subroutine one should be skipped" Label2: PRINT "back in subroutine one" RETURN Label1 Sub2: PRINT "in subroutine two" RETURN Label2 ■ Output in module-level code in subroutine one in subroutine two back in subroutine one back in module-level code ──────────────────────────────────────────────────────────────────────────── GOTO Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Branches unconditionally to the specified line ■ Syntax GOTO {linelabel | linenumber} ■ Remarks The GOTO statement provides a way to branch unconditionally to another line (linelabel or linenumber). A GOTO statement can branch only to another statement at the same level of a program. You cannot use GOTO to enter or exit a SUB, FUNCTION, or multiline DEF FN function. You can, however, use GOTO to control program flow within any of these program structures. It is good programming practice to use structured control statements (DO...LOOP, FOR, IF..THEN...ELSE, SELECT CASE) instead of GOTO statements because a program with many GOTO statements is difficult to read and debug. ■ Example The following program prints the area of the circle with the input radius: PRINT "Input 0 to end." Start: INPUT R IF R = 0 THEN END ELSE A = 3.14 * R^2 PRINT "Area =";A END IF GOTO Start ■ Output Input 0 to end. ? 5 Area = 78.5 ? 0 ──────────────────────────────────────────────────────────────────────────── HEX$ Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns a string that represents the hexadecimal value of the decimal argument expression ■ Syntax HEX$(expression) ■ Remarks The argument expression is rounded to an integer or, if the expression is outside the integer range, a long integer before the HEX$ function evaluates it. ■ See Also OCT$ ■ Example The following example prints the hexadecimal representation of an input value: INPUT X A$ = HEX$(X) PRINT X "decimal is " A$ " hexadecimal" ■ Output ? 32 32 decimal is 20 hexadecimal ──────────────────────────────────────────────────────────────────────────── IF...THEN...ELSE Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Allows conditional execution, based on the evaluation of a Boolean expression ■ Syntax 1 (Single Line) IF booleanexpression THEN thenpart «ELSE elsepart» ■ Syntax 2 (Block) IF booleanexpression1 THEN «statementblock-1» «ELSEIF booleanexpression2 THEN «statementblock-2»» . . . «ELSE «statementblock-n»» END IF ■ Remarks The single-line form of the statement is best used for short, straightforward tests where only one action is taken. The block form provides several advantages: ■ The block form provides more structure and flexibility than the single-line form by allowing conditional branches across several lines. ■ With the block form, more complex conditions can be tested. ■ The block form lets you use longer statements and structures within the THEN...ELSE portion of the statement. ■ The block form allows your program's structure to be guided by logic rather than by how many statements fit on a line. Programs that use block-form IF...THEN...ELSE are usually easier to read, maintain, and debug. The single-line form is never required. Any program using single-line IF...THEN...ELSE statements can be written using block form. SINGLE-LINE IF...THEN...ELSE The following list describes the parts of the single-line form: Part Description ────────────────────────────────────────────────────────────────────────── booleanexpression Any expression that evaluates to true (nonzero) or false (zero). thenpart, elsepart The statements or branches performed when booleanexpression is true (thenpart) or false (elsepart). Both parts have the same syntax, which is described below. ────────────────────────────────────────────────────────────────────────── The thenpart and the elsepart both have the following syntax: {statements | «GOTO» linenumber | GOTO linelabel } The following list describes the parts of the thenpart and elsepart syntax: Part Description ────────────────────────────────────────────────────────────────────────── statements One or more BASIC statements, separated by colons linenumber A valid BASIC program line number linelabel A valid BASIC line label ────────────────────────────────────────────────────────────────────────── Note that GOTO is optional with a line number but is required with a line label. The thenpart is executed if the booleanexpression is true; if the booleanexpression is false, the elsepart is executed. If the ELSE clause is not present, control passes to the next statement in the program. You can have multiple statements with a condition, but they must be on the same line and separated by colons: IF A > 10 THEN A=A+1:B=B+A:LOCATE 10,22:PRINT B,A BLOCK IF...THEN...ELSE The following list describes the parts of the block IF...THEN...ELSE: Part Description ────────────────────────────────────────────────────────────────────────── booleanexpression1, Any expression that evaluates to true (nonzero) booleanexpression2 or false (zero) statementblock-1, One or more BASIC statements on one or more lines statementblock-2, statementblock-n ────────────────────────────────────────────────────────────────────────── In executing a block-form IF, QuickBASIC tests booleanexpression1, the first Boolean expression. If the Boolean expression is true (nonzero), the statements following THEN are executed. If the first Boolean expression is false (zero), QuickBASIC begins evaluating each ELSEIF condition in turn. When QuickBASIC finds a true condition, the statements following the associated THEN are executed. If none of the ELSEIF conditions are true, the statements following the ELSE are executed. After the statements following a THEN or ELSE are executed, the program continues with the statement following the END IF. The ELSE and ELSEIF blocks are both optional. You can have as many ELSEIF clauses as you would like in a block IF. Any of the statement blocks can contain nested block IF statements. QuickBASIC looks at what appears after the THEN keyword to determine whether or not an IF statement is a block IF. If anything other than a comment appears after THEN, the statement is treated as a single-line IF statement. A block IF statement must be the first statement on a line. The ELSE, ELSEIF, and END IF parts of the statement can only have a line number or line label in front of them. The block must end with an END IF statement. For more information, see Chapter 1, "Control-Flow Structures," in Programming in BASIC. ■ See Also SELECT CASE ■ Examples The following program fragments demonstrate the use of single-line and block IF...THEN...ELSE and illustrate the differences. The first example demonstrates the single-line IF...THEN...ELSE form: DO INPUT "Enter a number greater than 0 and less than 10,000:",X IF X>=0 AND X<10000 THEN EXIT DO ELSE PRINT X;"out of range" LOOP IF X<10 THEN Y=1 ELSE IF X<100 THEN Y=2 ELSE IF X<1000 THEN Y=3 ELSE Y=4 PRINT "The number has";Y;"digits" In the second example the block IF...THEN...ELSE makes the code more readable and more powerful: DO INPUT "Enter a number greater than 0 and less than 100,000:",X IF X>0 AND X<100000 THEN EXIT DO ELSE PRINT X;"out of range" END IF LOOP IF X<10 THEN Y=1 ELSEIF X<100 THEN Y=2 ELSEIF X<1000 THEN Y=3 ELSEIF X<10000 THEN Y=4 ELSE Y=5 END IF PRINT "The number has";Y;"digits" ──────────────────────────────────────────────────────────────────────────── INKEY$ Function ──────────────────────────────────────────────────────────────────────────── ■ Action Reads a character from the keyboard ■ Syntax INKEY$ ■ Remarks The INKEY$ function returns a one- or two-byte string containing a character read from the standard input device. A null string is returned if no character is waiting there. A one-character string contains the actual character read from the keyboard, while a two-character string indicates an extended code, the first character of which is hexadecimal 00. For a complete list of these codes, see Appendix A, "Keyboard Scan Codes and ASCII Character Codes." The standard input device is usually the keyboard. INKEY$ does not echo characters to the screen; instead, all characters are passed through to the program except for these: ■ CTRL+BREAK, which halts program execution ■ CTRL+ALT+DEL, which does a system reboot ■ CTRL+NUMLOCK, which causes program execution to pause ■ PRTSC, which prints the screen ■ Example The following program fragment shows a common use of INKEY$──pausing until the user presses a key: PRINT "Press any key to continue..." DO LOOP WHILE INKEY$="" ──────────────────────────────────────────────────────────────────────────── INP Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the byte read from an I/O port ■ Syntax INP(port) ■ Remarks The port must be an integer in the range 0-65,535. The INP function complements the OUT statement. The INP and OUT statements give a BASIC program direct control over the hardware in a system through the I/O ports. These statements must be used carefully because they directly manipulate the system hardware. ■ See Also OUT, WAIT ■ Example See the example for the OUT statement. ──────────────────────────────────────────────────────────────────────────── INPUT Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Allows input from the keyboard during program execution ■ Syntax INPUT«;»«"promptstring"{; | ,}» variablelist ■ Remarks The following list describes the parts of the INPUT statement: Part Description ────────────────────────────────────────────────────────────────────────── ; A semicolon immediately after INPUT keeps the cursor on the same line after the user presses ENTER. promptstring A string constant printed before the prompt character. ; Prints a question mark at the end of the promptstring. , Prints the promptstring without a question mark. variablelist A list of variables, separated by commas, to accept the input values. See the discussion below. ────────────────────────────────────────────────────────────────────────── The INPUT statement causes the program to pause and wait for data. You can then enter the required data at the keyboard. The data that you enter is assigned to the variables in variablelist. The number of data items that you supply must be the same as the number of variables in the list. The first character encountered after a comma that is not a space, carriage return, or line feed is assumed to be the start of a new item. The variable names in the list may be numeric- or string-variable names (including subscripted variables), array elements, or elements of records. The type of each data item that you input must agree with the type of the variable. (Strings input to an INPUT statement need not be surrounded by quotation marks.) If this first character is a quotation mark ("), the string item will consist of all characters read between the first quotation mark and the second. This means a quoted string may not contain a quotation mark as a character. If the first character of the string is not a quotation mark, the string is an unquoted string and terminates on a comma, carriage return, or line feed. Input stored in elements of a record must be input as single elements: TYPE Demograph FullName AS STRING*25 Age AS INTEGER END TYPE DIM Person AS Demograph INPUT "Enter name and age: ";Person.FullName,Person.Age Responding to an INPUT statement with too many or too few items, or with the wrong type of value (for example, numeric instead of string), produces this error message: Redo from start No assignment of input values is made until you give an acceptable response. It is possible to edit a line of input before you press ENTER. The following list describes the key combinations that allow you to move the cursor, delete text, and insert text on the input line: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Keys Action ────────────────────────────────────────────────────────────────────────── CTRL+\ or RIGHT Moves cursor one character to the right. Keys Action ────────────────────────────────────────────────────────────────────────── CTRL+] or LEFT Moves cursor one character to the left. CTRL+F or CTRL+RIGHT Moves cursor one word to the right. CTRL+B or CTRL+LEFT Moves cursor one word to the left. CTRL+K or HOME Moves cursor to the beginning of the input line. CTRL+N or END Moves cursor to the end of the input line. CTRL+R or INS Toggles insert mode on and off. When insert mode is on, character above and those to the right of the cursor are shifted to the right as new characters are entered. CTRL+I or TAB Tabs right and inserts (insert mode on), or overwrites (insert mode off). Keys Action ────────────────────────────────────────────────────────────────────────── DEL Deletes the character at the cursor. CTRL+H or BACKSPACE Deletes the character to the left of the cursor, unless the cursor is at the beginning of the input, in which case it deletes the character at the cursor. CTRL+E or CTRL+END Deletes to the end of the line. CTRL+U or ESC Deletes entire line, regardless of cursor position. CTRL+M or RETURN Stores input line. CTRL+T Toggles function key label display on and off at bottom of screen. CTRL+BREAK or CTRL+C Terminates input (exits compiled program). Keys Action ────────────────────────────────────────────────────────────────────────── CTRL+BREAK or CTRL+C Terminates input (exits compiled program). ────────────────────────────────────────────────────────────────────────── ■ Example The following example calculates the area of a circle from an input radius: PI = 3.141593 : R = -1 PRINT "Enter radius (0 to end)." DO WHILE R PRINT INPUT;"If radius = ", R IF R > 0 THEN A = PI*R^2 PRINT ", the area of the circle =" A END IF LOOP ■ Output Enter radius (0 to end). If radius = 3, the area of the circle = 28.27434 If radius = 4, the area of the circle = 50.26549 If radius = 0 ──────────────────────────────────────────────────────────────────────────── INPUT # Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Reads data items from a sequential device or file and assigns them to variables ■ Syntax INPUT #filenumber, variablelist ■ Remarks The filenumber is the number used when the file was opened for input. The variablelist contains the names of the variables that are assigned values read from the file. (The variable type must match the type specified by the variable name.) The data items in the file should appear just as they would if you were entering data in response to an INPUT statement. Separate numbers with a space, carriage return, line feed, or comma. Separate strings with a carriage return or linefeed (leading spaces are ignored). The end-of-file character will end either a numeric or string entry. If BASIC is scanning the sequential data file for a string item, it will also ignore leading spaces, carriage returns, and line feeds. If end-of-file is reached when a numeric or string item is being INPUT, the item is terminated. ■ See Also INPUT, INPUT$ ■ Example The following program reads a series of test scores from a sequential file and calculates the average score: DEFINT A-Z OPEN "class.dat" FOR INPUT AS #1 DO WHILE NOT EOF(1) Count=Count+1 INPUT #1,Score Total=Total+Score PRINT Count;Score LOOP PRINT PRINT "Total students:";Count;" Average score:";Total/Count END ■ Output 1 97 2 84 3 63 4 89 5 100 Total students: 5 Average score: 86.6 ──────────────────────────────────────────────────────────────────────────── INPUT$ Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns a string of characters read from the specified file ■ Syntax INPUT$(n«,«#»filenumber») ■ Remarks The n is the number of characters (bytes) to read from the file. The filenumber is the number that was used in opening the file. If the file is opened for random access, the argument n must be less than or equal to the record length set by the LEN clause in the OPEN statement (or less than or equal to 128 if the record length is not set). If the given file is opened for binary or sequential access, then n must be less than or equal to 32,767. If the filenumber is not specified, the characters are read from the standard input device. (If input has not been redirected, the keyboard is the standard input device). You can use the DOS redirection symbols (<, >, or >>) or the pipe symbol (|) to redefine the standard input or standard output for an executable file created with BASIC. (See your operating system manual for a complete discussion of redirection and pipes.) No characters are echoed on the screen. All control characters are passed through except CTRL+BREAK, which interrupts execution of the function. ■ Example The following program prints a file on the screen. It uses INPUT$ to read one character at a time, then converts the character, as necessary, and displays it. 'ASCII codes for tab, and line feed. CONST HTAB = 9, LFEED = 10 INPUT "Display which file"; Filename$ OPEN Filename$ FOR INPUT AS #1 CLS DO WHILE NOT EOF(1) ' Input a single character from the file. S$=INPUT$(1,#1) ' Convert the character to an integer and ' turn off the high bit so WordStar(R) files ' can be displayed. C=ASC(S$) AND &H7F ' Is it a printable character? IF (C >= 32 AND C <= 126) OR C = HTAB OR C = LFEED THEN PRINT CHR$(C); END IF LOOP END ──────────────────────────────────────────────────────────────────────────── INSTR Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the character position of the first occurrence of a string in another string ■ Syntax INSTR(«start,»stringexpression1,stringexpression2) ■ Remarks The following list describes the INSTR function arguments: Argument Description ────────────────────────────────────────────────────────────────────────── start An optional offset that sets the position for starting the search; start must be in the range 1-32,767. If start is not given, the INSTR function begins the search at the first character of stringexpression1. stringexpression1 The string being searched. stringexpression2 The string to look for. ────────────────────────────────────────────────────────────────────────── The arguments stringexpression1 and stringexpression2 can be string variables, string expressions, or string literals. The value returned by INSTR depends on these conditions: Condition Value Returned ────────────────────────────────────────────────────────────────────────── stringexpression2 found in The position at which the match is stringexpression1 found start greater than length of 0 stringexpression1 stringexpression1 is null string 0 stringexpression2 cannot be found 0 stringexpression2 is null string start (if given); otherwise, 1 ────────────────────────────────────────────────────────────────────────── Use the LEN function to find the length of stringexpression1. ■ Example The following fragment uses INSTR and UCASE$ to look for Mr., Mrs., or Ms. in a name in order to deduce the person's sex: ' Get a name. DO INPUT "Enter name: ", Nm$ LOOP UNTIL LEN(Nm$)>=3 ' Convert lowercase letters to uppercase. Nm$ = UCASE$(Nm$) ' Look for MS., MRS., or MR. to set Sex$. IF INSTR(Nm$,"MS.") > 0 OR INSTR(Nm$,"MRS.") > 0 THEN Sex$ = "F" ELSEIF INSTR(Nm$,"MR.") > 0 THEN Sex$ = "M" ELSE ' Can't deduce sex, so query user. DO INPUT "Enter sex (M/F): ", Sex$ Sex$ = UCASE$(Sex$) LOOP WHILE Sex$ <> "M" AND Sex$ <> "F" END IF ■ Output Enter name: Elspeth Brandtkeep Enter sex (M/F): x Enter sex (M/F): F ──────────────────────────────────────────────────────────────────────────── INT Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the largest integer less than or equal to numeric-expression ■ Syntax INT(numeric-expression) ■ Remarks The INT function removes the fractional part of its argument. ■ See Also CINT, FIX ■ Example The following example compares the output from the three functions that convert numeric data to integers: PRINT " N","INT(N)","CINT(N)","FIX(N)" : PRINT FOR I% = 1 TO 6 READ N PRINT N, INT(N), CINT(N), FIX(N) NEXT DATA 99.3, 99.5, 99.7, -99.3, -99.5, -99.7 ■ Output N INT(N) CINT(N) FIX(N) 99.3 99 99 99 99.5 99 100 99 99.7 99 100 99 -99.3 -100 -99 -99 -99.5 -100 -100 -99 -99.7 -100 -100 -99 ──────────────────────────────────────────────────────────────────────────── IOCTL$ Function ──────────────────────────────────────────────────────────────────────────── ■ Action Receives a control data string from a device driver ■ Syntax IOCTL$ («#» filenumber) ■ Remarks The filenumber is the BASIC file number used to open the device. The IOCTL$ function is most frequently used to test whether an IOCTL statement succeeded or failed or to obtain current status information. You could use IOCTL$ to ask a communications device to return the current baud rate, information on the last error, logical line width, and so on. The exact information returned would depend on the specific device driver. The IOCTL$ function works only if all three of the following conditions are met: 1. The device driver is installed. 2. The device driver states that it processes IOCTL strings. See the documentation for the driver. You can also test for IOCTL support through DOS function &H44 by using interrupt &H21 and the CALL INTERRUPT routine. See the CALL INTERRUPT statement for more information. 3. BASIC performs an OPEN statement on a file on that device. ──────────────────────────────────────────────────────────────────────────── NOTE BASIC devices (LPT1:, COM1:, COM2:, SCRN:, CONS:) and DOS block devices (A: through Z:) do not support IOCTL. ──────────────────────────────────────────────────────────────────────────── ■ See Also IOCTL ■ Example The following example opens the device driver ENGINE and uses the IOCTL$ function to test for raw data mode being set: OPEN "\DEV\ENGINE" FOR OUTPUT AS #1 IOCTL #1, "RAW" 'Tells the device that the data is raw. ' If the character driver "ENGINE" responds "false" from ' the raw data mode in the IOCTL statement, then the file ' is closed. IF IOCTL$(1) = "0" THEN CLOSE 1 ──────────────────────────────────────────────────────────────────────────── IOCTL Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Transmits a control data string to a device driver ■ Syntax IOCTL «#»filenumber, string ■ Remarks The filenumber is the BASIC file number used to open the device. The string is the command sent to the device. Commands are specific to the device driver. See the documentation for the device driver to find out what the valid IOCTL commands are. An IOCTL control data string can be up to 32,767 bytes long. The IOCTL statement works only if all three of the following conditions are met: 1. The device driver is installed. 2. The device driver states that it processes IOCTL strings. See the documentation for the driver. You can also test for IOCTL support through DOS function &H44 by using interrupt &H21 and the CALL INTERRUPT routine. See the Microsoft MS-DOS Programmer's Reference and the CALL INTERRUPT statement for more information. 3. BASIC performs an OPEN on a file on that device, and the file is still open. Most standard DOS device drivers do not process IOCTL strings, and you must determine if the specific driver accepts the command. ■ See Also IOCTL$ ■ Example If you wanted to set the page length to 66 lines per page on LPT1, your statement might look like this: OPEN "\DEV\LPT1" FOR OUTPUT AS 1 IOCTL #1, "PL66" ──────────────────────────────────────────────────────────────────────────── KEY Statements ──────────────────────────────────────────────────────────────────────────── ■ Action Assign soft-key string values to FUNCTION keys, then display the values and enable or disable the FUNCTION key display line ■ Syntax KEY n, stringexpression KEY LIST KEY ON KEY OFF ■ Remarks The placeholder n is a number representing the FUNCTION key. The values for n are 1 to 10 for the FUNCTION keys, and 30 and 31 for FUNCTION keys F11 and F12 on 101-key keyboards. The stringexpression is a string of up to 15 characters that is returned when the FUNCTION key is pressed. If the stringexpression is longer than 15 characters, the extra characters are ignored. The KEY statement allows you to designate special "soft-key" functions──strings that are returned when FUNCTION keys are pressed. Assigning a null string to a soft key disables the FUNCTION key as a soft key. If the FUNCTION key number is not in the correct range, an error message is displayed that reads Illegal function call, and the previous key string expression is retained. You may display soft keys with the KEY ON, KEY OFF, and KEY LIST statements: Statement Action ────────────────────────────────────────────────────────────────────────── KEY ON Displays the first six characters of the soft-key string values on the bottom line of the screen. KEY OFF Erases the soft-key display from the bottom line, making that line available for program use. It does not disable the FUNCTION keys. KEY LIST Displays all soft-key values on the screen, with all 15 characters of each key displayed. ────────────────────────────────────────────────────────────────────────── If a soft key is pressed, the effect is the same as if the user typed the string associated with the soft key. INPUT$, INPUT, and INKEY$ can all be used to read the string produced by pressing the soft key. ■ Examples The following examples show how to assign a string to a soft key and how to disable a soft key: KEY 1,"MENU"+CHR$(13) 'Assigns to soft key 1 the string '"MENU" followed by a carriage return. KEY 1,"" 'Disables soft key 1. The following program uses KEY statements to set up one-key equivalents of menu selections. For example, pressing F1 is the same as entering the string Add: DIM KeyText$(3) DATA Add, Delete, Quit ' Assign soft-key strings to F1 to F3. FOR I=1 TO 3 READ KeyText$(I) KEY I, KeyText$(I)+CHR$(13) NEXT I ' Print menu. PRINT " Main Menu" : PRINT PRINT " Add to list (F1)" PRINT " Delete from list (F2)" PRINT " Quit (F3)" : PRINT ' Get input and respond. DO LOCATE 7,1 : PRINT SPACE$(50); LOCATE 7,1 : INPUT " Enter your choice:",R$ SELECT CASE R$ CASE "Add", "Delete" LOCATE 10,1 : PRINT SPACE$(15); LOCATE 10,1 : PRINT R$; CASE "Quit" EXIT DO CASE ELSE LOCATE 10,1 : PRINT "Enter first word or press key." END SELECT LOOP ──────────────────────────────────────────────────────────────────────────── KEY (n) Statements ──────────────────────────────────────────────────────────────────────────── ■ Action Start or stop trapping of specified keys ■ Syntax KEY(n) ON KEY(n) OFF KEY(n) STOP ■ Remarks The argument n is the number of a FUNCTION key, a cursor-direction key, or a user-defined key. (See the KEY statement for information on assigning soft-key values to FUNCTION keys.) The values of n are as follows: Value Key ────────────────────────────────────────────────────────────────────────── 1-10 The FUNCTION keys F1-F10 11 UP 12 LEFT 13 RIGHT 14 DOWN 15-25 User-defined keys 30-31 The FUNCTION keys F11-F12 on 101-key keyboards ────────────────────────────────────────────────────────────────────────── LEFT, RIGHT, UP, and DOWN refer to the direction keys. You can enable trapping of combination keys by using a variation of the KEY statement: KEY n, CHR$(keyboardflag) + CHR$(scancode) The argument n is in the range 15-25 to indicate a user-defined key. The keyboardflag can be any combination of the following hexadecimal values: Value Key ────────────────────────────────────────────────────────────────────────── &H00 No keyboard flag &H01-&H03 Either SHIFT key &H04 CTRL &H08 ALT &H20 NUMLOCK &H40 CAPSLOCK &H80 101-key keyboard extended keys ────────────────────────────────────────────────────────────────────────── You can add the values together to test for multiple shift states. A keyboardflag value of &H12 would test for both CTRL and ALT being pressed, for example. Because key trapping assumes the left and right SHIFT keys are the same, you can use either &H01, &H02, or &H03 to indicate a SHIFT key. The scancode argument is a number identifying one of the 83 keys to trap, as shown in Table R.4. Table R.4 Keyboard Scan Codes ╓┌─┌───────────┌────────────┌───────────┌───────────┌────────────┌───────────╖ Code Code Code Key in Hex Key in Hex Key in Hex ────────────────────────────────────────────────────────────────────────── ESC 01 CTRL 1D SPACEBAR 39 ! or 1 02 A 1E CAPS LOCK 3A # or 3 04 D 20 F2 3C Code Code Code Key in Hex Key in Hex Key in Hex ────────────────────────────────────────────────────────────────────────── # or 3 04 D 20 F2 3C $ or 4 05 F 21 F3 3D % or 5 06 G 22 F4 3E ^ or 6 07 H 23 F5 3F & or 7 08 J 24 F6 40 * or 8 09 K 25 F7 41 ( or 9 0A L 26 F8 42 ) or 0 0B : or ; 27 F9 43 _ or - 0C " or ' 28 F10 44 + or = 0D ~ or ` 29 NUM LOCK 45 LEFT 0E LEFT SHIFT 2A SCROLL LOCK 46 TAB 0F | or \ 2B HOME or 7 47 Q 10 Z 2C UP or 8 48 W 11 X 2D PGUP or 9 49 E 12 C 2E - 4A R 13 V 2F LEFT or 4 4B T 14 B 30 5 4C Y 15 N 31 RIGHT or 6 4D Code Code Code Key in Hex Key in Hex Key in Hex ────────────────────────────────────────────────────────────────────────── Y 15 N 31 RIGHT or 6 4D U 16 M 32 + 4E I 17 < or , 33 END or 1 4F O 18 > or . 34 DOWN or 2 50 P 19 ? or / 35 PGDN or 3 51 { or [ 1A RIGHT SHIFT 36 INS or 0 52 } or ] 1B PRTSC or * 37 DEL or . 53 RETURN 1C ALT 38 ────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── NOTE The scan codes in Table R.4 are equivalent to the first column of the scan code table in Appendix A, "Keyboard Scan Codes and ASCII Character Codes." The codes in the other columns of the table in the appendix should not be used for key trapping. ──────────────────────────────────────────────────────────────────────────── The KEY(n) ON statement enables soft-key or cursor-direction-key event trapping by an ON KEY statement. If you specify a nonzero line number in the ON KEY statement while trapping is enabled, BASIC checks to see if you have pressed KEY(n). If you have, BASIC executes the GOSUB clause in the ON KEY statement. The text that would normally be associated with a FUNCTION key is not input. When you are working in the environment, QuickBASIC tests between statements for key presses. In stand-alone programs, you can specify checking between lines. KEY(n) OFF disables the event trap; even if an event takes place, it is not remembered. KEY(n) STOP inhibits the event trap; that is, if you press the specified key your action is remembered and an ON KEY event trap is executed as soon as a KEY(n) ON statement is executed. ■ See Also ON event ■ Example This example traps the DOWN direction key and CTRL+S (control key and lowercase "s"). To trap the combination of the CTRL key and uppercase "s," you need to trap CTRL+SHIFT and CTRL+CAPS LOCK+S. I = 0 PRINT "Press DOWN direction key to end." KEY 15,CHR$(&H04)+CHR$(&H1f) KEY(15) ON 'Trap CTRL+s. KEY(14) ON 'Trap DOWN direction key. ON KEY(15) GOSUB Keytrap ON KEY(14) GOSUB Endprog Idle: GOTO Idle 'Endless loop Keytrap: 'Counts the number of times CTRL+s pressed. I = I + 1 RETURN Endprog: PRINT "CTRL+s trapped"; I; "times" END RETURN ──────────────────────────────────────────────────────────────────────────── KILL Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Deletes a file from disk ■ Syntax KILL filespec ■ Remarks The KILL statement is similar to the DOS ERASE or DEL commands. KILL is used for all types of disk files: program files, random data files, and sequential data files. The filespec may contain question marks (?) or asterisks (*) used as wild cards. A question mark matches any single character in the file name or extension. An asterisk matches one or more characters starting at its position. You can use KILL only to delete files. To delete directories, use the RMDIR command. Using KILL to delete a file that is currently open produces an error message that reads File already open. ──────────────────────────────────────────────────────────────────────────── WARNING Be extremely careful when using wild cards with KILL. You can delete files unintentionally with the wild card characters. ──────────────────────────────────────────────────────────────────────────── ■ Examples The following examples show the effect of wild-card characters when used with KILL: KILL "DATA1?.DAT" 'Kills any file with a six-character 'base name starting with DATA1 and 'also with the extension .DAT. KILL "DATA1.*" 'Kills any file with the base name 'DATA1 and any extension. KILL "\GREG\*.DAT" 'Kills any file with the extension '.DAT in a subdirectory called GREG. The following program deletes the file specified in the command line: DEFINT A-Z ON ERROR GOTO Errorhandle 'Set up error handling. FileName$ = COMMAND$ 'Get file name. KILL FileName$ END Errorhandle: Number = ERR IF Number = 53 THEN PRINT "Couldn't delete " FileName$ ; PRINT "; file does not exist in current directory" ELSE PRINT "Unrecoverable error:";Number ON ERROR GOTO 0 'ON ERROR GOTO zero aborts program. END IF RESUME NEXT ──────────────────────────────────────────────────────────────────────────── LBOUND Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the lower bound (smallest available subscript) for the indicated dimension of an array ■ Syntax LBOUND(array«,dimension») ■ Remarks The LBOUND function is used with the UBOUND function to determine the size of an array. LBOUND takes the following arguments: Argument Description ────────────────────────────────────────────────────────────────────────── array The name of the array being dimensioned dimension An integer ranging from 1 to the number of dimensions in array: indicates which dimension's lower bound is returned ────────────────────────────────────────────────────────────────────────── For an array dimensioned as follows, LBOUND returns the values listed below: DIM A(1 TO 100, 0 TO 50, -3 TO 4) Invocation Value Returned ────────────────────────────────────────────────────────────────────────── LBOUND(A,1) 1 LBOUND(A,2) 0 LBOUND(A,3) -3 ────────────────────────────────────────────────────────────────────────── The default lower bound for any dimension is either 0 or 1, depending on the setting of the OPTION BASE statement. If OPTION BASE is 0, the default lower bound is 0, and if OPTION BASE is 1, the default lower bound is 1. Arrays dimensioned using the TO clause in the DIM statement may have any integer value as a lower bound. You may use the shortened syntax LBOUND(array) for one-dimensional arrays, since the default value for dimension is 1. Use the UBOUND function to find the upper limit of an array dimension. ■ See Also UBOUND ■ Example The LBOUND and UBOUND functions may be used to determine the size of an array passed to a subprogram, as in the following program fragment: CALL Prntmat(Array()) . . . ' Print a matrix (two-dimensional array). SUB Prntmat(A(2)) STATIC ' Outer loop controls row (dimension 1). FOR I% = LBOUND(A,1) TO UBOUND(A,1) ' Inner loop controls column (dimension 2). FOR J% = LBOUND(A,2) TO UBOUND(A,2) PRINT A(I%,J%);" "; NEXT J% PRINT:PRINT NEXT I% END SUB ──────────────────────────────────────────────────────────────────────────── LCASE$ Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns a string expression with all letters in lowercase ■ Syntax LCASE$ (stringexpression) ■ Remarks The LCASE$ function takes a string variable, string constant, or string expression as its single argument. LCASE$ works with both variable- and fixed-length strings. LCASE$ and UCASE$ are helpful in string comparison operations where tests need to be case insensitive. ■ See Also UCASE$ ■ Example The following example converts uppercase characters in a string to lowercase characters: ' Program to convert to lowercase. READ Word$ PRINT LCASE$(Word$); DATA "THIS IS THE STRING in lowercase." ■ Output this is the string in lowercase. ──────────────────────────────────────────────────────────────────────────── LEFT$ Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns a string consisting of the leftmost n characters of a string ■ Syntax LEFT$(stringexpression,n) ■ Remarks The argument stringexpression can be any string variable, any string constant, or any string expression. The argument n is a numeric expression in the range 0-32,767 indicating how many characters are to be returned. If n is greater than the number of characters in stringexpression, the entire string is returned. To find the number of characters in stringexpression, use LEN(stringexpression). If n is zero, the null string (length zero) is returned. ■ See Also MID$, RIGHT$ ■ Example The following example prints the leftmost five characters of A$: A$="BASIC LANGUAGE" B$=LEFT$(A$,5) PRINT B$ ■ Output BASIC ──────────────────────────────────────────────────────────────────────────── LEN Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the number of characters in a string or the number of bytes required by a variable ■ Syntax LEN(stringexpression) LEN(variable) ■ Remarks In the first form, LEN returns the number of characters in the argument stringexpression. The second syntax returns the number of bytes required by a BASIC variable. This syntax is particularly useful for determining the correct record size of a random-access file. ■ Example The following example prints the sizes of BASIC variables of several different types and also prints the length of a string: TYPE EmpRec EmpName AS STRING*20 EmpNum AS INTEGER END TYPE DIM A AS INTEGER, B AS LONG, C AS SINGLE, D AS DOUBLE DIM E AS EmpRec PRINT "Integer:" LEN(A) PRINT "Long:" LEN(B) PRINT "Single:" LEN(C) PRINT "Double:" LEN(D) PRINT "EmpRec:" LEN(E) PRINT "A string:" LEN("A string.") END ■ Output Integer: 2 Long: 4 Single: 4 Double: 8 EmpRec: 22 A string: 9 ──────────────────────────────────────────────────────────────────────────── LET Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Assigns the value of an expression to a variable ■ Syntax «LET»variable=expression ■ Remarks Notice that the word LET is optional. The equal sign in the statement is enough to inform QuickBASIC that the statement is an assignment statement. LET statements can be used with record variables only when both variables are the same user-defined type. Use the LSET statement for assigning record variables of different user-defined types. ■ See Also LSET ■ Examples Corresponding lines perform the same function in these two examples: LET D=12 LET E=12-2 LET F=12-4 LET SUM=D+E+F . . . or D=12 E=12-2 F=12-4 SUM=D+E+F . . . ──────────────────────────────────────────────────────────────────────────── LINE Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Draws a line or box on the screen ■ Syntax LINE ««STEP» (x1,y1)»-«STEP» (x2,y2) «,«color»«,«B«F»»«,style»»» ■ Remarks The coordinates (x1,y1) and (x2,y2) specify the endpoints of the line; note that the order in which these endpoints appear is unimportant, since a line from (10,20) to (120,130) is the same as a line from (120,130) to (10,20). The STEP option makes the specified coordinates relative to the most recent point, instead of absolute, mapped coordinates. For example, if the most recent point referred to by the program is (10,10), then LINE -STEP (10,5) draws a line from (10,10) to the point with x-coordinate equal to 10 + 10 and y-coordinate equal to 10 + 5, or (20,15). You may establish a new most recent point by initializing the screen with the CLS and SCREEN statements. Using the PSET, PRESET, CIRCLE, and DRAW statements will also establish a new most recent point. Variations of the STEP argument are shown below. For the following examples, assume that the last point plotted was (10,10): ╓┌─┌────────────────────────────────────────────────┌────────────────────────╖ Statement Description ────────────────────────────────────────────────────────────────────────── LINE -(50,50) Draws from (10,10) to (50,50) LINE -STEP(50,50) Draws from (10,10) to (60,60); that is, to 10 plus offset 50 LINE (25,25)-STEP(50,50) Draws from (25,25) to (75,75); that is, to 25 plus offset 50 Statement Description ────────────────────────────────────────────────────────────────────────── LINE STEP(25,25)-STEP(50,50) Draws from (35,35) to (85,85); that is, from 10 plus offset 25 to that point plus offset 50 LINE STEP(25,25)-(50,50) Draws from (35,35) to (50,50); that is, from 10 plus offset 25 to absolute 50 ────────────────────────────────────────────────────────────────────────── The color is the number of the color in which the line is drawn. (If the B or BF options are used, the box is drawn in this color.) See the SCREEN statement for information on valid colors. The B option draws a box with the points (x1,y1) and (x2,y2) specifying diagonally opposite corners. The BF option draws a filled box. This option is similar to the B option; BF also paints the interior of the box with the selected color. The style is a 16-bit integer mask used to put pixels on the screen. Using the style argument is called "line styling." With line styling, LINE reads the bits in style from left to right. If a bit is 0, then no point is plotted; if the bit is 1, a point is plotted. After plotting a point, LINE selects the next bit position in style. Because a 0 bit in style does not change the point on the screen, you may want to draw a background line before using styling so you can have a known background. Style is used for normal lines and boxes, but has no effect on filled boxes. When coordinates specify a point that is not in the current viewport, the line segment is clipped to the viewport. See Chapter 5, "Graphics," in Programming in BASIC for more information on the LINE statement. ■ See Also SCREEN ■ Examples The following examples are different LINE statements that assume a screen 320 pixels wide by 200 pixels high: SCREEN 1 'Sets up the screen mode. LINE -(X2,Y2) 'Draws a line (in the 'foreground color) from 'the most recent point 'to X2,Y2. LINE(0,0)-(319,199) 'Draws a diagonal line across 'the screen (downward). LINE(0,100)-(319,100) 'Draws a horizontal line 'across the screen. LINE(10,10)-(20,20),2 'Draws a line in color 2. FOR X=0 to 319 'Draws an alternating pattern LINE(X,0)-(X,199),X AND 1 '(line on/line off) on mono- NEXT 'chrome display. LINE (0,0)-(100,100),,B 'Draws a box in the fore- 'ground color (note that the 'color is not included). LINE STEP(0,0)-STEP(200,200),2,BF 'Draws a filled box in color '2 (coordinates are given as 'offsets with the STEP option). LINE(0,0)-(160,100),3,,&HFF00 'Draws a dashed line from 'the upper lefthand corner to 'the center of the screen in 'color 3. ──────────────────────────────────────────────────────────────────────────── LINE INPUT Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Inputs an entire line (up to 255 characters) to a string variable, without the use of delimiters ■ Syntax LINE INPUT«;» «"promptstring";» stringvariable ■ Remarks The promptstring is a string constant displayed on the screen before input is accepted. A question mark is not printed unless it is part of the promptstring. All input from the end of promptstring to the carriage return is assigned to stringvariable. A semicolon immediately after the LINE INPUT statement keeps the cursor on the same line after the user presses ENTER. LINE INPUT uses the same editing characters as INPUT. ■ See Also INPUT ■ Example The following program enables the user to enter text in a notes file. The LINE INPUT statement allows you to enter any characters, including those (such as a comma) that are delimiters in a regular INPUT statement. 'Opens and writes lines to a notes file until you 'enter a blank line. DO CLS PRINT "Enter text. To stop, press <RETURN> without "; PRINT "entering any new text." : PRINT OPEN "NOTES.TXT" FOR OUTPUT AS #1 ' Take lines until a blank line is entered. DO LINE INPUT "->";Inline$ IF Inline$ <> "" THEN PRINT #1, Inline$ LOOP WHILE Inline$ <> "" CLS : CLOSE #1 ' Echo the notes back and see if they are correct. OPEN "NOTES.TXT" FOR INPUT AS #1 PRINT "You entered: " : PRINT DO WHILE NOT EOF(1) LINE INPUT #1, Inline$ PRINT Inline$ LOOP CLOSE #1 PRINT : INPUT "Is this correct (Y/N)"; R$ LOOP WHILE UCASE$(R$)="N" END ──────────────────────────────────────────────────────────────────────────── LINE INPUT # Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Reads an entire line without delimiters from a sequential file to a string variable ■ Syntax LINE INPUT #filenumber,stringvariable ■ Remarks The filenumber is the number used to open the file. The stringvariable is the variable the line is assigned to. The LINE INPUT # statement reads all characters in the sequential file up to a carriage return. It then skips over the carriage-return and line-feed sequence. The next LINE INPUT # reads all characters up to the next carriage return. LINE INPUT # is especially useful if each line of a data file has been broken into fields or a text file is being read a line at a time. ■ See Also INPUT$, LINE INPUT ■ Example The following uses LINE INPUT # to echo data input to a file: OPEN "LIST" FOR OUTPUT AS #1 PRINT "CUSTOMER INFORMATION:" ' Get customer information. DO PRINT INPUT " LAST NAME: ", LName$ INPUT " FIRST NAME: ", FrName$ INPUT " AGE: ", Age$ INPUT " SEX: ", Sex$ Sex$=UCASE$(Sex$) WRITE #1, LName$, FrName$, Age$, Sex$ INPUT "Add another"; R$ LOOP WHILE UCASE$(R$)="Y" CLOSE #1 ' Echo the file back. OPEN "LIST" FOR INPUT AS #1 CLS PRINT "Records in file:" : PRINT DO WHILE NOT EOF(1) LINE INPUT #1, REC$ 'Read records from file with PRINT REC$ 'LINE INPUT #. Print the 'records on the screen. LOOP ■ Output CUSTOMER INFORMATION: LAST NAME: Saintsbury FIRST NAME: Aloysius AGE: 35 SEX: m Add another? y LAST NAME: Frangio FIRST NAME: Louisa AGE: 27 SEX: f Add another? n Records in file: "Saintsbury","Aloysius","35","M" "Frangio","Louisa","27","F" ──────────────────────────────────────────────────────────────────────────── LOC Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the current position within the file ■ Syntax LOC(filenumber) ■ Remarks The filenumber is the number used in the OPEN statement to open the file. With random-access files, the LOC function returns the number of the last record read from or written to the file. With sequential files, LOC returns the current byte position in the file, divided by 128. With binary mode files, LOC returns the position of the last byte read or written. For a COM device, LOC(filenumber) returns the number of characters in the input queue waiting to be read. The value returned depends on whether the device was opened in ASCII or binary mode. In ASCII mode, the low-level routines stop queuing characters as soon as end-of-file is received. The end-of-file itself is not queued and cannot be read. An attempt to read the end-of-file produces an error message that reads Input past end of file. In binary mode, the end-of-file character is ignored and the entire file can therefore be read. The LOC function cannot be used on the SCRN:, KYBD:, or LPTn: devices. ■ See Also OPEN COM ■ Example The following line stops the program if the current file position is beyond 50: IF LOC(1) > 50 THEN STOP ──────────────────────────────────────────────────────────────────────────── LOCATE Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Moves the cursor to the specified position ■ Syntax LOCATE«row»«,«column»«,«cursor»«,«start»«,stop»»»» ■ Remarks The following list describes the LOCATE statement's arguments: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Argument Description Argument Description ────────────────────────────────────────────────────────────────────────── row The number of a row on the screen; row is a numeric expression returning an integer. If row is not specified, then the line (row) does not change. column The number of a column on the screen; column is a numeric expression returning an integer. If column is not specified, then the column location does not change. cursor A Boolean value indicating whether the cursor is visible or not. A value of 0 (zero) indicates cursor off; a value of 1 indicates cursor on. start The starting scan line of cursor on the screen. It must be a numeric expression returning an integer. stop The ending scan line of cursor on the screen. It Argument Description ────────────────────────────────────────────────────────────────────────── stop The ending scan line of cursor on the screen. It must be a numeric expression returning an integer. ────────────────────────────────────────────────────────────────────────── You may omit any argument from the statement except that if stop is specified, start must also be specified. When you omit the row or column, LOCATE leaves the cursor at the row or column where it was moved by a previous LOCATE or a previous input or output statement, whichever occurred most recently. When you omit other arguments, QuickBASIC assumes the previous value for the argument. Note that the start and stop lines are the CRT scan lines that specify which pixels on the screen are lit. A wider range between the start and stop lines produces a taller cursor, such as one that occupies an entire character block. When start is greater than stop, LOCATE produces a two-part cursor. If the start line is given but the stop line is omitted, stop assumes the same value as start. The last line on the screen is reserved for the soft-key display and is not accessible to the cursor unless the soft-key display is off (KEY OFF) and LOCATE is used with PRINT to write on the line. ■ See Also CSRLIN, POS ■ Examples The following statements show the effects on the cursor of different LOCATE statements: LOCATE 1,1 'Moves cursor to upper-left corner of the screen. LOCATE,,1 'Makes the cursor visible; position remains 'unchanged. LOCATE,,,7 'Position and cursor visibility remain unchanged; 'sets the cursor to display at the bottom of 'the character box starting and ending on 'scan line 7. LOCATE 5,1,1,0,7 'Moves the cursor to line 5, column 1; 'turns cursor on; cursor covers entire 'character cell starting at scan line '0 and ending on scan line 7. The following example prints a menu on the screen, then waits for input in the allowable range (1-4). If a number outside that range is entered, the program continues to prompt for a selection. CONST FALSE=0, TRUE=NOT FALSE DO CLS PRINT "MAIN MENU" : PRINT PRINT "1) Add Records" PRINT "2) Display/Update/Delete a Record" PRINT "3) Print Out List of People Staying at Hotel" PRINT "4) End Program" ' Change cursor to a block. LOCATE ,,1,1,12 LOCATE 12,1 PRINT "What is your selection?"; DO CH$ = INPUT$(1) LOOP WHILE (CH$ < "1" OR CH$ > "4") PRINT CH$ ' Call the appropriate subprogram. SELECT CASE VAL(CH$) CASE 1 CALL Add CASE 2 CALL Search CASE 3 CALL Hotel CASE 4 CALL Quit END SELECT LOOP WHILE NOT ENDPROG . . . END ──────────────────────────────────────────────────────────────────────────── LOCK...UNLOCK Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Controls access by other processes to all or part of an opened file ■ Syntax LOCK «#» filenumber «,{record | «start» TO end}» . . . UNLOCK «#» filenumber «,{record | «start» TO end}» ■ Remarks These statements are used in networked environments where several processes might need access to the same file. The LOCK and UNLOCK statements take the following arguments: Argument Description ────────────────────────────────────────────────────────────────────────── filenumber The number with which the file was opened. record The number of the record or byte to be locked; record can be any number from 1 to 2,147,483,647 (equivalent to 2^31-1). A record may be up to 32,767 bytes in length. start The number of the first record or byte to be locked. end The number of the last record or byte to be locked. ────────────────────────────────────────────────────────────────────────── For binary-mode files, the arguments record, start, and end represent the number of a byte relative to the beginning of the file. The first byte in a file is byte 1. For random-access files, the arguments record, start, and end are the number of a record relative to the beginning of the file. The first record is record 1. The LOCK and UNLOCK statements are always used in pairs. The arguments to LOCK and UNLOCK must match exactly when you use them. See the second example below. If you specify just one record, then only that record is locked or unlocked. If you specify a range of records and omit a starting record (start), then all records from the first record to the end of the range (end) are locked or unlocked. LOCK with no record arguments locks the entire file, while UNLOCK with no record arguments unlocks the entire file. If the file has been opened for sequential input or output, LOCK and UNLOCK affect the entire file, regardless of the range specified by start and end. LOCK and UNLOCK only function at run time if you are using versions of DOS that support networking (version 3.1 or later). In addition, each terminal (or the network setup programs) must run the DOS SHARE.EXE program to enable locking operations. Earlier versions of DOS return an error message that reads Advanced feature unavailable if LOCK and UNLOCK are executed. ──────────────────────────────────────────────────────────────────────────── NOTE Be sure to remove all locks with an UNLOCK statement before closing a file or terminating your program. Failing to remove locks produces unpredictable results. The arguments to LOCK and UNLOCK must match exactly. ──────────────────────────────────────────────────────────────────────────── If you attempt to access a file that is locked, the following error messages may appear: Bad record number Permission denied ■ Examples These examples assume a random-access file. The following statement locks the entire file opened as number 2: LOCK #2 The following statement locks only record 32 in file number 2: LOCK #2, 32 The following statement locks records 1-32 in file number 2: LOCK #2, TO 32 The two UNLOCK statements below unlock the records locked by the preceding LOCK statements: LOCK #1, 1 TO 4 LOCK #1, 5 TO 8 UNLOCK #1, 1 TO 4 UNLOCK #1, 5 TO 8 The following UNLOCK statement is illegal because the range in an UNLOCK statement must exactly match the range in the corresponding LOCK statements (no error is reported, but the statements produce unpredictable results): LOCK #1, 1 TO 4 LOCK #1, 5 TO 8 UNLOCK #1, 1 TO 8 The following program fragment opens a file and allows a user to lock an individual record before updating the information in that record. When the user is done, the program unlocks the locked record. (Unlocking the locked records allows other processes to use the data in the file.) TYPE AccountRec Payer AS STRING*15 Address AS STRING*20 Place AS STRING*20 Owe AS SINGLE END TYPE DIM CustRec AS AccountRec OPEN "MONITOR" SHARED AS #1 LEN = LEN(CustRec) DO CLS:LOCATE 10,10 INPUT "Customer Number? #"; Number% ' Lock the current record so another process ' doesn't change it while you're using it. LOCK #1, Number% GET #1, Number% LOCATE 11,10: PRINT "Customer: ";CustRec.Payer LOCATE 12,10: PRINT "Address: ";CustRec.Address LOCATE 13,10: PRINT "Currently owes: $";CustRec.Owe LOCATE 15,10: INPUT "Change (+ or -)", Change! CustRec.Owe=CustRec.Owe+Change! PUT #1, Number% ' Unlock the record. UNLOCK #1, Number% LOCATE 17,10: INPUT "Update another? ", Continue$ Update$ = UCASE$(LEFT$(Continue$,1)) LOOP WHILE Update$="Y" ──────────────────────────────────────────────────────────────────────────── LOF Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the length of the named file in bytes ■ Syntax LOF(filenumber) ■ Remarks The argument filenumber is the number used in the OPEN statement. When a file is opened in any mode, the LOF function returns the size of the file in bytes. LOF cannot be used with the BASIC devices SCRN:, KYBD:, CONS:, and LPTn:. When used on a device opened as a file with the statement OPEN COM, the LOF function returns the number of bytes free in the output buffer. ■ Example See the example for the GET statement. ──────────────────────────────────────────────────────────────────────────── LOG Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the natural logarithm of a numeric expression ■ Syntax LOG(n) ■ Remarks The numeric expression, n, must be greater than zero. The natural logarithm is the logarithm to the base e. The constant e is approximately equal to 2.718282. The LOG function calculates the natural logarithm with single-precision accuracy, unless the argument n is a double-precision value. In this case LOG is calculated with double-precision accuracy. You may calculate base-10 logarithms by dividing the natural logarithm of the number by the logarithm of 10. The following FUNCTION calculates base-10 logarithms: FUNCTION Log10(X) STATIC Log10=LOG(X)/LOG(10.#) END FUNCTION ■ Example The following example first prints the value of e and then prints the natural logarithms of e taken to the first, second, and third powers: PRINT EXP(1), FOR I = 1 TO 3 PRINT LOG(EXP(1)^I), NEXT ■ Output 2.718282 1 2 3 ──────────────────────────────────────────────────────────────────────────── LPOS Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the current position of the line printer's print head within the printer buffer ■ Syntax LPOS(n) ■ Remarks The argument n is the index of the printer being tested. For example, LPT1: would be tested with LPOS(1), while LPT2: would be tested with LPOS(2), and so on. The LPOS function does not necessarily give the physical position of the print head because it does not expand tab characters. In addition, some printers may buffer characters. ■ Example The following program prompts the user for team names and the names of players on each team. It then prints the players and their teams on the printer. LPRINT"Team Members"; TAB(76); "TEAM" : LPRINT INPUT "How many teams"; TEAMS INPUT "How many players per team";PPT PRINT FOR T = 1 TO TEAMS INPUT "Team name: ", TEAM$ FOR P = 1 TO PPT INPUT " Enter player name: ", PLAYER$ LPRINT PLAYER$; IF P < PPT THEN IF LPOS(0) > 55 THEN 'Print a new line if print 'head past column 55. LPRINT : LPRINT " "; ELSE LPRINT ", "; 'Otherwise, print a comma. END IF END IF NEXT P LPRINT STRING$(80-LPOS(0)-LEN(TEAM$),"."); TEAM$ NEXT T ──────────────────────────────────────────────────────────────────────────── LPRINT, LPRINT USING Statements ──────────────────────────────────────────────────────────────────────────── ■ Action Prints data on the printer LPT1: ■ Syntax 1 LPRINT «expressionlist» «{;|,}» ■ Syntax 2 LPRINT USING formatstring; expressionlist «{;|,}» ■ Remarks These statements function in the same way as the PRINT and PRINT USING statements except that output goes to the line printer and the filenumber option is not permitted. The LPRINT statement assumes an 80-character-wide printer. This width can be changed with a WIDTH LPRINT statement. ──────────────────────────────────────────────────────────────────────────── WARNING Since the LPRINT statement uses the LPT1 printer device, you should not use LPRINT in a program that also contains an OPEN LPT1 statement. Using these two statements together produces unpredictable results. ──────────────────────────────────────────────────────────────────────────── ■ Differences From Basica An LPRINT CHR$(13) statement actually outputs both CHR$(13) and CHR$(10). This feature was created to provide compatibility with BASICA. ■ See Also PRINT, PRINT USING, WIDTH ■ Example See examples for PRINT, PRINT USING. ──────────────────────────────────────────────────────────────────────────── LSET Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Moves data from memory to a random-access file buffer (in preparation for a PUT statement), copies one record variable to another, or left-justifies the value of a string in a string variable ■ Syntax LSET {stringvariable=stringexpression | stringexpression1= stringexpression2} ■ Remarks The stringvariable is usually a random-access file field defined in a FIELD statement, although it can be any string variable. The stringexpression is the value assigned to the variable. If stringexpression requires fewer bytes than were defined for stringvariable in the FIELD statement, the LSET function left-justifies the string in the field (RSET will right-justify the string). Spaces are used to pad the extra positions. If the string is too long for the field, both LSET and RSET truncate characters from the right. Numeric values must be converted to strings before they are justified with the LSET or RSET statements. ──────────────────────────────────────────────────────────────────────────── NOTE You may also use LSET or RSET with a string variable not defined in a FIELD statement to left-justify or right-justify a string in a given field. For example, the program lines A$=SPACE$(20) RSET A$=N$ will right-justify the string N$ in a 20-character field. This can be useful for formatting printed output. ──────────────────────────────────────────────────────────────────────────── You can use LSET to assign one record variable to another. The following example copies the contents of RecTwo to RecOne: TYPE TwoString StrFld AS STRING * 2 END TYPE TYPE ThreeString StrFld AS STRING * 3 END TYPE DIM RecOne AS TwoString, RecTwo AS ThreeString . . . LSET RecOne = RecTwo Notice that LSET is used to assign record variables of differing types. Record variables of the same type can be assigned using LET. Also, because RecOne is only two bytes long, only two bytes are copied from RecTwo. LSET copies only the number of bytes in the shorter of the two record variables. ■ See Also LET; MKD$, MKI$, MKL$, MKS$; PUT (File I/O); RSET ■ Example The first line of the following example converts the single-precision numeric variable AMT to a 4-byte string and stores that string in A$, left-justified. The second line converts the integer numeric variable COUNT% to a 2-byte string and stores that string in D$, right-justified. LSET A$ = MKS$(AMT) RSET D$ = MKI$(COUNT%) ──────────────────────────────────────────────────────────────────────────── LTRIM$ Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns a copy of a string with leading spaces removed ■ Syntax LTRIM$(stringexpression) ■ Remarks The stringexpression can be any string expression. ■ See Also RTRIM$ ■ Example This program copies a file to a new file, removing all leading and trailing spaces: CLS ' Get the file names. INPUT "Enter input file name:",InFile$ INPUT "Enter output file name:",OutFile$ OPEN InFile$ FOR INPUT AS #1 OPEN OutFile$ FOR OUTPUT AS #2 ' Read, trim, and write each line. DO WHILE NOT EOF(1) LINE INPUT #1,LineIn$ ' Remove leading and trailing blanks. LineIn$=LTRIM$(RTRIM$(LineIn$)) PRINT #2, LineIn$ LOOP CLOSE #1,#2 END ──────────────────────────────────────────────────────────────────────────── MID$ Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns a substring of a string ■ Syntax MID$(stringexpression,start«,length») ■ Remarks The MID$ function takes the following arguments: Argument Description ────────────────────────────────────────────────────────────────────────── stringexpression The string expression that the substring is extracted from. This can be any string expression. start The character position in stringexpression where the substring starts. length The number of characters to extract. ────────────────────────────────────────────────────────────────────────── The arguments start and length must be in the range 1 to 32,767. If length is omitted or if there are fewer than length characters to the right of the start character, the MID$ function returns all characters to the right of the start character. If start is greater than the number of characters in stringexpression, MID$ returns a null string. Use the LEN function to find the number of characters in stringexpression. ■ See Also LEFT$, LEN, MID$ Statement, RIGHT$ ■ Example The following program converts a binary number to a decimal number. Digits are extracted from the binary number (input as a string) using MID$. INPUT "Binary number = ",Binary$ 'Input binary number as 'string. Length = LEN(Binary$) 'Get length of string. Decimal = 0 FOR K = 1 TO Length 'Get individual digits from string, from left to right. Digit$ = MID$(Binary$,K,1) 'Test for valid binary digit. IF Digit$="0" OR Digit$="1" THEN 'Convert digit characters to numbers. Decimal = 2*Decimal + VAL(Digit$) ELSE PRINT "Error--invalid binary digit: ";Digit$ EXIT FOR END IF NEXT PRINT "Decimal number =" Decimal ■ Output Binary number = 10110 Decimal number = 22 ──────────────────────────────────────────────────────────────────────────── MID$ Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Replaces a portion of a string variable with another string ■ Syntax MID$(stringvariable,start«,length»)=stringexpression ■ Remarks The MID$ statement has the following arguments: Argument Description ────────────────────────────────────────────────────────────────────────── stringvariable The string variable being modified. start A numeric expression giving the position in stringvariable where the replacement starts. length The length of the string being replaced. The length is a numeric expression. stringexpression The string expression that replaces part of the stringvariable. ────────────────────────────────────────────────────────────────────────── The arguments start and length are integer expressions. The argument stringvariable is a string variable, but stringexpression can be a string variable, a string constant, or a string expression. The optional length refers to the number of characters from the argument stringexpression that are used in the replacement. If length is omitted, all of stringexpression is used. However, regardless of whether length is omitted or included, the replacement of characters never goes beyond the original length of stringvariable. ■ See Also MID$ Function ■ Example The following example uses the MID$ statement to get characters from a string: Test$ = "Paris, France" PRINT Test$ MID$(Test$,8)="Texas " PRINT Test$ ■ Output Paris, France Paris, Texas ──────────────────────────────────────────────────────────────────────────── MKDIR Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Creates a new directory ■ Syntax MKDIR pathname ■ Remarks The pathname is a string expression specifying the name of the directory to be created. The pathname must be a string of less than 128 characters. The MKDIR statement works like the DOS command MKDIR; the syntax in BASIC cannot, however, be shortened to MD, as in DOS. ■ See Also CHDIR, RMDIR ■ Example The following fragment creates a new directory (if the directory does not exist) and copies files into that directory: ON ERROR GOTO Errorhandler PRINT "This program creates a new directory named MONTHS" PRINT "in this directory, then creates files in that directory" MKDIR "MONTHS" DO INPUT "Filename"; File$ IF File$ = "" THEN END OPEN "MONTHS\" + File$ FOR OUTPUT AS #1 . . . CLOSE #1 LOOP Errorhandler: 'Error 75 means MONTHS directory already exists IF ERR = 75 THEN RESUME NEXT ON ERROR GOTO 0 ──────────────────────────────────────────────────────────────────────────── MKSMBF$, MKDMBF$ Functions ──────────────────────────────────────────────────────────────────────────── ■ Action Converts an IEEE-format number to a string containing a Microsoft Binary format number. ■ Syntax MKSMBF$(single-precision-expression) MKDMBF$(double-precision-expression) ■ Remarks These functions are used to write real numbers to random-access files using Microsoft Binary format. They are particularly useful for maintaining data files created with older versions of BASIC. The MKSMBF$ and MKDMBF$ functions convert real numbers in IEEE-format to strings so they can be written to the random-access file. To write a real number to a random-access file in Microsoft Binary format, convert the number to a string using MKSMBF$ (for a single-precision number) or MKDMBF$ (for a double-precision number). Then store the result in the corresponding field (defined in the FIELD statement) and write the record to the file using the PUT statement. ■ Example The following example uses MKSMBF$ to store real values in a file as Microsoft Binary format numbers: ' Read a name and a test score from the console. ' Store as a record in a random-access file. ' Scores are written out as ' Microsoft Binary format single-precision values. TYPE Buffer NameField AS STRING * 20 ScoreField AS STRING * 4 END TYPE DIM RecBuffer AS Buffer OPEN "TESTDAT.DAT" FOR RANDOM AS #1 LEN=LEN(RecBuffer) PRINT "Enter names and scores, one name and score per line." PRINT "Enter END, 0 to end input." INPUT NameIn$, Score I=0 ' Read pairs of names and scores from the console ' until the name is END. DO WHILE UCASE$(NameIn$) <> "END" I=I+1 RecBuffer.NameField=NameIn$ ' Convert the score to a string. RecBuffer.ScoreField=MKSMBF$(Score) PUT #1,I,RecBuffer INPUT NameIn$, Score LOOP PRINT I;" records written." CLOSE #1 ──────────────────────────────────────────────────────────────────────────── MKD$, MKI$, MKL$, MKS$ Functions ──────────────────────────────────────────────────────────────────────────── ■ Action Converts numeric values to string values ■ Syntax MKI$(integerexpression) MKS$(single-precision-expression) MKL$(long-integer-expression) MKD$(double-precision-expression) ■ Remarks The MKI$, MKS$, MKL$, and MKD$ functions are used with FIELD and PUT statements to write real numbers to a random-access file. The functions take numeric expressions and convert them to strings that can be stored in the strings defined in the FIELD statement. The functions are the inverse of CVI, CVS, CVL, and CVD. Function Description ────────────────────────────────────────────────────────────────────────── MKI$ Converts an integer to a two-byte string MKS$ Converts a single-precision value to a four-byte string MKL$ Converts a long-integer value to a four-byte string MKD$ Converts a double-precision value to an eight-byte string ────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── NOTE BASIC record variables provide a more efficient and convenient way of reading and writing random-access files. See Chapter 3, "File and Device I/O," in Programming in BASIC for a discussion of the new method. ──────────────────────────────────────────────────────────────────────────── ■ See Also CVI, CVS, CVL, CVD; FIELD; PUT ■ Example See the example for the CVI, CVS, CVL, CVD statements. ──────────────────────────────────────────────────────────────────────────── NAME Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Changes the name of a disk file or directory ■ Syntax NAME oldfilename AS newfilename ■ Remarks The NAME statement is similar to the DOS RENAME command. NAME can move a file from one directory to another but cannot move a directory. The arguments oldfilename and newfilename are string expressions each of which contains a file or directory name and an optional path. If the path in newfilename is different from the path in oldfilename, the NAME statement changes the pathname as well as renames the file as indicated. A file named oldfilename must exist and the newfilename must not be in use. Both files must be on the same drive. Using NAME with different drive designations in the old and new file names produces an error message that reads Rename across disks. After a NAME statement, the file or directory exists on the same disk, in the same disk space, but with the new name. Using NAME on an open file causes a run-time error message reading File already open. You must close an open file before renaming it. ■ Examples The following statements show NAME used with and without a path specification: 'Changes the name of file ACCTS to LEDGER. NAME "ACCTS" AS "LEDGER" 'Moves file CLIENTS from directory X to directory \XYZ\P. NAME "\X\CLIENTS" AS "\XYZ\P\CLIENTS" ──────────────────────────────────────────────────────────────────────────── OCT$ Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns a string representing the octal value of the numeric argument ■ Syntax OCT$(numeric-expression) ■ Remarks The numeric-expression may be of any type. The numeric-expression is rounded to an integer or long integer before the OCT$ function evaluates it. ■ See Also HEX$ ■ Example The following line prints the octal representation of 24: PRINT OCT$(24) ■ Output 30 ──────────────────────────────────────────────────────────────────────────── ON event Statements ──────────────────────────────────────────────────────────────────────────── ■ Action Indicates the first line of an event-trapping subroutine ■ Syntax ON event GOSUB {linenumber | linelabel } ■ Remarks The ON event statement lets you specify a subroutine that is executed whenever an event occurs on a specified device. The following list describes the parts of the statement: Argument Description ────────────────────────────────────────────────────────────────────────── event Specifies the event that causes a branch to the event-trapping subroutine. An event is a condition on a specific device. See below for more information about specific devices. linenumber linelabel The number or label of the first line in the event-trapping subroutine. This line must be in the module-level code. ────────────────────────────────────────────────────────────────────────── A linenumber of 0 disables event trapping and does not specify line 0 as the start of the subroutine. The following list describes the events that can be trapped: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Event Description ────────────────────────────────────────────────────────────────────────── COM(n) Branches to the subroutine when characters are received at a communications port. The integer expression n indicates one of the serial ports, either 1 or 2. KEY(n) Branches to the subroutine when a specified key is pressed. The integer expression n is the number of a function key, direction key, or user-defined key. See Appendix A, "Keyboard Scan Codes and ASCII Character Codes," and the KEY statement for more information about these values. PEN Branches to the subroutine when a lightpen is activated. Event Description ────────────────────────────────────────────────────────────────────────── activated. PLAY(queuelimit) Branches when the number of notes in the music buffer goes from queuelimit to queuelimit-1. The value of queuelimit is an integer expression from 1 to 32. A PLAY event-trapping subroutine can be used with a PLAY statement to play music in the background while a program is running. STRIG(n) Branches to the event-trapping subroutine when a joystick trigger is pressed. The integer expression n is the joystick trigger number: 0 for the lower button and 4 for the upper button on the first joystick; 2 for the lower button and 6 for the upper button on the second joystick. TIMER(n) Branches to the subroutine when n seconds have Event Description ────────────────────────────────────────────────────────────────────────── TIMER(n) Branches to the subroutine when n seconds have passed. The integer expression n is in the range 1 to 86,400 (1 second to 24 hours). ────────────────────────────────────────────────────────────────────────── The ON event statement only specifies the start of an event-trapping subroutine. Another set of statements determines whether or not the subroutine is called. This set of statements turns event trapping on or off and determines how events are handled when trapping is off. The following list describes these statements in a general way. See the entries for particular statements for more specific information. Event Description ────────────────────────────────────────────────────────────────────────── event ON Enables event trapping. Event trapping occurs only after an event ON statement is executed. event OFF Disables event trapping. No trapping takes place until the execution of another event ON statement. Events occurring while trapping is off are ignored. event STOP Inhibits event trapping so no trapping takes place until an event ON statement is executed. Events occurring while trapping is inhibited are remembered and processed when an event ON statement is executed. ────────────────────────────────────────────────────────────────────────── When an event trap occurs (the subroutine is called), BASIC performs an automatic event STOP that prevents recursive traps. The RETURN from the trapping subroutine automatically performs an event ON statement unless an explicit event OFF is performed inside the subroutine. ──────────────────────────────────────────────────────────────────────────── NOTE Because of the implicit event STOP and event ON statements, the events during execution of the trapping subroutine are remembered and processed when the trapping subroutine ends. ──────────────────────────────────────────────────────────────────────────── The RETURN linenumber or RETURN linelabel forms of RETURN can be used to return to a specific line number from the trapping subroutine. Use this type of return with care, however, because any other GOSUB, WHILE, or FOR statements active at the time of the trap remain active. This may produce error messages such as NEXT without FOR. In addition, if an event occurs in a procedure, a RETURN linenumber or RETURN linelabel statement cannot get back into the procedure──the line number or label must be in the module-level code. The next three sections contain additional information about the ON COM, ON KEY, and ON PLAY statements. USING ON COM If your program receives data using an asynchronous communications adapter, the BASIC command-line option /C can be used to set the size of the data buffer. USING ON KEY Keys are processed in the following order: 1. The line printer's echo-toggle key is processed first. Making this key a user-defined key trap does not prevent characters from being echoed to the line printer when pressed. 2. Function keys and the cursor-direction keys are examined next. Defining a FUNCTION key or DIRECTION key as a user-defined key trap has no effect because these keys are predefined. 3. Finally, the user-defined keys are examined. The ON KEY statement can trap any key, including BREAK or system reset. This makes it possible to prevent accidentally breaking out of a program or rebooting the machine. ──────────────────────────────────────────────────────────────────────────── NOTE When a key is trapped, the key event is destroyed. You cannot subsequently use INPUT or INKEY$ statements to find out which key caused the trap. Because there is no way to know which key press caused the branch to the trap, you must set up a subroutine for each key if you want to assign different functions to particular keys. ──────────────────────────────────────────────────────────────────────────── USING ON PLAY The following three rules apply to the use of ON PLAY: 1. A play event trap occurs only when music is playing in the background. Play event traps do not occur when music is running in the foreground. 2. A play event trap does not occur if the background music queue has already gone from having queuelimit to queuelimit-1 notes when a PLAY ON is executed. 3. If queuelimit is a large number, event traps may occur often enough to slow down the program. ■ Differences From Basica If you use BC from the DOS prompt, you must use /V or /W if a program contains ON event statements to allow the compiler to function correctly when event-trapping subroutines are included in a program. BASICA does not require additional options. ■ See Also COM, KEY (n), PEN ON, PLAY ON, RETURN, STRIG ON, TIMER ON ■ Examples The following example plays continuous music by calling an event-handling subroutine whenever the music buffer goes from three to two notes: ' Call subroutine Background when the music buffer goes from ' 3 to 2 notes. ON PLAY(3) GOSUB Background ' Turn on event trapping for PLAY. PLAY ON ' Define a string containing the melody. Lizzie$="o3 L8 E D+ E D+ E o2 B o3 D C L2 o2 A" ' Play the melody for the first time. PLAY "MB X" + VARPTR$(Lizzie$) ' Continue until a key is pressed. LOCATE 2,1 : PRINT "Press any key to stop."; DO WHILE INKEY$="" LOOP END ' PLAY event-handling subroutine. Background: ' Increment and print a counter each time. Count% = Count% + 1 LOCATE 1,1 : PRINT "Background called ";Count%;"time(s)"; ' Execute another PLAY to fill the buffer. PLAY "MB X" + VARPTR$(Lizzie$) RETURN The following example draws a polygon every three seconds with a random shape (three to seven sides), size, and location: SCREEN 1 DEFINT A-Z DIM X(6), Y(6) TIMER ON 'Enable timer event trapping. ON TIMER(3) GOSUB Drawpoly 'Draw a new polygon every 'three seconds. PRINT "Press any key to end program" INPUT "Press <RETURN> to start",Test$ DO LOOP WHILE INKEY$="" 'End program if any key pressed. END Drawpoly: CLS 'Erase old polygon. N = INT(5*RND + 2) 'N is random number from 2 to 6. FOR I = 0 TO N X(I) = INT(RND*319) 'Get coordinates of vertices of Y(I) = INT(RND*199) 'polygon. NEXT PSET (X(N),Y(N)) FOR I = 0 TO N LINE -(X(I),Y(I)),2 'Draw new polygon. NEXT RETURN ──────────────────────────────────────────────────────────────────────────── ON ERROR Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Enables error handling and specifies the first line of the error-handling routine ■ Syntax ON ERROR GOTO line ■ Remarks The line argument is the line number or line label of the first line in the error-handling routine. This line must appear in module-level code. If line cannot be found in the module where the error occurred, or if there is no ON ERROR GOTO statement, a backward search is made through the modules that invoked the module with the error. If an active error handler is found, it is used. If no active error handler is found, an error message is printed and program execution halts. The specific error message depends on the type of error. Only modules in the invocation path are searched. Modules outside the path are not searched, even if there is no active error handler in the search path. A line number of 0 disables error handling. It does not specify line 0 as the start of the error-handling code, even if the program contains a line numbered 0. Subsequent errors print an error message and halt the program. Once error handling is enabled, any error that can be trapped causes a jump to the specified error-handling routine. Inside an error handler, executing an ON ERROR statement with a line number of 0 halts program execution and prints the error message for the error that caused the trap. This is a convenient way to halt a program in response to errors that cannot be processed by the error-handling routine. Note that an error-handling routine is not a SUB or FUNCTION procedure or a DEF FN function. An error-handling routine is a module-level block of code marked by a line label or line number. ──────────────────────────────────────────────────────────────────────────── NOTE Errors occurring within an error-handling routine are not trapped. These errors halt program execution after printing an error message. ──────────────────────────────────────────────────────────────────────────── ■ Differences From Basica Compiling from the BC command line requires additional options when you use ON ERROR GOTO. BASICA does not require any additional options. If a program contains ON ERROR GOTO or RESUME linenumber statements, you must use the On Error /E compile option when compiling from the BC command line. If a program contains the statements RESUME, RESUME NEXT, or RESUME 0, you must also use the Resume Next /X compile option when compiling from the command line. No compile options are required when compiling within the QuickBASIC environment. ■ See Also ERR, ERL; ERROR; RESUME ■ Example The following program gets a file name from the user and displays the file on the screen. If the file cannot be opened, an error-handling routine traps the error and starts the program again at the prompt for the file name. DEFINT A-Z ' Establish the error-handling routine. ON ERROR GOTO ErrorHandler CLS ' Get a file name. INPUT "Enter the file to display: ",filename$ ' Open the file. OPEN filename$ FOR INPUT AS #1 ' Display the file on the screen. DO WHILE NOT EOF(1) LINE INPUT #1, aline$ PRINT aline$ LOOP END ' Error handling routine handles only "Bad file name," ' aborts on any other error. CONST BADFILENAME=64 ErrorHandler: IF ERR=BADFILENAME THEN ' Get another file name. PRINT "File "; UCASE$(filename$); " not found." INPUT "Enter the file to display: ",filename$ RESUME ELSE ' Some other error, so print message and abort. PRINT "Unrecoverable error--";ERR ON ERROR GOTO 0 END IF ──────────────────────────────────────────────────────────────────────────── ON...GOSUB, ON...GOTO Statements ──────────────────────────────────────────────────────────────────────────── ■ Action Branches to one of several specified lines, depending on the value of an expression ■ Syntax 1 ON expression GOSUB {line-number-list | line-label-list } ■ Syntax 2 ON expression GOTO {line-number-list | line-label-list } ■ Remarks The expression argument can be any numeric expression (expression is rounded to an integer before the ON...GOSUB or ON...GOTO is evaluated). The line-number-list or line-label-list consists of a list of line numbers or line labels, separated by commas. The value of expression determines which line the program branches to. For example, if the value is 3, the third line specified in the list is the destination of the branch. The value of expression should be greater than or equal to 1 and less than or equal to the number of items in the list. If the value falls outside this range, one of the following results occurs: Value Result ────────────────────────────────────────────────────────────────────────── Number equal to 0 or greater than number of Control drops to the next items in list BASIC statement. Negative number or a number greater than 255 An error message appears that reads Illegal function call. ────────────────────────────────────────────────────────────────────────── You may mix line numbers and labels in the same list. ──────────────────────────────────────────────────────────────────────────── NOTE The ON...GOTO statement accepts a maximum of 60 line labels or line numbers. The SELECT CASE statement provides a more powerful, convenient, and flexible way to do multiple branches. ──────────────────────────────────────────────────────────────────────────── ■ See Also GOSUB, RETURN, SELECT CASE ■ Example The following program fragment causes program control to branch to one of the four subroutines listed, depending on the value of Chval: DO CLS PRINT "1) Display attendance at workshops." PRINT "2) Calculate total registration fees paid." PRINT "3) Print mailing list." PRINT "4) End program." PRINT : PRINT "What is your choice?" DO Ch$=INKEY$ LOOP WHILE Ch$="" Chval = VAL(Ch$) IF Chval > 0 AND Chval < 5 THEN ON Chval GOSUB Shop, Fees, Mailer, Progend END IF LOOP END . . . ──────────────────────────────────────────────────────────────────────────── ON UEVENT GOSUB Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Defines the event-handler for a user-defined event ■ Syntax ON UEVENT GOSUB { linenumber | linelabel } ■ Remarks The linenumber or linelabel argument is the number or label of the first line in the event-handling routine. ON UEVENT GOSUB lets your program branch to an event-handling routine when a user-defined event occurs. The event is usually a hardware interrupt. This gives user-defined events one of the features enjoyed by the COM, KEY, and other events in BASIC. Once these events have been defined with an ON event statement, they act like interrupts. The program does not need to poll for the event. Likewise, once ON UEVENT GOSUB and UEVENT ON have been executed, the user-defined event automatically triggers execution of the BASIC routine to handle it. The program does not have to poll. At least two (and sometimes three) pieces of code are needed to set up a user-defined event. The first is the interrupt service routine. The second is an initialization routine to insert the address of the service routine into the interrupt vector table. The third is the routine your BASIC program calls to retrieve the data (if any) collected by the interrupt service routine. If the initialization routine "steals" an interrupt used by another service routine, the original address must be restored before your program terminates. These routines are usually written in assembly language. However, any language whose compiler can generate interrupt service routines and whose object code can be linked with BASIC may be used. There are four steps in creating a user-defined event: 1. Write an event-handling routine and add it to your BASIC program. 2. Execute the ON UEVENT GOSUB statement to specify the user-event handling routine. 3. Execute the UEVENT ON statement to enable user-event trapping. 4. Call the interrupt-initialization routine to insert the address of the interrupt service routine into the interrupt vector table. You're now ready for the interrupt when it occurs. The interrupt transfers execution to the interrupt service routine. The service routine collects and stores the data the user wants. It then calls SetUEvent. SetUEvent sets a flag checked by QuickBASIC before going to the next BASIC statement (or label if executing compiled code using /W instead of /V). When the flag is set, control transfers to the event-handling routine designated in ON UEVENT GOSUB. The SetUEvent procedure is a part of BASIC, and is automatically included in compiled applications or when running QuickBASIC with the /L command-line option. Your interrupt service routine must call SetUEvent; it is the only way to alert your program that the event has occurred. You can call SetUEvent from any language, not just from assembly language. SetUEvent is not a function; it cannot return a value to BASIC. If you wish to return a value, you must write a function for your BASIC program to call. (It would usually be called by your event-handling routine.) This function must be described in a DECLARE statement so your BASIC program can find and use it. Although ON UEVENT GOSUB ties an event-handling routine to a user-defined event, it does not enable the event trap. The UEVENT statement is used to enable, disable, and suspend user-defined event trapping. ■ See Also UEVENT ■ Example The following example illustrates the use of ON UEVENT GOSUB: DECLARE SUB test (a) ON UEVENT GOSUB Event1 UEVENT ON INPUT "Enter a number";a CALL test(a) END Event1: PRINT "Got to the event handler" RETURN SUB test(a) IF a=5 THEN CALL SetUEvent END SUB ──────────────────────────────────────────────────────────────────────────── OPEN Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Enables I/O to a file or device ■ Syntax 1 OPEN file «FOR mode1» «ACCESS access» «lock» AS «#» filenum «LEN=reclen» ■ Syntax 2 OPEN mode2,«#»filenum, file «,reclen» ■ Remarks The file is a string expression that specifies an optional device, followed by a file name or path name conforming to the DOS file-naming conventions. You must open a file before any I/O operation can be performed on it. OPEN allocates a buffer for I/O to the file or device and determines the mode of access used with the buffer. SYNTAX 1 In the first syntax, mode1 is one of the following: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Mode Description ────────────────────────────────────────────────────────────────────────── OUTPUT Specifies sequential output mode. Mode Description ────────────────────────────────────────────────────────────────────────── INPUT Specifies sequential input mode. APPEND Specifies sequential output mode and sets the file pointer to the end of file and the record number to the last record of the file. A PRINT # or WRITE # statement then extends (appends to) the file. RANDOM Specifies random-access file mode, the default mode. In RANDOM mode, if no ACCESS clause is present, three attempts are made to open the file when the OPEN statement is executed. Access is attempted in the following order: 1. Read/write 2. Write-only Mode Description ────────────────────────────────────────────────────────────────────────── 3. Read-only BINARY Specifies binary file mode. In binary mode, you may read or write information to any byte position in the file using GET and PUT. In binary mode, if no ACCESS clause is present, three attempts are made to open the file. The attempts follow the same order as those for RANDOM files. ────────────────────────────────────────────────────────────────────────── If mode1 is omitted, the default random-access mode is assumed. The access expression specifies the operation performed on the opened file. If the file is already opened by another process and the specified type of access is not allowed, the OPEN fails and an error message is generated that reads Permission denied. The ACCESS clause works in an OPEN statement only if you are using a version of DOS that supports networking (DOS Versions 3.0 or later). In addition, you must run the SHARE.EXE program (or the network startup program must run it) to perform any locking operation. If ACCESS is used with OPEN, earlier versions of DOS return an error message that reads Advanced feature unavailable. The access argument can be one of the following: Access Type Description ────────────────────────────────────────────────────────────────────────── READ Opens the file for reading only. WRITE Opens the file for writing only. READ WRITE Opens the file for both reading and writing. This mode is valid only for RANDOM and BINARY files and files opened for APPEND. ────────────────────────────────────────────────────────────────────────── The lock clause works in a multiprocessing environment to restrict access by other processes to an open file. The lock types are as follows: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Lock Type Description ────────────────────────────────────────────────────────────────────────── Default If locktype is not specified, the file may be opened for reading and writing any number of times by this process, but other processes are denied access to the file while it is opened. SHARED Any process on any machine may read from or write to this file. Do not confuse the SHARED lock type with the SHARED statement or the SHARED attribute appearing in other statements. LOCK READ No other process is granted read access to this file. This access is granted only if no other process has a previous READ access to the file. LOCK WRITE No other process is granted write access to this file. This lock is granted only if no other process has a previous WRITE access to the file. Lock Type Description ────────────────────────────────────────────────────────────────────────── process has a previous WRITE access to the file. LOCK READ WRITE No other process is granted either read or write access to this file. This access is granted only if READ or WRITE access has not already been granted to another process, or if a LOCK READ or LOCK WRITE is not already in place. ────────────────────────────────────────────────────────────────────────── When the OPEN is restricted by a previous process, it generates error 70, Permission denied, under DOS. The filenum (file number) argument is an integer expression whose value is between 1 and 255. When an OPEN is executed, the file number is associated with the file as long as it is open. Other I/O statements may use the number to refer to the file. The reclen (record length) argument is an integer expression that, if included, sets the record length (number of characters in one record) for random-access files. For sequential files, the default length for records is 512 bytes; for random-access files, the default is 128 bytes. The value of reclen cannot exceed 32,767 bytes. If the file mode is binary, then the LEN clause is ignored. For sequential files, reclen need not correspond to an individual record size, since a sequential file may have records of different sizes. When used to open a sequential file, reclen specifies the number of characters to be loaded into the buffer before the buffer is written to, or read from, the disk. A larger buffer means more room taken from BASIC, but faster file I/O. A smaller buffer means more room in memory for BASIC, but slower I/O. The default buffer size is 512 bytes. SYNTAX 2 In the second form of the OPEN syntax, mode2 is a string expression the first character of which must be one of the following: Mode Description ────────────────────────────────────────────────────────────────────────── O Specifies sequential output mode. I Specifies sequential input mode. R Specifies random-access file input/output mode. B Specifies binary file mode. A Specifies sequential output mode and sets the file pointer to the end of the file and the record number to the last record of the file. A PRINT # or WRITE # statement extends (appends to) the file. ────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── NOTE The second form of the OPEN syntax does not support any of the access and file-sharing options found in the first syntax and is supported for compatibility with programs written in earlier versions of BASIC. ──────────────────────────────────────────────────────────────────────────── The following devices are supported by BASIC and can be named and opened with the file argument: KYBD:, SCRN:, COMn:, LPTn:, CONS:. The BASIC file I/O system allows you to take advantage of user-installed devices. (See your DOS manual for information on character devices.) Character devices are opened and used in the same manner as disk files. However, characters are not buffered by BASIC as they are for disk files. The record length for the device files is set to one. BASIC only sends a carriage return at the end of a line. If the device requires a line feed, the driver must provide it. When writing device drivers, keep in mind that other BASIC users will want to read and write control information. The writing and reading of device-control data is handled by the IOCTL statement and IOCTL$ function. None of the BASIC devices directly supports binary mode. However, the line printer devices (LPT1:, LPT2:) can be opened in binary mode by adding the BIN keyword: OPEN "LPT1:BIN" FOR OUTPUT AS #1 Opening a printer in BIN mode eliminates printing a carriage return at the end of a line. ──────────────────────────────────────────────────────────────────────────── NOTE In INPUT, RANDOM, and BINARY modes you can open a file under a different file number without first closing the file. In OUTPUT or APPEND mode you must close a file before opening it with a different file number. ──────────────────────────────────────────────────────────────────────────── ■ See Also FREEFILE ■ Examples The following statement opens MAILING.DAT as file number 1 and allows data to be added without destroying what is already in MAILING.DAT: OPEN "MAILING.DAT" FOR APPEND AS #1 If you wrote and installed a device driver named ROBOT, then the OPEN statement might appear as OPEN "\DEV\ROBOT" FOR OUTPUT AS #1 To open the printer for output, you could use either of the following two lines. (The first line uses the BASIC device LPT1: while the second line uses the DOS device LPT1.) OPEN "LPT1:" FOR OUTPUT AS #1 OPEN "LPT1" FOR OUTPUT AS #1 The following statement opens the file RECORDS in random-access mode, for reading only. The statement locks the file for writing, but allows reading by other processes while the OPEN is in effect. OPEN "RECORDS" FOR RANDOM ACCESS READ LOCK WRITE AS #1 The following example opens the file named INVEN for input as file number 2: OPEN "I",2,"INVEN" ──────────────────────────────────────────────────────────────────────────── OPEN COM Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Opens and initializes a communications channel for I/O ■ Syntax OPEN "COMn: optlist1 optlist2" «FOR mode» AS «#»filenum «LEN=reclen» ■ Remarks COMn: is the name of the device to be opened. The n argument is the number of a legal communications device, such as COM1: or COM2:. The first list of options, optlist1, has the following form: «speed»«,«parity» «,«data»«,«stop»»»» The following list describes the possible options: Option Description ────────────────────────────────────────────────────────────────────────── speed The "baud" rate (baud means "bits per second") of the device to be opened. Valid speeds are 75, 110, 150, 300, 600, 1200, 1800, 2400, 4800, and 9600. The default is 300 bps. parity The parity of the device to be opened. Valid entries for parity are: N (none), E (even), O (odd), S (space), or M (mark). data The number of data bits per byte. Valid entries are 5, 6, 7, or 8. stop The number of stop bits. Valid entries are 1, 1.5, or 2. ────────────────────────────────────────────────────────────────────────── Options from this list must be entered in the order shown; moreover, if any options from optlist2 are chosen, comma placeholders must still be used even if none of the options from optlist1 are chosen. For example: OPEN "COM1: ,,,,CD1500" FOR INPUT AS #1 If you set the data bits per byte to eight, you must specify no parity (N). Because QuickBASIC uses complete bytes (eight bits) for numbers, you must specify eight data bits when transmitting or receiving numeric data. The choices for optlist2 are described in the following list. The argument m is given in milliseconds; the default value for m is 1000. ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Option Description ────────────────────────────────────────────────────────────────────────── ASC Opens the device in ASCII mode. In ASCII mode, Option Description ────────────────────────────────────────────────────────────────────────── ASC Opens the device in ASCII mode. In ASCII mode, tabs are expanded to spaces, carriage returns are forced at end-of-line, and CTRL+Z is treated as end-of-file. When the channel is closed, CTRL+Z is sent over the RS-232 line. BIN Opens the device in binary mode. This option supersedes the LF option. BIN is selected by default unless ASC is specified. In the BIN mode, tabs are not expanded to spaces, a carriage return is not forced at the end-of-line, and CTRL+Z is not treated as end-of-file. When the channel is closed, CTRL+Z will not be sent over the RS-232 line. CD«m» Controls the timeout on the Data Carrier Detect line (DCD). If DCD is low for more than m milliseconds, a device timeout occurs. Option Description ────────────────────────────────────────────────────────────────────────── CS«m» Controls the timeout on the Clear To Send line (CTS). If CTS is low (there is no signal) for more than m milliseconds, a device timeout occurs. DS«m» Controls the timeout on the Data Set Ready line (DSR). If DSR is low for more than m milliseconds, a device timeout occurs. LF Allows communication files to be printed on a serial line printer. When LF is specified, a line-feed character (0AH) is automatically sent after each carriage-return character (0DH). This includes the carriage return sent as a result of the width setting. Note that INPUT and LINE INPUT, when used to read from a COM file that was opened with the LF option, stop when they see a carriage return, ignoring the line feed. Option Description ────────────────────────────────────────────────────────────────────────── carriage return, ignoring the line feed. OP«m» Controls how long the statement waits for the open to be successful. The parameter m is a value in the range 0 to 65,535 representing the number of milliseconds to wait for the communications lines to become active. If OP is specified without a value, the statement waits indefinitely. If OP is omitted, OPEN COM waits for ten times the maximum value of the CD or DS timeout values. RB«n» Sets the size of the receive buffer to n bytes. If n is omitted, or the option is omitted, the current value is used. The current value can be set by the /C option on the QuickBASIC or BC command line. The default is 512 bytes. The maximum size is 32,767 bytes. Option Description ────────────────────────────────────────────────────────────────────────── RS Suppresses detection of Request To Send (RTS). TB«n» Sets the size of the transmit buffer to n bytes. If n is omitted, or the option is omitted, the current value is used. The default size is 512 bytes. ────────────────────────────────────────────────────────────────────────── The options from the list above can be entered in any order, but they must be separated from one another by commas. For CS«m», DS«m», and CD«m», if there is no signal within m milliseconds, a timeout occurs. The value for m may range from 0 to 65,535, with 1000 as the default value. (The CD default is 0.) If m is equal to 0 for any of these options the option is ignored. The CTS line is checked whenever there is data in the transmit buffer if the CS option is specified. The DSR and DCD lines are continuously checked for timeouts if the corresponding options (DS, CD) are specified. The mode argument is one of the following string expressions: Mode Description ────────────────────────────────────────────────────────────────────────── OUTPUT Specifies sequential output mode INPUT Specifies sequential input mode RANDOM Specifies random-access mode ────────────────────────────────────────────────────────────────────────── If the mode expression is omitted, it is assumed to be random-access input/output. The filenum is the number used to open the file. The OPEN COM statement must be executed before a device can be used for communication using an RS-232 interface. If the device is opened in RANDOM mode, the LEN option specifies the length of an associated random-access buffer. The default value for length is 128. You can use any of the random-access I/O statements, such as GET and PUT, to treat the device as if it were a random-access file. The OPEN COM statement performs the following steps in opening a communications device: 1. The communications buffers are allocated and interrupts are enabled. 2. The Data Terminal Ready line (DTR) is set high. 3. If either of the OP or DS options is nonzero, the statement waits up to the indicated time for the Data Set Ready line (DSR) to be high. If a timeout occurs, the process goes to step 6. 4. The Request To Send line (RTS) is set high if the RS option is not specified. 5. If either of the OP or CD options is nonzero, OPEN COM waits up to the indicated time for the Data Carrier Detect line (DCD) to be high. If a timeout occurs, the process goes to step 6. Otherwise, OPEN COM has succeeded. 6. The open has failed due to a timeout. The process deallocates the buffers, disables interrupts, and clears all of the control lines. ──────────────────────────────────────────────────────────────────────────── NOTE Use a relatively large value for the OP option compared to the CS, DS, or CD options. If two programs are attempting to establish a communications link, they both need to attempt an OPEN during at least half of the time they are executing. ──────────────────────────────────────────────────────────────────────────── Any syntax errors in the OPEN COM statement produce an error message that reads Bad file name. ■ Example The following program fragment opens communications channel 1 in random-access mode at a speed of 9600 baud, no parity bit, eight data bits, and one stop bit. Input/output will be in the binary mode. Other lines in the program can now access channel 1 as file number 2. OPEN "COM1:9600,N,8,1,BIN" AS 2 ──────────────────────────────────────────────────────────────────────────── OPTION BASE Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Declares the default lower bound for array subscripts ■ Syntax OPTION BASE n ■ Remarks The OPTION BASE statement is never required. It is used to change the default lower bound for array subscripts. The value of n must be either 0 or 1. The default base is 0. If the following statement OPTION BASE 1 is executed, the lowest value an array subscript can have is 1. ──────────────────────────────────────────────────────────────────────────── NOTE The TO clause in the DIM statement provides an easier, more flexible way to control the range of an array's subscripts. If the lower bound of an array subscript is not explicitly set, then OPTION BASE can be used to change the default lower bound to 1. ──────────────────────────────────────────────────────────────────────────── The OPTION BASE statement can be used only once in a module (source file) and can only appear in the module-level code. An OPTION BASE statement must be used before any arrays are dimensioned. Chained programs may have an OPTION BASE statement if no arrays are passed in COMMON between them or if the specified base is identical in the chained programs. The chained-to program inherits the OPTION BASE value of the chaining program if OPTION BASE is omitted in the latter. ■ See Also DIM, LBOUND, REDIM ■ Example The following statement overrides the default value of zero, so the lowest value a subscript in an array can have in this program is 1: OPTION BASE 1 DIM A(20) PRINT LBOUND(A), UBOUND(A) ■ Output 1 20 ──────────────────────────────────────────────────────────────────────────── OUT Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Sends a byte to a machine I/O port ■ Syntax OUT port, data ■ Remarks The following list describes the arguments of the OUT statement: Argument Description ────────────────────────────────────────────────────────────────────────── port The number of the port. The number must be an integer expression in the range 0-65,535. data The data to be sent to the port. It must be an integer expression in the range 0-255. ────────────────────────────────────────────────────────────────────────── The OUT and INP statements give a BASIC program direct control over the hardware in a system through the I/O ports. These statements must be used carefully because they directly manipulate the hardware. ■ See Also INP, WAIT ■ Example The following example uses OUT and INP to control the timer and speaker to produce a note. (This example is specific to the IBM PC and close compatibles and produces unpredictable results on other machines.) ' Play a scale using the speaker and timer. CONST WHOLE=5000!, QRTR=WHOLE/4. CONST C=523.0, D=587.33, E=659.26, F=698.46, G=783.99, A=880.00 CONST B=987.77, C1=1046.50 CALL Sounds(C,QRTR) : CALL Sounds(D,QRTR) CALL Sounds(E,QRTR) : CALL Sounds(F,QRTR) CALL Sounds(G,QRTR) : CALL Sounds(A,QRTR) CALL Sounds(B,QRTR) : CALL Sounds(C1,WHOLE) ' Use ports 66, 67, and 97 to control the timer and speaker ' to produce a sound. SUB Sounds (Freq!,Length!) STATIC ' Divide the clock frequency by the sound frequency to ' get the number of "clicks" the clock must produce. Clicks%=CINT(1193280!/Freq!) LoByte%=Clicks% AND &H00FF HiByte%=Clicks%\256 ' Tell timer that data is coming. OUT 67,182 ' Send the low byte followed by the high byte of the count. OUT 66,LoByte% OUT 66,HiByte% ' Turn the speaker on by setting bits 0 and 1 of the PPI chip. ' Get the current value, and turn the bits on. SpkrOn%=INP(97) OR &H03 OUT 97,SpkrOn% ' Leave the speaker on for a while. FOR I!=1 TO Length! : NEXT I! ' Turn the speaker off. SpkrOff%=INP(97) AND &HFC OUT 97,SpkrOff% END SUB ──────────────────────────────────────────────────────────────────────────── PAINT Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Fills a graphics area with the color or pattern specified ■ Syntax PAINT «STEP» (x,y)«,«paint» «,«bordercolor» «,background»»» ■ Remarks The following list describes the parts of the PAINT statement: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Part Description ────────────────────────────────────────────────────────────────────────── STEP Defines coordinates to be relative to the most recently plotted point. For example, if the last point plotted were (10,10), then the coordinates referred to by STEP (4,5) would be (4+10, 5+10) or (14,15). (x,y) The coordinates where painting begins. The point must be inside or outside a figure, not on the border itself. If this point is inside, the figure's interior is painted; if the point is on the outside, the background is painted. paint A numeric or string expression. If paint is a numeric expression, then the number must be a valid color attribute. The corresponding color is Part Description ────────────────────────────────────────────────────────────────────────── valid color attribute. The corresponding color is used to paint the area. If you do not specify paint, the foreground color attribute is used. (See the COLOR, PALETTE, and SCREEN statements for discussions of valid colors, numbers, and attributes.) If the paint argument is a string expression, then PAINT does "tiling," a process that paints a pattern rather than a solid color. Tiling is similar to "line styling," which creates dashed lines rather than solid lines. bordercolor A numeric expression identifying the color attribute to use to paint the border of the figure. When the border color is encountered, painting of the current line stops. If the border color is not specified, the paint argument is used. Part Description ────────────────────────────────────────────────────────────────────────── used. background A string value giving the "background tile slice" to skip when checking for termination of the boundary. Painting is terminated when adjacent points display the paint color. Specifying a background tile slice allows you to paint over an already painted area. When you omit background the default is CHR$ (0). ────────────────────────────────────────────────────────────────────────── Painting is complete when a line is painted without changing the color of any pixel, in other words, when the entire line is equal to the paint color. The PAINT command permits coordinates outside the screen or viewport. Tiling "Tiling" is the design of a PAINT pattern that is eight bits wide and up to 64 bytes long. In the tile string, each byte masks eight bits along the x-axis when putting down points. The syntax for constructing this tile mask is PAINT (x,y), CHR$(arg1)+CHR$(arg2)+...+CHR$(argn) The arguments to CHR$ are numbers between 0 and 255, represented in binary form across the x axis of the tile. There can be up to 64 of these CHR$ elements; each generates an image not of the assigned character, but of the bit arrangement of the code for that character. For example, the decimal number 85 is binary 01010101; the graphic image line on a black-and-white screen generated by CHR$(85) is an eight-pixel line, with even-numbered points white and odd-numbered points black. That is, each bit equal to 1 turns the associated pixel on and each bit equal to 0 turns the associated bit off in a black-and-white system. The ASCII character CHR$(85), which is U, is not displayed in this case. When supplied, background defines the "background tile slice" to skip when checking for boundary termination. You cannot specify more than two consecutive bytes that match the tile string in the tile background slice. Specifying more than two consecutive bytes produces an error message that reads Illegal function call. Tiling can also be done to produce various patterns of different colors. See Chapter 5, "Graphics," in Programming in BASIC for a complete description of how to do tiling. ■ See Also CHR$, CIRCLE, DRAW, LINE, SCREEN ■ Example The following program draws a magenta fish with a cyan tail: CONST PI=3.1415926536 CLS SCREEN 1 CIRCLE (190,100),100,1,,,.3 'Outline fish body in cyan. CIRCLE (265,92),5,1,,,.7 'Outline fish eye in cyan. PAINT (190,100),2,1 'Fill in fish body with magenta. LINE (40,120)-STEP (0,-40),2 'Outline LINE -STEP (60,+20),2 ' tail in LINE -STEP (-60,+20),2 ' magenta. PAINT (50,100),1,2 'Paint tail cyan. CIRCLE (250,100),30,0,PI*3/4,PI* 5/4,1.5 'Draw gills in black. FOR Y = 90 TO 110 STEP 4 LINE (40,Y)-(52,Y),0 'Draw comb in tail. NEXT ──────────────────────────────────────────────────────────────────────────── PALETTE, PALETTE USING Statements ──────────────────────────────────────────────────────────────────────────── ■ Action Changes one or more of the colors in the palette ■ Syntax PALETTE «attribute,color» PALETTE USING array-name «(array-index)» ■ Remarks The PALETTE statement takes the following arguments: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Argument Description ────────────────────────────────────────────────────────────────────────── attribute The palette attribute to be changed. color The display color number to be assigned to the attribute. The color must be a long integer expression for the IBM Video Graphics Array adapter (VGA) and IBM Multicolor Graphics Array adapter (MCGA) in screen modes 11 to 13. Integer or long-integer expressions may be used with the Argument Description ────────────────────────────────────────────────────────────────────────── or long-integer expressions may be used with the IBM Enhanced Graphics Adapter (EGA). array-name An array containing the color numbers to be assigned to the attributes available in the current screen mode. The VGA and MCGA adapters require a long integer array in screen modes 11 to 13. With the EGA this can be either an integer or long-integer array. array-index The index of the first array element to use in setting the palette. ────────────────────────────────────────────────────────────────────────── The PALETTE statement works only on systems equipped with the EGA, VGA, or MCGA adapters. The statement provides a way of mapping display colors (the actual binary values used by the adapter) to color attributes (a smaller set of values). All BASIC graphics statements such as CIRCLE, COLOR, DRAW, or LINE use color attributes rather than display-color values. When a program enters a screen mode, the attributes are set to a series of default color values. (See the SCREEN statement for a list of the default colors.) In the EGA, VGA, and MCGA adapters these default values have been selected so the display shows the same colors, even though the EGA uses different color values. With the palette statement you can assign different colors to the attributes, giving you greater control over the colors on the display. A PALETTE statement with no arguments sets the palette back to the default color values. When you execute a PALETTE statement with arguments, the adapter subsequently uses the display color (indicated by color) whenever the value attribute appears in a statement like DRAW or LINE that specifies a color. Changing the display color assigned to an attribute changes the color on the screen immediately. For example, assume that the current palette contains colors 0, 1, 2, and 3 in the four attributes numbered 0, 1, 2, and 3. The DRAW statement DRAW "C3L100" selects attribute 3, and draws a line of 100 pixels using the display color associated with attribute 3, in this case also 3. If the statement PALETTE 3,2 is executed, then the color associated with attribute 3 is changed to color 2. All text or graphics currently on the screen displayed using attribute 3 are instantaneously changed to color 2. Text or graphics subsequently displayed with attribute 3 are also displayed in color 2. The new palette of colors contains 0, 1, 2, and 2. With the USING option, all entries in the palette can be modified in one PALETTE statement. The array-name argument is the name of an integer or long-integer array and the array-index specifies the index of the first array element in the array-name to use in setting the palette. Each attribute in the palette is assigned a corresponding color from this array. The array must be dimensioned large enough to set all the palette entries after array-index. For example, if you are assigning colors to all 16 attributes, and the index of the first array element that is given in your PALETTE USING statement is 5, then the array must be dimensioned to hold at least 20 elements (since the number of elements from 5-20, inclusive, is 16): DIM PAL%(20) . . . PALETTE USING PAL%(5) A color argument of -1 in the array leaves the attribute unchanged. All other negative numbers are invalid values for color. You can use the COLOR statement to set the default foreground color and the background display color. The foreground color argument specifies the way text characters appear on the display screen. Under a common initial palette setting, points colored with the attribute 0 appear black on the display screen. Using the PALETTE statement, you could, for example, change the mapping of attribute 0 from black to white. Table R.5 lists attribute and color ranges for various adapter types and screen modes. Table R.5 Screen Color and Attribute Ranges ╓┌─┌───────────┌────────────────────────┌───────────┌────────────┌───────────╖ Screen Monitor Attribute Color Mode Attached Adapter Range Range ────────────────────────────────────────────────────────────────────────── 0 Monochrome MDPA 0-15 N/A Monochrome EGA 0-15 0-2 Color CGA 0-15 N/A Color/Enhanced EGA 0-15 0-63 N/A VGA 0-15 0-63 N/A MCGA 0-15 N/A 1 Color CGA 0-3 N/A Color/Enhanced EGA 0-3 0-15 N/A VGA 0-3 0-15 N/A MCGA 0-3 N/A 2 Color CGA 0-1 N/A Color/Enhanced EGA 0-1 0-15 Screen Monitor Attribute Color Mode Attached Adapter Range Range ────────────────────────────────────────────────────────────────────────── Color/Enhanced EGA 0-1 0-15 N/A VGA 0-1 0-15 N/A MCGA 0-1 N/A 7 Color/Enhanced EGA 0-15 0-15 N/A VGA 0-15 0-15 8 Color/Enhanced EGA 0-15 0-15 N/A VGA 0-15 0-15 9 Enhanced EGA 0-3 0-63 Enhanced EGA 0-15 0-63 N/A VGA 0-16 0-63 10 Monochrome EGA 0-3 0-8 N/A VGA 0-3 0-8 11 N/A VGA 0-1 0-262,143 N/A MCGA 0-1 0-262,143 12 N/A VGA 0-15 0-262,143 13 N/A VGA 0-255 0-262,143 N/A MCGA 0-255 0-262,143 ────────────────────────────────────────────────────────────────────────── Screen Monitor Attribute Color Mode Attached Adapter Range Range ────────────────────────────────────────────────────────────────────────── ────────────────────────────────────────────────────────────────────────── The VGA uses a different way of calculating color values from the EGA. To calculate a color value, select the intensities of red, green, and blue. The intensity of a color is a number from 0 (low intensity) to 63 (high intensity). Then use the following formula to calculate the actual color number: color number = 65536 * blue + 256 * green + red Because there are gaps in the range of color numbers, you should use the formula rather than just select a number. When used with the IBM Analog Monochrome Monitor, the VGA color values are converted to a gray-scale value by taking a weighted sum of the red, blue, and green intensities as follows: gray value = 11% blue + 59% green + 30% red For example if the blue, green, and red intensities are 45, 20, and 20, the gray value would be .11*45+.59*20+.30*20 or 22 (the fraction in the result is dropped). See the SCREEN statement for the list of colors available for various screen-mode, monitor, and graphics-adapter combinations. ──────────────────────────────────────────────────────────────────────────── NOTE Because of their wide range of colors, the VGA and MCGA adapters require a long-integer array in the PALETTE USING statement in screen modes 11 to 13. ──────────────────────────────────────────────────────────────────────────── ■ See Also CIRCLE, COLOR, DRAW, LINE, SCREEN ■ Examples The following lines show the different forms of the PALETTE and PALETTE USING statements: PALETTE 0,2 'Changes all points colored with attribute 0 to 'color 2. PALETTE USING A%(0) 'Changes each palette entry. Since the 'array is initialized to zero when it 'is first declared, all attributes are 'now mapped to display color zero. The 'screen will now appear as one single 'color. However, it will still be 'possible to execute BASIC statements. PALETTE 'Sets each palette entry to its appropriate 'initial display color. Actual initial colors 'depend on your screen-hardware configuration. ──────────────────────────────────────────────────────────────────────────── PCOPY Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Copies one screen page to another ■ Syntax PCOPY sourcepage, destinationpage ■ Remarks The sourcepage is an integer expression in the range 0 to n, where n is the maximum number of pages determined by the current video-memory size and the size per page for the current screen mode. The destinationpage has the same requirements as the sourcepage. See the SCREEN statement for more information about the number of pages available in different modes. ■ See Also CLEAR, SCREEN ■ Example The following example copies the contents of page 1 to page 2: PCOPY 1,2 ──────────────────────────────────────────────────────────────────────────── PEEK Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the byte stored at a specified memory location ■ Syntax PEEK(address) ■ Remarks The returned value is an integer in the range 0-255. The argument address is a value in the range 0-65,535. The argument address is treated as the offset from the current default segment (as set by the DEF SEG statement). If the argument is a single- or double-precision floating-point value or a long integer, it is converted to a two-byte integer. The PEEK function complements the POKE statement. ■ See Also DEF SEG, POKE, VARPTR ■ Example See the example for DEF SEG. ──────────────────────────────────────────────────────────────────────────── PEN Function ──────────────────────────────────────────────────────────────────────────── ■ Action Reads the lightpen coordinates ■ Syntax PEN(n) ■ Remarks The argument n indicates what value is to be returned. It is a numeric expression in the range 0-9. ──────────────────────────────────────────────────────────────────────────── NOTE The PEN function does not work when the mouse driver is enabled because the mouse driver uses the PEN function's BIOS calls. Use mouse function 14 to disable the driver's lightpen emulation. Mouse function 13 turns emulation back on. See your mouse manual for more information. ──────────────────────────────────────────────────────────────────────────── The following list describes the values for n and the corresponding values returned by PEN: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Argument Value Returned ────────────────────────────────────────────────────────────────────────── 0 The most recent pen use: -1 if pen was down since last poll, 0 if not 1 The x pixel coordinate where pen was last pressed 2 The y pixel coordinate where pen was last pressed 3 The current pen-switch value: -1 if down, 0 if up Argument Value Returned ────────────────────────────────────────────────────────────────────────── 4 The last known valid x pixel coordinate 5 The last known valid y pixel coordinate 6 The character row position where pen was last pressed 7 The character column position where pen was last pressed 8 The last known character row where the pen was positioned 9 The last known character column where the pen was positioned ────────────────────────────────────────────────────────────────────────── ■ Example The following example produces an endless loop to print the current pen-switch status (UP/DOWN): CLS PEN ON DO P = PEN(3) LOCATE 1,1 : PRINT "PEN IS "; IF P THEN PRINT "DOWN" ELSE PRINT "UP" X = PEN(4) : Y = PEN(5) PRINT "X =" X, "Y =" Y LOOP ──────────────────────────────────────────────────────────────────────────── PEN ON, OFF, and STOP Statements ──────────────────────────────────────────────────────────────────────────── ■ Action Enables, disables, or suspends lightpen-event trapping ■ Syntax PEN ON PEN OFF PEN STOP ■ Remarks The PEN ON statement enables lightpen-event trapping by using an ON PEN statement. The pen is initially off. A lightpen event occurs whenever the lightpen is activated by pressing the tip to the screen or pressing the touch ring. A PEN ON statement must be executed before any read-pen function calls. If a read-pen function is called when the pen is off, an error message results that reads Illegal function call. The PEN OFF statement disables lightpen event trapping. The PEN STOP statement suspends lightpen event trapping; a pen event is remembered and trapped as soon as event trapping is enabled. To speed program execution, the pen should be turned off by using a PEN OFF statement when pen trapping is not needed. ──────────────────────────────────────────────────────────────────────────── NOTE The lightpen requires an IBM Color Graphics Adapter. ──────────────────────────────────────────────────────────────────────────── ■ See Also ON event, PEN Function ■ Example See the example for the PEN function. ──────────────────────────────────────────────────────────────────────────── PLAY Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Plays music as specified by a string ■ Syntax PLAY commandstring ■ Remarks The commandstring is a string expression containing one or more of the commands listed below. The PLAY statement uses a concept similar to DRAW in that it embeds a music macro language (described below) in one statement. A set of commands, used as part of the PLAY statement, specifies a particular action. In compiled programs, you should use the VARPTR$(variable) form for variables. For example, the BASICA statements PLAY "XA$" PLAY "O=I" should be written for the compiler like this: PLAY "X" + VARPTR$(A$) PLAY "O=" + VARPTR$(I) The commandstring music macros are described as follows: Octave Commands Action ────────────────────────────────────────────────────────────────────────── o n Sets the current octave. There are seven octaves, numbered 0-6. > Increases octave by 1. Octave cannot go beyond 6. < Decreases octave by 1. Octave cannot drop below 0. Tone Commands Action ────────────────────────────────────────────────────────────────────────── A-G Plays a note in the range A-G. The "#" symbol or the "+" symbol after a note specifies sharp; a "-" specifies flat. N n Plays note n. The range for n is 0-84 (in the seven possible octaves, there are 84 notes); n = 0 means a rest. Duration Commands Action ────────────────────────────────────────────────────────────────────────── L n Sets the length of each note. L4 is a quarter note, L1 is a whole note, etc. The range for n is 1-64. The length may also follow the note when a change of length only is desired for a particular note. In this case, A16 is equivalent to L16A. MN Sets "music normal" so that each note will play 7/8 of the time determined by the length (L). ML Sets "music legato" so that each note will play the full period set by length (L). MS Sets "music staccato" so that each note will play 3/4 of the time determined by the length (L). Tempo Commands Action ────────────────────────────────────────────────────────────────────────── P n Specifies a pause, ranging from 1-64. This option corresponds to the length of each note, set with L n. T n Sets the "tempo," or the number of L4 quarter notes in one minute. The range for n is 32-255. The default for n is 120. Operation Commands Action ────────────────────────────────────────────────────────────────────────── MF Sets music (PLAY statement) and SOUND to run in the foreground. That is, each subsequent note or sound will not start until the previous note or sound has finished. This is the default setting. MB Music (PLAY statement) and SOUND are set to run in the background. That is, each note or sound is placed in a buffer, allowing the BASIC program to continue executing while the note or sound plays in the background. The maximum number of notes that can be played in the background at one time is 32. Suffixes Action ────────────────────────────────────────────────────────────────────────── # or + Follows a specified note and turns it into a sharp. - Follows a specified note and turns it into a flat. . A period after a note causes the note to play 3/2 times the length determined by L (length) times T (tempo). The period has the same meaning as in a musical score. Multiple periods can appear after a note. Each period adds a length equal to one half the length of the previous period. The command A. plays 1 + 1/2 or 3/2 times the length; A.. plays 1 + 1/2 + 1/4 or 7/4 times the length; and so on. Periods can appear after a pause (P). In this case, the pause length is scaled in the same way notes are scaled. Substring Command Action ────────────────────────────────────────────────────────────────────────── "X" + VARPTR$(string) Executes a substring. ────────────────────────────────────────────────────────────────────────── Because of the slow clock-interrupt rate, some notes will not play at higher tempos (L64 at T255, for example). ■ Examples The following example uses ">" to play the scales from octave 0 to octave 6, then reverses with "<" to play the scales from octave 6 to octave 0: SCALE$ = "CDEFGAB" PLAY "o0 X" + VARPTR$(SCALE$) FOR I = 1 TO 6 PLAY ">X" + VARPTR$(SCALE$) NEXT PLAY "o6 X" + VARPTR$(SCALE$) FOR I = 1 TO 6 PLAY "<X" + VARPTR$(SCALE$) NEXT The following example plays the beginning of the first movement of Beethoven's Fifth Symphony: LISTEN$ = "T180 o2 P2 P8 L8 GGG L2 E-" FATE$ = "P24 P8 L8 FFF L2 D" PLAY LISTEN$ + FATE$ ──────────────────────────────────────────────────────────────────────────── PLAY Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the number of notes currently in the background-music queue ■ Syntax PLAY (n) ■ Remarks The argument n is a dummy argument and may be any numeric value. PLAY(n) will return 0 when the user is in music-foreground mode. ■ See Also ON event; PLAY Statement; PLAY ON, OFF, and STOP ■ Example See the examples for the ON event statements. ──────────────────────────────────────────────────────────────────────────── PLAY ON, OFF, and STOP Statements ──────────────────────────────────────────────────────────────────────────── ■ Action PLAY ON enables play event trapping, PLAY OFF disables play event trapping, and PLAY STOP suspends play event trapping. ■ Syntax PLAY ON PLAY OFF PLAY STOP ■ Remarks These statements are used with the ON PLAY statement to trap play events. When a PLAY OFF statement is executed, the event-trapping subroutine is not performed and the event is not remembered. A PLAY STOP statement does not perform the event-trapping subroutine, but the subroutine is performed as soon as a PLAY ON statement is executed. When a play event trap occurs (that is, the GOSUB is performed), an automatic PLAY STOP is executed so that recursive traps cannot take place. The RETURN from the trapping subroutine automatically performs a PLAY ON statement unless an explicit PLAY OFF was performed inside the subroutine. ■ Example See the entry for the ON event statements for an example of play event trapping. ──────────────────────────────────────────────────────────────────────────── PMAP Function ──────────────────────────────────────────────────────────────────────────── ■ Action Maps view-coordinate expressions to physical locations or maps physical expressions to a view-coordinate location ■ Syntax PMAP (expression, function) ■ Remarks The argument expression indicates the coordinate of the point to be mapped. The argument function can have one of the four following values: Value Description ────────────────────────────────────────────────────────────────────────── 0 Maps view-coordinate expression to physical x-coordinate 1 Maps view-coordinate expression to physical y-coordinate 2 Maps physical expression to view x-coordinate 3 Maps physical expression to view y-coordinate ────────────────────────────────────────────────────────────────────────── The four PMAP functions allow the user to find equivalent point locations between the view coordinates created with the WINDOW statement and the physical coordinate system of the screen or viewport as defined by the VIEW statement. ■ See Also VIEW, WINDOW ■ Example The following fragment uses PMAP to convert coordinate values from view to screen coordinates and from screen coordinates to view coordinates: SCREEN 2 'Coordinates of upper-left corner of window defined in follow- 'ing statement are (80,100); coordinates of lower-right corner 'are 200,200. WINDOW SCREEN (80,100) - (200,200) 'If physical screen coordinates are (0,0) in the upper-left 'corner and (639,199) in the lower-right corner, then the 'following statements will return the screen coordinates 'equivalent to the view coordinates 80,100. X = PMAP(80,0) 'X = 0 Y = PMAP(100,1) 'Y = 0 'The following statements will return the screen coordinates 'equivalent to the view coordinates 200,200. X = PMAP(200,0) 'X = 639 Y = PMAP(200,1) 'Y = 199 'The following statements will return the view coordinates 'equivalent to the screen coordinates 639,199. X = PMAP(639,2) 'X = 200 Y = PMAP(199,3) 'Y = 200 ──────────────────────────────────────────────────────────────────────────── POINT Function ──────────────────────────────────────────────────────────────────────────── ■ Action Reads the color number of a pixel from the screen or returns the pixel's coordinates ■ Syntax POINT (x,y) POINT (number) ■ Remarks The coordinates x and y refer to the pixel being evaluated by the POINT function. When called with two coordinates, POINT returns the color number of the indicated pixel. If the specified pixel is out of range, POINT returns the value -1. POINT with one argument (as explained in the list below) allows the user to retrieve the current graphics-cursor coordinates. Argument Value Returned ────────────────────────────────────────────────────────────────────────── 0 The current physical x-coordinate. 1 The current physical y-coordinate. 2 The current view x-coordinate. This returns the same value as the POINT(0) function if the WINDOW statement has not been used. 3 The current view y-coordinate. This returns the same value as the POINT(1) function if the WINDOW statement has not been used. ────────────────────────────────────────────────────────────────────────── ■ Example The following example redraws the ellipse drawn with the CIRCLE statement, using POINT to find the border of the ellipse by testing for a change in color: DEFINT X,Y INPUT "Enter angle of tilt in degrees (0 to 90): ",Ang SCREEN 1 'Medium resolution screen. Ang = (3.1415926#/180)*Ang 'Convert degrees to radians. Cs = COS(Ang) : Sn = SIN(Ang) CIRCLE (45,70),50,2,,,2 'Draw ellipse. PAINT (45,70),2 'Paint interior of ellipse. FOR Y = 20 TO 120 FOR X = 20 TO 70 'Check each point in rectangle enclosing ellipse. IF POINT(X,Y) <> 0 THEN 'If the point is in the ellipse, plot a corresponding 'point in the "tilted" ellipse. Xnew = (X*Cs - Y*Sn) + 200 : Ynew = (X*Sn + Y*Cs) PSET(Xnew,Ynew),2 END IF NEXT NEXT END ──────────────────────────────────────────────────────────────────────────── POKE Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Writes a byte into a memory location ■ Syntax POKE address,byte ■ Remarks The expression address is a value that represents the address of the memory location; address must be in the range 0-65,535. The expression byte is the data byte to be written; it is an integer value in the range 0-255. The address is treated as the offset from the current default segment (as set by the DEF SEG statement). If the argument is a single- or double-precision floating-point value or a long integer, it is converted to a two-byte integer. The complementary function to POKE is PEEK. ──────────────────────────────────────────────────────────────────────────── WARNING Use POKE carefully. If used incorrectly, it can cause BASIC or the operating system to fail. ──────────────────────────────────────────────────────────────────────────── ■ See Also DEF SEG, PEEK, VARPTR ■ Example See the example for the DEF SEG statement. ──────────────────────────────────────────────────────────────────────────── POS Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the current horizontal position of the cursor ■ Syntax POS(0) ■ Remarks The leftmost cursor position is numbered 1. To return the current vertical-line position of the cursor, use the CSRLIN function. ■ See Also CSRLIN, LPOS ■ Example The following example uses POS to start input on a new line after every 40 characters: PRINT "This program starts a new line after every forty" PRINT "characters are printed. Press <CTRL-C> to end." PRINT DO DO WHILE POS(0) < 41 'Stay on same line until 40 characters DO 'printed. Char$=INKEY$ LOOP WHILE Char$="" 'If input is key combination CTRL-C then end; otherwise, 'print the character. IF ASC(Char$) = 3 THEN END ELSE PRINT Char$; LOOP PRINT 'Print a new line. LOOP ──────────────────────────────────────────────────────────────────────────── PRESET Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Draws a specified point on the screen ■ Syntax PRESET «STEP»(xcoordinate,ycoordinate) «,color» ■ Remarks PRESET works exactly like PSET, except that if the color is not specified, the background color is selected. The following list describes the parts of the PRESET statement: Part Description ────────────────────────────────────────────────────────────────────────── STEP Indicates that the given x- and y-coordinates are relative, not absolute. The coordinates are treated as distances from the most recent cursor location, not distances from the (0,0) screen coordinate. For example, if the most recent point referenced were (10,10), PRESET STEP (10,5) would reference the point at (20,15). xcoordinate The x-coordinate of the pixel that is to be set. ycoordinate The y-coordinate of the pixel that is to be set. color The color attribute for the specified point. ────────────────────────────────────────────────────────────────────────── If a coordinate is outside the current viewport, no action is taken, nor is an error message given. ■ See Also PSET ■ Example The following example draws a line 20 pixels long. The line then moves across the screen from left to right: SCREEN 1 : COLOR 1,1 : CLS FOR I = 0 TO 299 STEP 3 FOR J = I TO 20+I PSET (J,50),2 'Draw the line in new location. NEXT FOR J = I TO 20+I PRESET (J,50) 'Erase the line. NEXT NEXT ──────────────────────────────────────────────────────────────────────────── PRINT Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Outputs data on the screen ■ Syntax PRINT «expressionlist» «{, | ;}» ■ Remarks If expressionlist is omitted, a blank line is printed. If expressionlist is included, the values of the expressions are printed on the screen. The expressions in the list may be numeric or string expressions. (String literals must be enclosed in quotation marks.) A printed number is always followed by a space. If the number is positive, it is also preceded by a space; if the number is negative, it is preceded by a minus sign (-). There are two formats that PRINT uses to display single- and double-precision numbers: fixed point and floating point. If PRINT can represent a single-precision number in the fixed-point format with seven or fewer digits and no loss of accuracy, then it uses the fixed-point format; otherwise, it uses the floating-point format. For example, the number 1.1E-6 is output as .0000011, but the number 1.1E-7 is output as 1.1E-7. Similarly, if PRINT can represent a double-precision number in the fixed-point format with 16 or fewer digits and no loss of accuracy, then it uses the fixed-point format; otherwise, it uses the floating-point format. For example, the number 1.1D-15 is output as .0000000000000011, but the number 1.1D-16 is output as 1.1D-16. The PRINT statement supports only elementary BASIC data types (integers, long integers, single-precision real numbers, double-precision real numbers, and strings). To print information in a record, use the PRINT statement with individual record elements as in the following fragment: TYPE MyType Word AS STRING*20 Count AS LONG END TYPE DIM Myrec AS MyType PRINT Myrec.Word PRINT POSITIONS The position of each printed item is determined by the punctuation used to separate the items in the list. BASIC divides the line into print zones of 14 spaces each. In the expression list, a comma makes the next value print at the start of the next zone. A semicolon makes the next value print immediately after the last value. Typing one or more spaces or tabs between expressions has the same effect as typing a semicolon. If a comma or a semicolon terminates the list of expressions, the next PRINT statement prints on the same line, after spacing accordingly. If the expression list ends without a comma or a semicolon, a carriage-return and line-feed sequence is printed at the end of the line. If the printed line is wider than the screen width, BASIC goes to the next physical line and continues printing. ■ Examples In the following example, the commas in the PRINT statement print each value at the beginning of the next print zone: X=5 PRINT X+5, X-5, X*(-5), X^5 END ■ Output 10 0 -25 3125 In the following example, the semicolon at the end of the first PRINT statement makes the first two PRINT statements print on the same line. The last PRINT statement prints a blank line before the next prompt. DO INPUT "Input X (input 0 to end): ", X IF X = 0 THEN EXIT DO ELSE PRINT X "squared is" X^2 "and"; PRINT X "cubed is" X^3 PRINT END IF LOOP ■ Output Input X (input 0 to end): 9 9 squared is 81 and 9 cubed is 729 Input X (input 0 to end): 21 21 squared is 441 and 21 cubed is 9261 Input X (input 0 to end): 0 In the following example, the semicolons in the PRINT statement print each value immediately after the preceding value. (Remember, a space always follows a number and a space precedes a positive number.) FOR X=1 TO 5 J=J+5 K=K+10 PRINT J;K; NEXT X ■ Output 5 10 10 20 15 30 20 40 25 50 ──────────────────────────────────────────────────────────────────────────── PRINT #, PRINT # USING Statements ──────────────────────────────────────────────────────────────────────────── ■ Action Writes data to a sequential file ■ Syntax PRINT #filenumber,«USING stringexpression;» expressionlist «{, | ;}» ■ Remarks The filenumber is the number specified when the file was opened for output. The stringexpression consists of formatting characters as described under PRINT USING. The expressions in expressionlist are the numeric or string expressions to be written to the file. Spaces, commas, and semicolons in the expressionlist have the same meaning they have in a PRINT statement. If you omit expressionlist, the PRINT # statement prints a blank line in the file. PRINT # works like PRINT and writes an image of the data to the file, just as the data would be displayed on the terminal screen. For this reason, be careful to delimit the data so it is output correctly. If you use commas as delimiters, the blanks between print fields are also written to the file. For more information, see Chapter 3, "File and Device I/O," in Programming in BASIC. ■ See Also PRINT; PRINT USING; WRITE# ■ Example The following example shows the effects of omitting and of including delimiters in data written out with PRINT #: A$ = "CAMERA, AUTOFOCUS" : B$= "September 20, 1985" : C$ = "42" Q$ = CHR$(34) OPEN "INVENT.DAT" FOR OUTPUT AS #1 'Open INVENT.DAT for writing 'Write A$, B$, C$ without delimiters. PRINT #1, A$ B$ C$ 'Write A$, B$, C$ with delimiters. PRINT #1, Q$ A$ Q$ Q$ B$ Q$ Q$ C$ Q$ CLOSE #1 OPEN "INVENT.DAT" FOR INPUT AS #1 'Open INVENT.DAT for reading. FOR I% = 1 TO 2 'Read first two records and INPUT #1, First$,Second$,Third$ 'print. PRINT First$ TAB(30) Second$ TAB(60) Third$ : PRINT NEXT CLOSE #1 ■ Output CAMERA AUTOFOCUSSeptember 20 198542 CAMERA, AUTOFOCUS September 20, 1985 42 ──────────────────────────────────────────────────────────────────────────── PRINT USING Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Prints strings or numbers using a specified format ■ Syntax PRINT USING formatstring; expressionlist «{, | ;}» ■ Remarks The formatstring is a string literal (or variable) containing literal characters to print (such as labels) and special formatting characters. These formatting characters determine the field and the format of the printed strings or numbers. Spaces, commas, and semicolons in the expressionlist have the same meaning they do in a PRINT statement. The expressionlist contains the string expressions or numeric expressions to be printed, separated by semicolons. When PRINT USING is used to print strings, you may use one of three formatting characters to format the string field, as described in the following list: Character Description ────────────────────────────────────────────────────────────────────────── ! Only the first character in the given string is to be printed. \ \ Prints 2 + n characters from the string, where n is the number of spaces between the two backslashes. If the backslashes are typed with no spaces, two characters are printed. With one space, three characters are printed, and so on. If the field is longer than the string, the string is left-justified in the field and padded with spaces on the right. & Indicates a variable-length string field. When the field is specified with the ampersand (&), the string is output without modification. ────────────────────────────────────────────────────────────────────────── When PRINT USING is used to print numbers, the following special characters can be used to format the numeric field: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Character Description ────────────────────────────────────────────────────────────────────────── # Represents each digit position. Digit positions are always filled. If the number to be printed has fewer digits than positions specified, the number is right-justified (preceded by spaces) in the field. . Prints a decimal point. A decimal point may be inserted at any position in the field. If the format string specifies that a digit is to precede the decimal point, the digit is always printed (as 0, if necessary). If necessary, Character Description ────────────────────────────────────────────────────────────────────────── printed (as 0, if necessary). If necessary, numbers are rounded. + Causes the sign of the number (plus or minus) to be printed before the number (if it appears at the beginning of the format string) or after (if it appears at the end of the format string). - Causes a negative number to be printed with a trailing minus sign if it appears at the end of the format string. ** Causes leading spaces in the numeric field to be filled with asterisks. The double asterisk also specifies positions for two more digits. $$ Causes a dollar sign to be printed to the immediate left of the formatted number. The $$ specifies two more digit positions, one of which Character Description ────────────────────────────────────────────────────────────────────────── specifies two more digit positions, one of which is the dollar sign. **$ Combines the effects of the double-asterisk and double-dollar-sign symbols. Leading spaces are asterisk-filled and a dollar sign is printed before the number. The **$ symbols specify three more digit positions, one of which is the dollar sign. When negative numbers are printed, the minus sign appears to the immediate left of the dollar sign. , If the comma appears to the left of the decimal point in a format string, it causes a comma to be printed to the left of every third digit left of the decimal point. If it appears at the end of the format string, it is printed as part of the string. A comma specifies another digit position. The comma has no effect if used with exponential Character Description ────────────────────────────────────────────────────────────────────────── The comma has no effect if used with exponential (^^^^ or ^^^^^) format. ^^^^ Specifies exponential format. You can also use five carets (^^^^^) to allow E+xxx to be printed for larger numbers. Any decimal point position may be specified. The significant digits are left-justified and the exponent is adjusted. Unless a leading +, trailing +, or - is specified, one digit position is used to the left of the decimal point to print a space or a minus sign. _ An underscore in the format string prints the next character as a literal character. A literal underscore is printed as the result of two underscores ( __ ) in the format string. % If the number to be printed is larger than the Character Description ────────────────────────────────────────────────────────────────────────── % If the number to be printed is larger than the specified numeric field, a percent sign (%) is printed in front of the number. If rounding causes the number to exceed the field, a percent sign is printed in front of the rounded number. If the number of digits specified exceeds 24, an error message results that reads Illegal function call. ────────────────────────────────────────────────────────────────────────── ■ Examples The following example shows the results of using the three string-formatting characters: 'Using the three string-formatting characters to modify the 'appearance of printed output. A$ = "LOOK" : B$ = "OUT" PRINT USING "!";A$;B$ PRINT USING "\ \";A$;B$ 'Two spaces between back- 'slashes, will print four 'characters from A$. PRINT USING "\ \";A$;B$;"!!" 'Three spaces, will print PRINT USING "!";A$; 'A$ and a blank. PRINT USING "&";B$ ■ Output LO LOOKOUT LOOK OUT !! LOUT The following example shows the effects of different combinations of numeric formatting characters: 'Format and print numeric data. PRINT USING "##.##";.78 PRINT USING "###.##";987.654 PRINT USING "##.## ";10.2,5.3,66.789,.234 PRINT USING "+##.## ";-68.95,2.4,55.6,-.9 PRINT USING "##.##- ";-68.95,22.449,-7.01 PRINT USING "**#.# ";12.39,-0.9,765.1 PRINT USING "$$###.##";456.78 PRINT USING "**$##.##";2.34 PRINT USING "####,.##";1234.5 PRINT USING "##.##^^^^";234.56 PRINT USING ".####^^^^-";-888888 PRINT USING "+.##^^^^";123 PRINT USING "+.##^^^^^";123 PRINT USING "_!##.##_!";12.34 PRINT USING "##.##";111.22 PRINT USING ".##";.999 ■ Output 0.78 987.65 10.20 5.30 66.79 0.23 -68.95 +2.40 +55.60 -0.90 68.95- 22.45 7.01- *12.4 *-0.9 765.1 $456.78 ***$2.34 1,234.50 2.35E+02 .8889E+06- +.12E+03 +.12E+003 !12.34! %111.22 %1.00 ──────────────────────────────────────────────────────────────────────────── PSET Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Draws a point on the screen ■ Syntax PSET «STEP»(xcoordinate,ycoordinate) «,color» ■ Remarks The following list describes the parts of the PSET statement: Part Description ────────────────────────────────────────────────────────────────────────── STEP Indicates that the given xcoordinate and ycoordinate are relative, not absolute. The coordinates are treated as distances from the most recent cursor location, not distances from the (0,0) screen coordinate. For example, if the most recent point referenced were (10,10) then PSET STEP (10,5) would reference the point at (20,15). xcoordinate The x-coordinate of the pixel that is to be set. ycoordinate The y-coordinate of the pixel that is to be set. color The color attribute for the specified point. ────────────────────────────────────────────────────────────────────────── If a coordinate is outside the current viewport, no action is taken nor is an error message given. PSET allows the color to be left off the command line. If it is omitted, the default is the foreground color. ■ See Also PRESET ■ Example The following example draws a line from (0,0) to (100,100) and then erases that line by writing over it with the background color: SCREEN 2 'Draw a line from (0,0) to (100,100). FOR I=0 TO 100 PSET (I,I) NEXT I FOR I=0 TO 100 'Now erase that line. PSET STEP (-1,-1),0 NEXT I ──────────────────────────────────────────────────────────────────────────── PUT Statement──Graphics ──────────────────────────────────────────────────────────────────────────── ■ Action Places a graphic image obtained by a GET statement onto the screen ■ Syntax PUT «STEP» (x, y), arrayname«(indices)» «,actionverb» ■ Remarks The parts of the PUT statement are described as follows: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Part Description ────────────────────────────────────────────────────────────────────────── STEP Indicates that the given x- and y-coordinates are relative, not absolute. The coordinates are treated as distances from the most recent cursor location, not distances from the (0,0) screen coordinate. For example, if the most recent point referenced were (10,10) then the statement PUT STEP (10,5),Ball would put the object stored in Ball at (20,15). Part Description ────────────────────────────────────────────────────────────────────────── would put the object stored in Ball at (20,15). (x,y) Coordinates specifying the top-left corner of the rectangle enclosing the image to be placed in the current output window. arrayname The name of the array that holds the image. See the entry for GET (Graphics) for the formula that computes the size of this array. The array can be a multidimensional array. indices Specifies that the image is retrieved starting from the designated array element, rather than at the first array element. actionverb The actionverb determines the interaction between the stored image and the one already on the screen. ────────────────────────────────────────────────────────────────────────── Part Description ────────────────────────────────────────────────────────────────────────── ────────────────────────────────────────────────────────────────────────── The different values for actionverb are described in the following list. The default for actionverb is XOR. ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Verb Description ────────────────────────────────────────────────────────────────────────── PSET Transfers the data point-by-point onto the screen. Each point has the exact color attribute it had when it was taken from the screen with GET. PRESET The same as PSET except that a negative image (for example, black on white) is produced. AND Used when the image is to be transferred over an existing image on the screen. The resulting image Verb Description ────────────────────────────────────────────────────────────────────────── existing image on the screen. The resulting image is the result of a logical AND of the stored image and the screen; points that had the same color in both the existing image and the stored image remain the same color, while those points that do not have the same color in both the existing image and the stored image do not. OR Used to superimpose the image onto an existing image; the stored image does not erase the previous screen contents. The resulting image is the product of a logical OR of the stored image and the screen image. XOR A special mode often used for animation. XOR causes the points on the screen to be inverted where a point exists in the array image. This behavior is exactly like that of the cursor: when an image is placed on the screen against a Verb Description ────────────────────────────────────────────────────────────────────────── an image is placed on the screen against a complex background twice, the background is restored. This allows you to move an object around the screen without erasing the background. ────────────────────────────────────────────────────────────────────────── See Chapter 5, "Graphics," in Programming in BASIC for a detailed description of doing animation with the PUT statement. ■ See Also GET (Graphics), PRESET, PRINT, PSET ■ Example The following example creates a moving white ball that ricochets off the sides of the screen until you press a key to end the program: DEFINT A-Z DIM Ball(84) 'Dimension integer array large enough 'to hold ball. SCREEN 2 '640 pixels by 200 pixels screen resolution. INPUT "Press any key to end; press <ENTER> to start",Test$ CLS CIRCLE (16,16),14 'Draw and paint ball. PAINT (16,16),1 GET (0,0)-(32,32),Ball X = 0 : Y = 0 Xdelta = 2 : Ydelta = 1 DO 'Continue moving in same direction as long as ball is within 'the boundaries of the screen - (0,0) to (640,200). X = X + Xdelta : Y = Y + Ydelta IF INKEY$<>"" THEN END ' Test for key press. 'Change X direction if ball hits left or right edge. IF (X < 1 OR X > 600) THEN Xdelta = -Xdelta BEEP END IF 'Change Y direction if ball hits top or bottom edge. IF (Y < 1 OR Y > 160) THEN Ydelta = -Ydelta BEEP END IF 'Put new image on screen, simultaneously erasing old image. PUT (X,Y),Ball,PSET LOOP END ──────────────────────────────────────────────────────────────────────────── PUT Statement──File I/O ──────────────────────────────────────────────────────────────────────────── ■ Action Writes from a variable or a random-access buffer to a file ■ Syntax PUT «#»filenumber«,«recordnumber»«,variable»» PUT «#»filenumber«,{recordnumber|recordnumber, variable|,variable}» ■ Remarks The following list describes the parts of the PUT statement: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Argument Description ────────────────────────────────────────────────────────────────────────── filenumber The number used in the OPEN statement to open the file. recordnumber For random-mode files, the number of the record to be written. For binary-mode files, the byte position in the file where writing is done. The Argument Description ────────────────────────────────────────────────────────────────────────── position in the file where writing is done. The first record in a file is record 1. If you omit recordnumber, the next record or byte (the one after the last GET or PUT statement, or the one pointed to by the last SEEK) is written to. The largest possible record number is 2^31-1 or 2,147,483,647. variable The variable containing the output to be written to the file. The PUT statement writes as many bytes to the file as there are bytes in the variable. If you use a variable, you do not need to use MKI$, MKL$, MKS$, or MKD$ to convert numeric fields before writing. You may not use a FIELD statement with the file if you use the variable argument. Argument Description ────────────────────────────────────────────────────────────────────────── For random-access files, you can use any variable as long as the length of the variable is less than or equal to the length of the record. Usually, a record variable defined to match the fields in a data record is used. For binary-mode files, you can use any variable. When you use a variable-length string variable, the statement writes as many bytes as there are characters in the string's value. For example, the following two statements write 15 bytes to file number 1: VarString$=STRING$ (15, "X") PUT #1,,VarString$ See the examples below and Chapter 3, "File and Device I/O," in Programming in BASIC, for more Argument Description ────────────────────────────────────────────────────────────────────────── Device I/O," in Programming in BASIC, for more information about using variables rather than FIELD statements for random-access files. A record cannot contain more than 32,767 bytes. ────────────────────────────────────────────────────────────────────────── You can omit the recordnumber, the variable, or both. If you omit only the recordnumber, you must still include the commas: PUT #4,,FileBuffer If you omit both arguments, you do not include the commas: PUT #4 The GET and PUT statements allow fixed-length input and output for BASIC communications files. Be careful using GET and PUT for communications because PUT writes a fixed number of characters and may wait indefinitely if there is a communications failure. ──────────────────────────────────────────────────────────────────────────── NOTE When using a file buffer defined by a FIELD statement, LSET, RSET, PRINT #, PRINT # USING, and WRITE # may be used to put characters in the random-file buffer before executing a PUT statement. In the case of WRITE # , BASIC pads the buffer with spaces up to the carriage return. Any attempt to read or write past the end of the buffer causes an error message that reads FIELD overflow. ──────────────────────────────────────────────────────────────────────────── ■ See Also CVI, CVS, CVL, CVD; GET (File I/O);LSET; MKD$, MKI$, MKL$, MKS$ ■ Example The following example reads names and test scores from the console and stores the names and scores in a random-access file: ' Read a name and a test score from the console. ' Store each name and score as a record in a ' random-access file. ' Define record fields. TYPE TestRecord NameField AS STRING*20 ScoreField AS SINGLE END TYPE ' Open the test data file. DIM FileBuffer AS TestRecord OPEN "TESTDAT.DAT" FOR RANDOM AS #1 LEN=LEN(FileBuffer) ' Read pairs of names and scores from the console. I=0 DO I=I+1 INPUT "Name ? ",FileBuffer.NameField INPUT "Score? ",FileBuffer.ScoreField INPUT "-->More (y/n)? ",Resp$ PUT #1,I,FileBuffer LOOP UNTIL UCASE$(MID$(Resp$,1,1))="N" PRINT I;" records written." CLOSE #1 ──────────────────────────────────────────────────────────────────────────── RANDOMIZE Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Initializes (reseeds) the random-number generator ■ Syntax RANDOMIZE«expression» ■ Remarks If you omit expression, BASIC pauses and asks for a value by printing Random Number Seed (-32768 to 32767)? before executing the RANDOMIZE statement. When you use the argument expression, QuickBASIC uses this value to initialize the random-number generator. If the random-number generator is not reseeded, the RND function returns the same sequence of random numbers each time the program is run. To change the sequence of random numbers every time the program is run, place a RANDOMIZE statement at the beginning of the program and change the argument with each run. A convenient way to initialize the random-number generator is to use the TIMER function. Using TIMER ensures a new series of random numbers each time you use the program. See the example below. ■ See Also RND, TIMER ■ Example The following program simulates rolling two dice. The RANDOMIZE statement initializes the random-number generator so the program produces different numbers each time. ' Use the timer as the seed for the number generator. RANDOMIZE TIMER DO ' Simulate rolling two dice using RND. D1=INT(RND*6)+1 D2=INT(RND*6)+1 ' Report the roll. PRINT "You rolled a";D1;"and a";D2;"for a total of";D1+D2 INPUT "Roll again (Y/N)";Resp$ PRINT LOOP UNTIL UCASE$(MID$(Resp$,1,1))="N" END ■ Output You rolled a 3 and a 5 for a total of 8 Roll again (Y/N)? y You rolled a 4 and a 1 for a total of 5 Roll again (Y/N)? y You rolled a 5 and a 6 for a total of 11 Roll again (Y/N)? n ──────────────────────────────────────────────────────────────────────────── READ Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Reads values from a DATA statement and assigns the values to variables ■ Syntax READ variablelist ■ Remarks A variablelist is a series of valid BASIC variables separated by commas. READ statements are always used with DATA statements. READ assigns DATA values to variables on a one-to-one basis. These variables may be numeric or string. Attempting to read a string value into a numeric variable produces a run-time syntax error. Reading a numeric value into a string variable does not produce an error, but stores the value as a string of numerals. Values read into integer variables are rounded before the value is assigned to the variable. Reading a numeric value too large for a variable produces a run-time error. String values read into fixed-length string variables are truncated if the string is too long. String values shorter than the string-variable length are left-justified and padded with blanks. Only individual elements of a record variable may appear in a READ statement. See example below. A single READ statement may use one or more DATA statements (they will be used in order); several READ statements may use the same DATA statement. If there are more variables in variablelist than there are values in the DATA statement or statements, an error message is printed that reads Out of DATA. If there are fewer variables than the number of elements in the DATA statement or statements, subsequent READ statements begin reading data at the first unread element. If there are no subsequent READ statements, the extra items are ignored. Use the RESTORE statement to reread DATA statements. ■ See Also DATA, RESTORE ■ Example The following fragment shows how a READ statement can be used to read information into the user-defined type named Employee: TYPE Employee FullName AS STRING*35 SocSec AS STRING*9 JobClass AS INTEGER END TYPE DIM ThisEmp AS Employee DATA "Julia Magruder","300-32-3403",3 DATA "Amelie Reeves Troubetzkoy","777-29-3206",7 . . . READ ThisEmp.FullName, ThisEmp.SocSec, ThisEmp.JobClass . . . See also the examples for DATA and RESTORE. ──────────────────────────────────────────────────────────────────────────── REDIM Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Changes the space allocated to an array that has been declared ¢DYNAMIC ■ Syntax REDIM «SHARED» variable(subscripts)«AS type» «,variable(subscripts)«AS typ e»»... ■ Remarks The REDIM statement has the following arguments: Arguments Description ────────────────────────────────────────────────────────────────────────── SHARED The optional SHARED attribute allows a module to share variables with all the procedures in the module; this differs from the SHARED statement, which affects only the variables within a single module. SHARED can only be used in REDIM statements in the module-level code. variable A BASIC variable name. subscripts The dimensions of the array. Multiple dimensions can be declared. The subscript syntax is described below. AS type Declares variable as an elementary or user-defined type. The elementary types are INTEGER, LONG, SINGLE, DOUBLE, and STRING. ────────────────────────────────────────────────────────────────────────── Subscripts in REDIM statements have the following form: «lower TO» upper «, «lower TO» upper»... The TO keyword provides a way to indicate both the lower and the upper bounds of an array's subscripts. The arguments lower and upper are numeric expressions specifying the lowest and highest value for the subscript. See the DIM statement for more information about using the TO keyword. The REDIM statement changes the space allocated to an array that has been declared dynamic. See Chapter 2, "Data Types," for more information about both static and dynamic arrays. When a REDIM statement is compiled, all arrays declared in the statement are treated as dynamic. At run time, when a REDIM statement is executed, the array is deallocated (if it is already allocated) and then reallocated with the new dimensions. Old array-element values are lost because all numeric elements are reset to 0 and all string elements are reset to null strings. Although you may change the size of an array's dimensions with the REDIM statement, you may not change the number of dimensions. For example, the following statements are legal: ' ¢DYNAMIC DIM A(50,50) ERASE A REDIM A(20,15) 'Array A still has two dimensions. However, the following statements are not legal and produce an error message that reads Wrong number of dimensions: ' ¢DYNAMIC DIM A(50,50) ERASE A REDIM A(5,5,5) 'Changed number of dimensions from 'two to three. ■ See Also DIM, ERASE, LBOUND, OPTION BASE, SHARED, UBOUND ■ Example The following program fragment shows one way to use REDIM to allocate an array of records when the records are needed and later to free the memory that the records use: TYPE KeyElement Word AS STRING*20 Count AS INTEGER END TYPE ' Make arrays dynamic. ' ¢DYNAMIC . . . ' Allocate an array of records when you need it. REDIM Keywords(500) AS KeyElement Keywords(99).Word="ERASE" Keywords(99).Count=2 PRINT Keywords(99).Word,Keywords(99).Count . . . ' Free the space taken by Keywords when you're finished. ERASE Keywords . . . END ──────────────────────────────────────────────────────────────────────────── REM Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Allows explanatory remarks to be inserted in a program ■ Syntax 1 REM remark ■ Syntax 2 ' remark ■ Remarks REM statements are not compiled, but they appear exactly as entered when the program is listed. You may branch from a GOTO or GOSUB statement to a REM statement. Execution continues with the first executable statement after the REM statement. A single quotation mark can be used instead of the REM keyword. If the REM keyword follows other statements on a line, it must be separated from the statements by a colon. REM statements are also used to introduce metacommands (see Appendix F, "Metacommands," in Programming in BASIC for more information). ──────────────────────────────────────────────────────────────────────────── NOTE Do not use the single quotation form of the REM statement in a DATA statement because it will be considered valid data. ──────────────────────────────────────────────────────────────────────────── ■ Examples The following two lines are equivalent (notice that the colon is not required with the single quote): FOR I=1 TO 23 : Array(I)=1 : NEXT I : REM Initialize the array. FOR I=1 TO 23 : Array(I)=1 : NEXT I ' Initialize the array. ──────────────────────────────────────────────────────────────────────────── RESET Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Closes all disk files ■ Syntax RESET ■ Remarks The RESET statement closes all open disk files and writes data still in the file buffers to disk. All files must be closed before a disk is removed from its drive. ■ See Also CLOSE, END, SYSTEM ■ Example There are no programming examples for the RESET statement. ──────────────────────────────────────────────────────────────────────────── RESTORE Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Allows DATA statements to be reread from a specified line ■ Syntax RESTORE «{linenumber | linelabel }» ■ Remarks After executing a RESTORE statement without a specified linenumber or linelabel, the next READ statement gets the first item in the first DATA statement in the program. If linenumber or linelabel is specified, the next READ statement gets the first item in the specified DATA statement. If a line is specified, the line number or line label must be in the module-level code. (Note that in the QuickBASIC environment, DATA statements are automatically moved to the module-level code.) ■ See Also DATA, READ ■ Example The RESTORE statement in the following fragment (from a program that generates random bridge hands) allows the program to reread the prompts in the DATA statement so the user can enter new boundary conditions for the different suits: DEFINT A-Z DIM X(13), Param(5,2) DATA Spades, Hearts, Diamonds, Clubs, Points CALL GetParameters(Param()) DO . . . INPUT "Repeat with same parameters"; Ch$ IF UCASE$(Ch$) <> "Y" THEN INPUT "Repeat with new parameters"; Ch$ IF UCASE$(Ch$) <> "Y" THEN EXIT DO ELSE RESTORE CALL GetParameters(Param()) END IF END IF LOOP END SUB GetParameters(Param(2)) STATIC CLS FOR I = 0 TO 4 READ SUIT$ PRINT SUIT$ " (low, high)"; INPUT Param(I,0), Param(I,1) NEXT END SUB ■ Output Spades (low, high)? 5,10 Hearts (low, high)? 5,10 Diamonds (low, high)? 6,8 Clubs (low, high)? 6,8 Points (low, high)? 5,15 . . . Repeat with same parameters? n Repeat with new parameters? y Spades (low, high)? 4,8 Hearts (low, high)? 4,8 . . . ──────────────────────────────────────────────────────────────────────────── RESUME Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Continues program execution after an error-trapping routine has been invoked ■ Syntax RESUME «0» RESUME NEXT RESUME { linenumber | linelabel } ■ Remarks The different forms of the RESUME statement redirect program flow as described in the following list: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Statement Where Execution Resumes ────────────────────────────────────────────────────────────────────────── RESUME «0» At the last statement executed in the module containing the error handler. If an active error handler is found in the module where the error occurs, execution resumes with the statement that caused the error. RESUME NEXT At the statement immediately following the last statement executed in the module containing the error handler. If an active error handler is found in the module where the error occurs, execution resumes with the statement immediately following the statement that caused the error. Statement Where Execution Resumes ────────────────────────────────────────────────────────────────────────── RESUME linenumber At linenumber. RESUME linelabel At linelabel. ────────────────────────────────────────────────────────────────────────── A RESUME statement that is not in an error-handling routine produces the error message RESUME without error. Reaching the end of an error-handling routine without finding RESUME produces the error message No RESUME. The line specified in a RESUME { linenumber | linelabel } statement must be defined at module level. As a rule, avoid using a line number or line label with a RESUME statement. Omitting the line number allows your program to continue no matter where the error occurred. ──────────────────────────────────────────────────────────────────────────── NOTE Programs containing error-handling routines must be compiled with either the /E (On Error) or /X (Resume Next) options when you are compiling from the BC command line. No options are required when compiling in the QuickBASIC environment, or using the Make EXE command from the QuickBASIC Run menu. ──────────────────────────────────────────────────────────────────────────── ■ DIFFERENCES FROM BASICA In BASICA, if an error occurs in a DEF FN function, both RESUME and RESUME NEXT attempt to resume program execution at the line containing the function. ■ See Also ERR, ERL; ERROR; ON ERROR ■ Example This example has an error-handling routine starting at line 900. In BASICA, this routine would cause an error message (No negative arguments) to be printed for I= -1 and -2. The routine would then end. In BASIC, the error-handling routine prints its message when I= -1, then resumes at the beginning of the FOR...NEXT loop with I reset to 4, as seen below. 10 ON ERROR GOTO 900 20 DEF FNTEST(A) = 1 - SQR(A) 30 FOR I = 4 TO -2 STEP -1 40 PRINT I,FNTEST(I) 50 NEXT 60 END 900 'Error-handling routine 910 PRINT "No negative arguments" 920 RESUME NEXT ■ Output 4 -1 3 -.7320509 2 -.4142136 1 0 0 1 -1 No negative arguments 4 -1 3 -.7320509 2 -.4142136 . . . ──────────────────────────────────────────────────────────────────────────── RETURN Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Returns control from a subroutine ■ Syntax RETURN «{linenumber | linelabel }» ■ Remarks Without a line label or number, RETURN continues execution where an event occurred (for event handling) or at the statement following the GOSUB (for subroutine calls). GOSUB and RETURN without a line number can be used anywhere in a program, but the GOSUB and corresponding RETURN must be at the same level. The linenumber or linelabel in the RETURN statement causes an unconditional return from a GOSUB subroutine to the specified line. RETURN with a line label or line number can only return control to a statement in the module-level code. A RETURN statement cannot be used to return control to a calling program from a subprogram defined by SUB. Use EXIT SUB. ──────────────────────────────────────────────────────────────────────────── NOTE BASIC's SUB procedures provide a more well-structured alternative to GOSUB subroutines. ──────────────────────────────────────────────────────────────────────────── ■ See Also EXIT, GOSUB, ON event ■ Example See the example for the GOSUB statement. ──────────────────────────────────────────────────────────────────────────── RIGHT$ Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the rightmost n characters of a string ■ Syntax RIGHT$(stringexpression,n) ■ Remarks The argument stringexpression can be any string variable, string constant, or string expression. If n is equal to the number of characters in the argument stringexpression, then the RIGHT$ function returns stringexpression. If n = 0, RIGHT$ returns the null string (length zero). ■ See Also LEFT$, MID$ ■ Example This program converts names that have been input in the form "Firstname [Middlename] Lastname" to the form "Lastname, Firstname [Middlename]": LINE INPUT "Name: "; Nm$ I = 1 : Sppos = 0 DO WHILE I > 0 I = INSTR(Sppos+1,Nm$," ") 'Get position of next space. IF I > 0 THEN Sppos = I LOOP 'SPPOS now points to the position of the last space. IF Sppos = 0 THEN PRINT Nm$ 'There was just a last name. ELSE 'Everything after last space. Lastname$ = RIGHT$(Nm$,LEN(Nm$)-Sppos) 'Everything before last space. Firstname$ = LEFT$(Nm$,Sppos-1) PRINT Lastname$ ", " Firstname$ END IF END ──────────────────────────────────────────────────────────────────────────── RMDIR Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Removes an existing directory ■ Syntax RMDIR pathname ■ Remarks The pathname is the name of the directory that is to be deleted. The pathname must be a string of less than 128 characters. The directory to be removed must be empty except for the working directory ('.') and the parent directory ('..'); otherwise, one of two error messages is printed, either Path not found or Path/File access error. RMDIR works like the DOS command of the same name; the syntax in BASIC cannot be shortened to RD, as in DOS. ■ See Also CHDIR, MKDIR ■ Example The following example illustrates the use of the RMDIR statement: CHDIR "C:\SALES\TEMP" 'Move to \TEMP subdirectory in \SALES. KILL "*.*" 'Remove all files in \TEMP. CHDIR ".." 'Move back up to \SALES. RMDIR "TEMP" 'Remove \TEMP subdirectory. ──────────────────────────────────────────────────────────────────────────── RND Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns a single-precision random number between 0 and 1 ■ Syntax RND«(n)» ■ Remarks The value of n determines how RND generates the next random number: Argument Number Returned ────────────────────────────────────────────────────────────────────────── n < 0 Always returns the same number for any given n n > 0 or n omitted Returns the next random number in the sequence n = 0 Returns the last number generated ────────────────────────────────────────────────────────────────────────── Even if n>0, the same sequence of random numbers is generated each time the program is run unless you initialize the random-number generator each time you run the program. (See the RANDOMIZE statement entry for more information about initializing the random-number generator.) To produce random integers in a given range, use the formula INT ((upperbound - lowerbound + 1)*RND + lowerbound) where upperbound is the highest number in the range, and lowerbound is the lowest number in the range. ■ Example See the examples for the RANDOMIZE and TYPE statements. ──────────────────────────────────────────────────────────────────────────── RSET Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Moves data from memory to a random-access file buffer (in preparation for a PUT statement) or right-justifies the value of a string in a string variable ■ Syntax RSET stringvariable=stringexpression ■ Remarks The stringvariable is usually a random-access file field defined in a FIELD statement, although it can be any string variable. The stringexpression is the value assigned to the variable. If stringexpression requires fewer bytes than were defined for stringvariable in the FIELD statement, the RSET statement right-justifies the string in the field (LSET left-justifies the string). Spaces are used to pad the extra positions. If the string is too long for the field, both LSET and RSET truncate characters from the right. Numeric values must be converted to strings before they are justified with the RSET or LSET statements. The RSET statement can be used with string variables unrelated to FIELD statements. When used with a fixed-length string variable, the value is right-justified and left-padded with blanks. When RSET is used with a variable-length string, the string is treated as a fixed field. The length of the field is the length of the value the variable had before the RSET statement. See the example below. ■ See Also FIELD; LSET; MKD$, MKI$, MKL$, MKS$; PUT ■ Example The following example shows the effects of using RSET to assign values to fixed- and variable-length strings: DIM TmpStr2 AS STRING * 10 PRINT " 1 2 3" PRINT "123456789012345678901234567890" ' Use RSET on null variable-length string of length. ' Nothing prints because TmpStr$ is a zero-length field. TmpStr$ = "" RSET TmpStr$ = "Another" PRINT TmpStr$ ' Use RSET on variable-length string with a value. TmpStr$ = SPACE$(20) RSET TmpStr$ = "Another" PRINT TmpStr$ ' Use RSET on fixed-length string of length 10. RSET TmpStr2 = "Another" PRINT TmpStr2 ■ Output 1 2 3 123456789012345678901234567890 Another Another ──────────────────────────────────────────────────────────────────────────── RTRIM$ Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns a string with trailing (right-hand) spaces removed ■ Syntax RTRIM$(stringexpression) ■ Remarks The stringexpression can be any string expression. The RTRIM$ function works with both fixed- and variable-length string variables. ■ See Also LTRIM$ ■ Example The example shows the effects of the RTRIM$ function on fixed- and variable-length strings. See also the example for the LTRIM$ function. DIM FixStr AS STRING * 10 PRINT " 1 2" PRINT "12345678901234567890" FixStr = "Twine" PRINT FixStr + "*" PRINT RTRIM$(FixStr) + "*" VarStr$ = "Braided" + SPACE$(10) PRINT VarStr$ + "*" PRINT RTRIM$(VarStr$) + "*" ■ Output 1 2 12345678901234567890 Twine * Twine* Braided * Braided* ──────────────────────────────────────────────────────────────────────────── RUN Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Restarts the program currently in memory or executes a specified program ■ Syntax RUN «{ linenumber | filespec }» ■ Remarks The RUN statement accepts the following arguments: Argument Description ────────────────────────────────────────────────────────────────────────── linenumber The numeric label of the line where execution begins. If no argument is given, execution begins at the first executable line of code. filespec A string expression naming the program file to load and run. The current program is cleared from memory before the specified program is loaded. ────────────────────────────────────────────────────────────────────────── The line where execution begins must be in the module-level code. Therefore, a RUN statement in a SUB or FUNCTION procedure must point to labels at module level. If no line label is given, execution always starts with the first executable line of the program's main module. During compilation, if linenumber cannot be found in the module-level code, compilation halts and the error message Label not defined appears. Program lines can have line numbers or alphanumeric labels, such as OpenWindow:. If an alphanumeric label is the target of a RUN statement, execution halts, and the error message Type mismatch appears. Note that the QuickBASIC syntax checker does not warn you if you give the RUN statement an alphanumeric label instead of a line number. You do not need to specify the file name extension in filespec. The .BAS extension is assumed in the QuickBASIC environment, and the .EXE extension is assumed when running compiled, stand-alone programs. If the program you wish to run has a different extension, you must give the extension. If the program name has no extension, the file name given must end with a period. For example, RUN "CATCHALL" would execute CATCHALL.EXE from a BC-compiled program, and CATCHALL.BAS from within QuickBASIC. Programs running within the QuickBASIC environment must call only QuickBASIC program files. The file is loaded and run as if it were a QuickBASIC program; if it is not in the QuickBASIC program format, execution halts. The error message that appears varies, depending on the file's contents. Likewise, programs compiled with BC must not invoke QuickBASIC source files, as these run only within the QuickBASIC environment. An executable file need not have been written in QuickBASIC. Any executable file may be run. When running a program under QuickBASIC, if an executable file matching the file name in filespec cannot be found, the error message File not found appears, and control returns to QuickBASIC. When running a program compiled by BC, the error message File not found in module programname appears, and control returns to DOS. When the invoked program completes execution, control does not return to the invoking program. If the invoking program ran outside QuickBASIC, control returns to DOS. If the invoking program ran under QuickBASIC, control returns to QuickBASIC. If you edit a QuickBASIC program containing a RUN statement, then run the program before saving the changes, QuickBASIC asks if you wish to save the new version of the program before RUN clears it from memory. RUN closes all files and clears program memory before loading the designated program.The BC compiler does not support the R option from BASICA. (This option keeps all open data files open.) If you want to run a different program, but leave open files open, use the CHAIN statement. ■ See Also CHAIN ■ Examples The following example shows how RUN linenumber resets all numeric variables to 0. As the line number following RUN increases in lines 60, 70, 80, and 90, the variables in the earlier statements lose their assigned values. 10 A = 9 20 B = 7 30 C = 5 40 D = 4 50 PRINT A,B,C,D 60 IF A = 0 THEN 70 ELSE RUN 20 70 IF B = 0 THEN 80 ELSE RUN 30 80 IF C = 0 THEN 90 ELSE RUN 40 90 IF D = 0 THEN END ELSE RUN 50 ■ Output 9 7 5 4 0 7 5 4 0 0 5 4 0 0 0 4 0 0 0 0 ──────────────────────────────────────────────────────────────────────────── SADD Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the address of the specified string expression ■ Syntax SADD(stringvariable) ■ Remarks The SADD function returns the address of a string as an offset (near pointer) from the current data segment. The offset is a two-byte integer. SADD is most often used in mixed-language programming. The argument may be a simple string variable or a single element of a string array. You may not use fixed-length string arguments. Use this function with care because strings can move in the BASIC string space (storage area) at any time. SADD works only with string variables stored in DGROUP. ──────────────────────────────────────────────────────────────────────────── NOTE Do not add characters to the beginning or end of a string passed using SADD and LEN. Adding characters may produce a run-time error. ──────────────────────────────────────────────────────────────────────────── ■ See Also CALL, CALLS (Non-BASIC); DECLARE (Non-BASIC); FRE; PEEK; POKE; VARPTR; VARPTR$; VARSEG ■ Example The following example uses SADD and LEN to pass a string to a function written in C. The C function returns the ASCII value of a character at a given position in the string. The C program would be separately compiled and stored in a Quick library or explicitly linked to form an .EXE file. Note that BYVAL is the default for C. ' Pass a string to a C function using SADD and LEN. DEFINT A-Z ' Declare the function; DECLARE FUNCTION MyAsc CDECL (BYVAL A%, BYVAL B%, BYVAL C%) A$="abcdefghijklmnopqrstuvwxyz" PRINT "Enter a character position (1-26). Enter 0 to Quit." DO ' Get a character position. INPUT N ' End if the position is less than zero. IF N<=0 THEN EXIT DO ' Call C function; the function returns the ASCII code of the ' character at position N in A$. AscValue=MyAsc(SADD(A$),LEN(A$),N) PRINT "ASCII value: ";AscValue;"Character: ";CHR$(AscValue) LOOP END /* C function to return the ASCII value of the character at position pos in string c of length len. */ int far myasc(c,len,pos) char near *c; int len, pos; { if(pos>len) return(c[--len]);/* Avoid indexing off end. */ else if (pos<1) return(c[0]);/* Avoid indexing off start. */ else return(c[--pos]);/* pos is good. Return the character at pos-1 because C arrays (strings) are zero-indexed. */ } ■ Output Enter a character position (1-26). Enter -1 to Quit. ? 24 ASCII value: 120 Character: x ? -1 ──────────────────────────────────────────────────────────────────────────── SCREEN Function ──────────────────────────────────────────────────────────────────────────── ■ Action Reads a character's ASCII value or its color from a specified screen location ■ Syntax SCREEN(row,column«,colorflag») ■ Remarks The following list describes the SCREEN function's arguments: Argument Description ────────────────────────────────────────────────────────────────────────── row The row number of the screen location. The row is a numeric expression that evaluates to an unsigned integer. column The column number of the screen location. The column is a numeric expression that evaluates to an unsigned integer. colorflag A numeric expression. When colorflag is nonzero, SCREEN returns the number of the color at the screen location. If the colorflag is zero or absent, the ASCII code of the character at the location is returned as an integer. ────────────────────────────────────────────────────────────────────────── ■ Examples If the character at (10,10) in the following examples is A, then the function would return 65, the ASCII code for A: X=SCREEN(10,10) The following example returns the color attribute of the character in the upper-left corner of the screen: X=SCREEN(1,1,1) ──────────────────────────────────────────────────────────────────────────── SCREEN Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Sets the specifications for the display screen ■ Syntax SCREEN «mode» «,«colorswitch» »«,«apage» »«,«vpage»» ■ Remarks The SCREEN statement selects a screen mode appropriate for a particular combination of display and adapter. Later sections describe the available modes for specific adapters. The following list describes the arguments of the SCREEN statement: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Argument Description ────────────────────────────────────────────────────────────────────────── mode An integer constant or expression indicating the screen mode. The valid modes are described below for each of the supported adapters. colorswitch Determines whether color is displayed on composite monitors. The colorswitch is a numeric expression in the range 0-255. When it is true (nonzero), color is disabled and only black-and-white images are displayed. When colorswitch is false (zero), images are in color. The colorswitch argument's meaning is inverted in screen mode 0. In screen modes 2 and up, colorswitch is ignored. apage A numeric expression that is the number of the screen page that text output or graphics commands write to. Tables below indicate valid values for apage with various adapters. Argument Description ────────────────────────────────────────────────────────────────────────── apage with various adapters. vpage A numeric expression that is the number of the screen page being displayed. Tables below indicate valid values for vpage with various adapters. ────────────────────────────────────────────────────────────────────────── The next two subsections summarize the screen modes and discuss the modes available with specific combinations of adapters and displays. The final subsection summarizes attributes and colors. SUMMARY OF SCREEN MODES The following paragraphs briefly summarize each of the screen modes. The color adapters referred to are the IBM Color Graphics Adapter (CGA), the IBM Enhanced Graphics Adapter (EGA), the IBM Video Graphics Array (VGA) and the IBM Multicolor Graphics Array (MCGA). The Hercules(R) Graphics Card, Graphics Card Plus and InColor(R) adapters are supported, but only with monochrome monitors. The next subsection supplies detailed information about the effects of a screen mode when used with a specific combination of display and adapter. ──────────────────────────────────────────────────────────────────────────── NOTE Many screen modes support more than one combination of rows and columns on the screen. See the entry for the WIDTH statement for more information about changing the number of rows and columns on the display. ──────────────────────────────────────────────────────────────────────────── Screen 0 ■ Text mode only ■ Either 40 x 25, 40 x 43, 40 x 50, 80 x 25, 80 x 43, or 80 x 50 text format with character-box size of 8 x 8 (8 x 14, 9 x 14, or 9 x 16 with EGA or VGA) ■ Assignment of 16 colors to 2 attributes ■ Assignment of 16 colors to any of 16 attributes (with CGA or EGA) ■ Assignment of 64 colors to any of 16 attributes (with EGA or VGA) Screen 1 ■ 320 x 200 pixel medium-resolution graphics ■ 40 x 25 text format with character-box size of 8 x 8 ■ Assignment of 16 colors to 4 attributes with EGA or VGA ■ Supports CGA, EGA, VGA, and MCGA Screen 2 ■ 640 x 200 pixel high-resolution graphics ■ 80 x 25 text format with character-box size of 8 x 8 ■ Assignment of 16 colors to 2 attributes with EGA or VGA ■ Supports CGA, EGA, VGA, and MCGA Screen 3 ■ Hercules adapter required ■ Monochrome monitor only ■ 720 x 348 pixel resolution, monochrome ■ 80 x 25 text format with character-box size of 9 x 14; bottom two scan lines of 25th row not visible ■ Two screen pages (one only if a second display adapter is installed) ■ PALETTE statement not supported ──────────────────────────────────────────────────────────────────────────── NOTE The Hercules driver (MSHERC.COM) must be loaded for the Hercules card to function. This file is supplied with QuickBASIC. Type MSHERC before running QuickBASIC. If a compatible color adapter is also installed (eg, CGA), type MSHERC /H instead. This limits the Hercules card to one screen page but permits normal operation of the color adapter. If the Hercules driver is not loaded, the Hercules card operates like an IBM Monochrome Display Adapter (MDA). ──────────────────────────────────────────────────────────────────────────── Screen 4 ■ 640 x 400 pixel high-resolution graphics ■ 80 x 25 text format with character-box size of 8 x 16 ■ Assignment of 1 of 16 colors as the foreground color (selected by the COLOR statement); background fixed at black ■ Supports Olivetti(R) Personal Computers, models M24, M240, M28, M280, M380, M380/C, and M380/T, and AT&T(R) Personal Computers 6300 series ──────────────────────────────────────────────────────────────────────────── WARNING Olivetti personal computers running in DOS-compatibility mode under Microsoft Operating System/2 should avoid this screen mode. ──────────────────────────────────────────────────────────────────────────── Screen 7 ■ 320 x 200 pixel medium-resolution graphics ■ 40 x 25 text format with character-box size of 8 x 8 ■ Multiple screen pages ■ Assignment of 16 colors to any of 16 attributes ■ EGA or VGA required Screen 8 ■ 640 x 200 pixel high-resolution graphics ■ 80 x 25 text format with character-box size of 8 x 8 ■ Multiple screen pages ■ Assignment of 16 colors to any of 16 attributes ■ EGA or VGA required Screen 9 ■ 640 x 350 pixel enhanced-resolution graphics ■ 80 x 25 or 80 x 43 text format with character-box size of 8 x 14 or 8 x 8 ■ Assignment of either 64 colors to 16 attributes (more than 64K of EGA or VGA memory) or 16 colors to 4 attributes (64K of EGA or VGA memory) ■ Multiple screen pages ■ EGA or VGA required Screen 10 ■ Monochrome only ■ 640 x 350 pixel enhanced-resolution graphics ■ 80 x 25 or 80 x 43 text format with character-box size of 8 x 14 or 8 x 8 ■ Multiple screen pages ■ Assignment of up to nine pseudocolors to 4 attributes (refer to Tables R.9 and R.10 in the next section) ■ EGA or VGA required Screen 11 ■ 640 x 480 pixel very high-resolution graphics ■ 80 x 30 or 80 x 60 text format with character-box size of 8 x 16 or 8 x 8 ■ Assignment of up to 256K colors to 2 attributes ■ VGA or MCGA required Screen 12 ■ 640 x 480 pixel very-high-resolution graphics ■ 80 x 30 or 80 x 60 text format with character-box size of 8 x 16 or 8 x 8 ■ Assignment of up to 256K colors to 16 attributes ■ VGA required Screen 13 ■ 320 x 200 pixel medium-resolution graphics ■ 40 x 25 text format with character-box size of 8 x 8 ■ Assignment of up to 256K colors to up to 256 attributes ■ VGA or MCGA required SCREEN MODES, ADAPTERS, AND DISPLAYS This section describes the screen modes for specific combinations of adapters and displays. The IBM Monochrome Display and Printer Adapter (MDPA) can be used only with a monochrome display. Only screen mode 0, text mode, can be used with the MDPA. Table R.6 summarizes the effect of using screen mode 0 with an MDPA. Table R.6 MDPA Screen Modes Screen Rows and Mode Columns Attributes Colors Resolution Pages ────────────────────────────────────────────────────────────────────────── 0 80x25 16 3 720x350 1 ────────────────────────────────────────────────────────────────────────── Table R.7 summarizes the screen modes available with Hercules adapters. Table R.7 Hercules Screen Modes Screen Rows and Mode Columns Attributes Colors Resolution Pages ────────────────────────────────────────────────────────────────────────── 0 80x25 16 1 720x348 2 3 80x25 16 1 720x348 2 ────────────────────────────────────────────────────────────────────────── The IBM Color Graphics Adapter (CGA) and Color Display are typically paired. This combination permits running text-mode programs and both medium-resolution and high-resolution graphics programs. Table R.8 summarizes the screen modes available with the CGA. Table R.8 CGA Screen Modes Screen Rows and Mode Columns Colors Resolution Pages ────────────────────────────────────────────────────────────────────────── 0 40x25 16 320x200 8 80x25 16 640x200 4 1 40x25 4 320x200 1 2 80x25 2 640x200 1 ────────────────────────────────────────────────────────────────────────── The IBM Enhanced Graphics Adapter (EGA) may be used with either the IBM Color Display or the Enhanced Color Display. In screen modes 0, 1, 2, 7, and 8, these pairings produce similar results, except for the following possible differences: 1. The border color cannot be set on an Enhanced Color Display when it is in 640 x 350 text mode. 2. The text quality is better on the Enhanced Color Display (an 8 x 14 character box for Enhanced Color Display versus an 8 x 8 character box for Color Display). Screen mode 9 takes full advantage of the capabilities of the Enhanced Color Display and provides for the highest resolution possible for the EGA/Enhanced Color Display configuration. Programs written for this mode will not work for any other hardware configuration except the VGA. Table R.9 summarizes the screen modes that can be used with an EGA. Table R.9 EGA Screen Modes ╓┌─┌───────┌─────────┌────────┌──────────┌───────┌──────────┌─────────┌──────╖ Screen Rows and Page Mode Columns Display Attributes Colors Resolution Size Pages ────────────────────────────────────────────────────────────────────────── 0 40x25 C 16 16 320x200 N/A 8 40x25 E 16 64 320x350 N/A 8 40x43 E 16 64 320x350 N/A 8 80x25 C 16 16 640x200 N/A 8 80x25 E 16 64 640x350 N/A 8 80x25 C 16 16 640x200 N/A 8 80x25 M 16 3 720x350 N/A 8 80x43 E 16 64 640x350 N/A 4 80x43 M 16 3 720x350 N/A 4 Screen Rows and Page Mode Columns Display Attributes Colors Resolution Size Pages ────────────────────────────────────────────────────────────────────────── 80x43 M 16 3 720x350 N/A 4 1 40x25 N/A 4 16 320x200 16K 1 2 80x25 N/A 2 16 640x200 16K 1 7 40x25 N/A 16 16 320x200 32K 8 80x25 N/A 16 16 640x200 64K 9 80x25 E 4 64 640x350 64K 1 80x43 E 4 64 640x350 64K 1 80x25 E 16 64 640x350 128K 80x43 E 16 64 640x350 128K 10 80x25 M 4 9 640x350 64K 80x43 M 4 9 640x350 64K ────────────────────────────────────────────────────────────────────────── Only the EGA and VGA can be paired with the IBM Monochrome Display to run programs in screen mode 10. This mode can be used to display monochrome graphics at a very high resolution. The following two tables summarize the default attributes and colors for screen mode 10 used with a monochrome display. Table R.10 Default Attributes: Screen Mode 10, Monochrome Display Attribute Displayed Value Pseudocolor ────────────────────────────────────────────────────────────────────────── 0 Off 1 On, normal intensity 2 Blink 3 On, high intensity ────────────────────────────────────────────────────────────────────────── Table R.11 Color Values: Screen Mode 10, Monochrome Display Color Displayed Value Pseudocolor ────────────────────────────────────────────────────────────────────────── 0 Off 1 Blink, off to on 2 Blink, off to high intensity 3 Blink, on to off 4 On 5 Blink, on to high intensity 6 Blink, high intensity to off 7 Blink, high intensity to on 8 High intensity ────────────────────────────────────────────────────────────────────────── The IBM Video Graphics Array (VGA) adapter offers significantly enhanced text and graphics in all screen modes. Table R.12 summarizes the modes available with the VGA. Table R.12 VGA Screen Modes ╓┌─┌──────────┌─────────┌──────────┌─────────┌──────────┌─────────┌──────────╖ Rows and Page Mode Columns Attributes Colors Resolution Size Pages ────────────────────────────────────────────────────────────────────────── 0 40x25 16 64 360x400 N/A 8 Rows and Page Mode Columns Attributes Colors Resolution Size Pages ────────────────────────────────────────────────────────────────────────── 0 40x25 16 64 360x400 N/A 8 40x43 16 64 320x350 N/A 8 40x50 16 64 320x400 N/A 4 80x25 16 64 720x400 N/A 8 80x43 16 64 640x350 N/A 4 80x43 16 3 720x350 N/A 4 80x50 16 64 640x400 N/A 4 80x50 16 3 720x400 N/A 4 1 40x25 4 16 320x200 16K 1 2 80x25 2 16 640x200 16K 1 7 40x25 16 16 320x200 32K 8 80x25 16 16 640x200 64K 9 80x25 16 64 640x350 128K 80x43 16 64 640x350 128K 10 80x25 4 9 640x350 64K 80x43 4 9 640x350 64K 11 80x30 2 256K 640x480 64K 1 80x60 2 256K 640x480 64K 1 Rows and Page Mode Columns Attributes Colors Resolution Size Pages ────────────────────────────────────────────────────────────────────────── 80x60 2 256K 640x480 64K 1 12 80x30 16 256K 640x480 256K 1 80x60 16 256K 640x480 256K 1 13 40x25 256 256K 320x200 64K 1 ────────────────────────────────────────────────────────────────────────── See the PALETTE statement for a description of how the VGA calculates color values. The IBM Multicolor Graphics Array (MCGA) combines the modes of the CGA with the very high resolution and 256K color modes of the VGA to provide enhanced text and graphics in all modes. Table R.13 summarizes the modes supported by the MCGA. Table R.13 MCGA Screen Modes Rows and Page Mode Columns Attributes Colors Resolution Size Pages ────────────────────────────────────────────────────────────────────────── 0 40x25 16 N/A 320x400 N/A 8 80x25 16 N/A 640x400 N/A 8 1 40x25 4 N/A 320x200 16K 1 2 80x25 2 N/A 640x200 16K 1 11 80x30 2 256K 640x480 64K 1 80x60 2 256K 640x480 64K 1 13 40x25 256 256K 320x200 64K 1 ────────────────────────────────────────────────────────────────────────── The MCGA uses the same color values as the VGA. See the PALETTE statement for a description of how the MCGA calculates color values. ATTRIBUTES AND COLORS For various screen modes and display hardware configurations, different attribute and color settings exist. (See the PALETTE statement for a discussion of attribute and color number.) The majority of these attribute and color configurations are summarized in Tables R.14-R.16. Table R.14 Default Attributes and Colors for Screen Modes 1 and 9 Attributes Color Display Monochrome Display Number Color Number Color ────────────────────────────────────────────────────────────────────────── 0 0 Black 0 Off 1 11 Light cyan 2 High intensity 2 13 Light magenta 2 High intensity 3 15 High-intensity 0 Off white ────────────────────────────────────────────────────────────────────────── Table R.15 Default Attributes and Colors for Screen Modes 2 and 11 Attributes Color Display Monochrome Display Number Color NumberColor ────────────────────────────────────────────────────────────────────────── 0 0 Black 0 Off 1 15 High-intensity 0 Off white ────────────────────────────────────────────────────────────────────────── Table R.16 Default Attributes and Colors for Screen Modes 0, 7, 8, 9, 12, and 13 ╓┌─┌──────────────┌────────────┌───────────────┌─────────────┌───────────────╖ Attributes Color Display Monochrome Display Number Color Number Color ────────────────────────────────────────────────────────────────────────── 0 0 Black 0 Off 1 1 Blue Underlined 2 2 Green 1 On 3 3 Cyan 1 On 4 4 Red 1 On 5 5 Magenta 1 On 6 6 Brown 1 On 7 7 White 1 On 8 8 Gray 0 Off 9 9 Light blue High intensity Underlined 10 10 Light green 2 High intensity 11 11 Light cyan 2 High intensity Attributes Color Display Monochrome Display Number Color Number Color ────────────────────────────────────────────────────────────────────────── 11 11 Light cyan 2 High intensity 12 12 Light red 2 High intensity 13 13 Light magenta 2 High intensity 14 14 Yellow 2 High intensity 15 15 High-intensity 0 Off white ────────────────────────────────────────────────────────────────────────── ■ Example See the LINE, CIRCLE, and DRAW statements for examples of the SCREEN statement. ──────────────────────────────────────────────────────────────────────────── SEEK Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the current file position ■ Syntax SEEK(filenumber) ■ Remarks The filenumber is the number used in the OPEN statement to open the file. SEEK returns a value in the range 1 to 2,147,483,647 (equivalent to 2^31-1). SEEK returns the number of the next record read or written when used on RANDOM mode files. For files opened in BINARY, OUTPUT, APPEND, or INPUT mode, SEEK returns the byte position in the file where the next operation is to take place. The first byte in a file is 1. When used on a device that does not support SEEK, the function returns zero. The BASIC devices (SCRN:, CONS:, KYBD:, COMn:, and LPTn:) do not support SEEK. See Chapter 3, "File and Device I/O," in Programming in BASIC for more information. ■ See Also GET (File I/O), OPEN, PUT (File I/O), SEEK Statement ■ Example The following code fragment prints a message indicating whether the last read or write was done in the first, second, or final third of the file: SELECT CASE (SEEK(1)) CASE IS < .333*LOF(1) PRINT "In first third of file." CASE .333*LOF(1) TO .667*LOF(1) PRINT "In second third of file." CASE IS >= .667*LOF(1) PRINT "In last third of file." CASE ELSE END SELECT ──────────────────────────────────────────────────────────────────────────── SEEK Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Sets the position in a file for the next read or write ■ Syntax SEEK «#»filenumber,position ■ Remarks The filenumber is an integer number used in the OPEN statement to open the file. The position is a numeric expression indicating where the next read or write is done. The position must be in the range 1 to 2,147,483,647 (equivalent to 2^31-1). For files opened in RANDOM mode, position is the number of a record in the file. For files opened in BINARY, INPUT, OUTPUT, or APPEND modes, position is the number of a byte from the beginning of the file. The first byte in a file is 1. After a SEEK, the next file I/O operation starts at that byte in the file. ──────────────────────────────────────────────────────────────────────────── NOTE Record numbers on a GET or PUT override the file positioning done by SEEK. ──────────────────────────────────────────────────────────────────────────── Performing a file write after doing a SEEK beyond the end of a file extends the file. A SEEK to a negative or zero position produces an error message that reads Bad record number. When used on a device that does not support SEEK, BASIC ignores SEEK and leaves the file position unchanged. The BASIC devices (SCRN:, CONS:, KYBD:, COMn:, and LPTn:) do not support SEEK. See Chapter 3, "File and Device I/O," in Programming in BASIC for more information. ■ See Also GET (File I/O), OPEN, PUT (File I/O), SEEK Function ■ Example The following code fragment uses a combination of the SEEK function and SEEK statement to back up the file position and rewrite a record if a variable is true (nonzero): CONST FALSE=0, TRUE=NOT FALSE . . . IF ReWriteFlag = TRUE THEN ' Back up file by the length of the record variable that ' is used to write to the file. SEEK #1, SEEK(1)-LEN(RecordVar) PUT #1,,RecordVar END IF ──────────────────────────────────────────────────────────────────────────── SELECT CASE Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Executes one of several statement blocks depending on the value of an expression ■ Syntax SELECT CASE testexpression CASE expressionlist1 «statementblock-1» «CASE expressionlist2 «statementblock-2»» . . . «CASE ELSE «statementblock-n»» END SELECT ■ Remarks The following list describes the parts of the SELECT CASE statement: Argument Description ────────────────────────────────────────────────────────────────────────── testexpression Any numeric or string expression. statementblock-1, The elements statementblock-1 to statementblock-n statementblock-2, consist of any number of statements on one or statementblock-n more lines. expressionlist1, These elements can have any of the three expressionlist2 following forms: expression«,expression...» expression TO expression IS relational-operator expression ────────────────────────────────────────────────────────────────────────── The following list describes the parts of an expressionlist: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Argument Description ────────────────────────────────────────────────────────────────────────── expression Any numeric or string expression. The type of the expression must match the type of the expression being tested. Argument Description ────────────────────────────────────────────────────────────────────────── relational-operator Any of the following operators: Symbol Meaning < Less than <= Less than or equal to > Greater than >= Greater than or equal to <> Not equal = Equal ────────────────────────────────────────────────────────────────────────── Argument Description ────────────────────────────────────────────────────────────────────────── If the testexpression matches the expressionlist associated with a CASE clause, then the statement block following that CASE clause is executed up to the next CASE clause or, for the last one, up to END SELECT. Control then passes to the statement following END SELECT. If you use the TO keyword to indicate a range of values, the smaller value must appear first. For example, the statements associated with the line CASE -1 TO -5 are not executed if the testexpression is -4. The line should be written as CASE -5 TO -1. You may use a relational operator only if the IS keyword appears. If CASE ELSE is used, its associated statements are executed only if the testexpression does not match any of the other CASE selections. It is a good idea to have a CASE ELSE statement in your SELECT CASE block to handle unforeseen testexpression values. When there is no CASE ELSE statement and no expression listed in the CASE clauses matches testexpression, program execution continues normally. No error occurs. You may use multiple expressions or ranges in each CASE clause. For example, the following line is valid: CASE 1 TO 4, 7 TO 9, 11, 13, IS > MaxNumber% You may also specify ranges and multiple expressions for strings: CASE "everything", "nuts" TO "soup", TestItem$ CASE matches strings that are exactly equal to everything, the current value of TestItem$, or that fall between nuts and soup in alphabetical order. Strings are evaluated according to the ASCII values of their characters. Lowercase letters have larger ASCII values than uppercase letters, so nuts > Nuts > NUTS If an expression appears in more than one CASE clause, only the statements associated with the first appearance of the expression are executed. SELECT CASE statements may be nested. Each SELECT CASE statement must have a matching END SELECT statement. ■ Example In the following program, the SELECT CASE statement is used to take different actions based on the input value: ' Program demonstrates various forms of CASE items INPUT "Enter acceptable level of risk (1-10): ", Total SELECT CASE Total CASE IS >= 10 PRINT "Maximum risk and potential return" PRINT "Choose stock investment plan" CASE 6 TO 9 PRINT "High risk and potential return" PRINT "Choose corporate bonds" CASE 2 TO 5 PRINT "Moderate risk and return" PRINT "Choose mutual fund" CASE 1 PRINT "No risk, low return" PRINT "Choose IRA" CASE ELSE PRINT "RESPONSE OUT OF RANGE" END SELECT ■ Output Enter acceptable level of risk (1-10): 10 Maximum risk and potential return Choose stock investment plan Enter acceptable level of risk (1-10): 0 RESPONSE OUT OF RANGE ──────────────────────────────────────────────────────────────────────────── SETMEM Function ──────────────────────────────────────────────────────────────────────────── ■ Action Changes the amount of memory used by the far heap──the area where far objects and internal tables are stored ■ Syntax SETMEM(numeric-expression) ■ Remarks The SETMEM function increases or decreases the far heap by the number of bytes indicated by numeric-expression. If the numeric-expression is negative, SETMEM decreases the far heap by the indicated number of bytes. When the numeric-expression is positive, SETMEM attempts to increase the far heap space by the number of bytes. SETMEM returns the total number of bytes in the far heap. If the numeric-expression is zero, SETMEM returns the current size of the far heap. If SETMEM cannot change the far heap by the requested number of bytes, it reallocates as many bytes as possible. SETMEM can be used in mixed-language programming to decrease the far heap space so procedures in other languages can dynamically allocate far memory. A first call to SETMEM trying to increase the far heap has no effect because BASIC allocates as much memory as possible to the far heap when a program starts. ■ Example The following program outlines how SETMEM could be used to free memory for a C function that uses malloc to get dynamic memory. The C function is separately compiled and then put in a Quick library or linked to the BASIC program. The C function is compiled using the large memory model, so calls to malloc use the far space freed by the BASIC program. DEFINT A-Z DECLARE SUB CFunc CDECL (BYVAL X AS INTEGER) ' Decrease the size of the far heap so CFunc can use ' malloc to get dynamic memory. BeforeCall=SETMEM(-2048) ' Call the C function. CFunc(1024%) ' Return the memory to the far heap; use a larger value so ' all space goes back into the heap. AfterCall=SETMEM(3500) IF AfterCall <= BeforeCall THEN PRINT "Memory not reallocated." END void far cfunc(bytes) int bytes; { char *malloc(); char *workspace; /* Allocate working memory using amount BASIC freed. */ workspace=malloc((unsigned) bytes); /* Working space would be used here. */ /* Free memory before returning to BASIC. */ free(workspace); } ──────────────────────────────────────────────────────────────────────────── SGN Function ──────────────────────────────────────────────────────────────────────────── ■ Action Indicates the sign of a numeric expression ■ Syntax SGN(numeric-expression) ■ Remarks The SGN function returns a value depending on the sign of its argument: If numeric-expression > 0, then SGN(numeric-expression) returns 1. If numeric-expression = 0, then SGN(numeric-expression) returns 0. If numeric-expression < 0, then SGN(numeric-expression) returns -1. ■ Example The following program calculates and prints the solution for a quadratic (or for a second-degree) equation. The program uses the sign of a test expression to determine how to calculate the solution. CONST NoRealSoln=-1, OneSoln=0, TwoSolns=1 ' Input coefficients of quadratic equation: ' ax^2 + bx + c = 0. INPUT;"a = ", A INPUT;", b = ",B INPUT ", c = ",C Test = B^2 - 4*A*C SELECT CASE SGN(Test) CASE NoRealSoln PRINT "This equation has no real-number solutions." CASE OneSoln PRINT "This equation has one solution: "; PRINT -B/(2*A) CASE TwoSolns PRINT "This equation has two solutions: "; PRINT (-B + SQR(Test))/(2*A) " and "; PRINT (-B - SQR(Test))/(2*A) END SELECT ■ Output a = 12, b = -5, c = -2 This equation has two solutions: .6666667 -.25 ──────────────────────────────────────────────────────────────────────────── SHARED Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Gives a SUB or FUNCTION procedure access to variables declared at the module level without passing them as parameters ■ Syntax SHARED variable «AS type» «, variable «AS type»»... ■ Remarks The argument variable is either an array name followed by () or a variable name. The AS clause can be used to indicate the variable's type. The type argument can be INTEGER, LONG, SINGLE, DOUBLE, STRING, fixed-length string (STRING*length), or a user-defined type. By using either the SHARED statement in a SUB or FUNCTION procedure, or the SHARED attribute with COMMON or DIM in the module-level code, you can use variables in a procedure without passing them as parameters. The SHARED attribute shares variables among all procedures in a module, while the SHARED statement shares variables between a single procedure and the module-level code. ──────────────────────────────────────────────────────────────────────────── NOTE The SHARED statement only shares variables within a single compiled module. It does not share variables with programs in the Quick library or with procedures compiled separately and linked to the program. The SHARED statement only shares variables between the module-level code and a SUB or FUNCTION in the same module. ──────────────────────────────────────────────────────────────────────────── The SHARED statement can appear only in a SUB or FUNCTION. For more information see Chapter 2, "SUB and FUNCTION Procedures," in Programming in BASIC and Chapter 4, "Programs and Modules," in this manual. ■ See Also COMMON, DIM, SUB ■ Example The following program calls a subprogram named CONVERT that converts the input decimal number to its string representation in the given new base. The string N$ is shared by the subprogram and the main program. DEFINT A-Z DO INPUT "Decimal number (input number <= 0 to quit): ",Decimal IF Decimal <= 0 THEN EXIT DO INPUT "New base: ",Newbase N$ = "" PRINT Decimal "base 10 equals "; DO WHILE Decimal > 0 CALL Convert (Decimal,Newbase) Decimal = Decimal\Newbase LOOP PRINT N$ " base" Newbase PRINT LOOP SUB Convert (D,Nb) STATIC SHARED N$ ' Take the remainder to find the value of the current ' digit. R = D MOD Nb ' If the digit is less than ten, return a digit (0...9). ' Otherwise, return a letter (A...Z). IF R < 10 THEN Digit$ = CHR$(R+48) ELSE Digit$ = CHR$(R+55) N$ = RIGHT$(Digit$,1) + N$ END SUB ■ Output Decimal number (input number <= 0 to quit): 256 New base: 2 256 base 10 equals 100000000 base 2 Decimal number (input number <= 0 to quit): 31 New base: 16 31 base 10 equals 1F base 16 Decimal number (input number <= 0 to quit): -1 ──────────────────────────────────────────────────────────────────────────── SHELL Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Exits the BASIC program, runs a .COM, .EXE, or .BAT program or a DOS command, and returns to the program at the line following the SHELL statement ■ Syntax SHELL «commandstring» ■ Remarks The commandstring must be a valid string expression containing the name of a program to run and any program options. Any .COM file, .EXE file, .BAT program, or DOS function that runs under the SHELL statement is called a "child process." Child processes are executed by the SHELL statement, loading and running a copy of COMMAND.COM with the /C option automatically; this option allows any parameters in commandstring to be passed to the child process. It also allows redirection of standard input and output, and execution of built-in commands such as DIR, PATH, and SORT. The program name in commandstring may have any extension you wish. If no extension is supplied, COMMAND.COM looks for a .COM file, then an .EXE file, and finally, a .BAT file. If COMMAND.COM is not found, SHELL issues an error message that reads File not found. BASIC does not generate an error if COMMAND.COM cannot find the file specified in commandstring. Any text separated from the program name by at least one blank is treated as program parameters by COMMAND.COM. BASIC remains in memory while the child process is running. When the child process finishes, BASIC continues. SHELL with no commandstring gives you a new COMMAND.COM shell. You may now do anything that COMMAND.COM allows. Enter the DOS command EXIT when you are ready to return to BASIC. ■ Examples This example shows how a SHELL statement starts up a new COMMAND.COM: SHELL 'Get a new COMMAND.COM. ■ Output The IBM Personal Computer DOS Version 3.20 (C)Copyright International Business Machines Corp 1981, 1986 (C)Copyright Microsoft Corp 1981, 1986 D:\QB4> The following example copies all files modified on a certain date from a specified directory: ' This program copies all files in this directory modified ' on a certain date to the drive and directory you specify. DECLARE FUNCTION GetName$ (DirLine$) LINE INPUT "Enter target drive and directory: ",PathSpec$ SHELL "DIR > DIRFILE" 'Store directory listing in DIRFILE. DO OPEN "DIRFILE" FOR INPUT AS #1 INPUT "Enter date (MM-DD-YY): ",MDate$ PRINT ' Read DIRFILE, test for input date. DO LINE INPUT #1, DirLine$ ' Test directory line to see if date matches and the line ' is not one of the special directories ( . or .. ). IF INSTR(DirLine$,MDate$) > 0 AND LEFT$(DirLine$,1) <> "." THEN FileSpec$ = GetName$(DirLine$) ' Make sure we don't move our temporary file. IF FileSpec$ <> "DIRFILE" THEN ' Build the DOS command line to copy the file. DoLine$ = "COPY " + FileSpec$ + " " + PathSpec$ PRINT DoLine$ ' Copy the file. SHELL DoLine$ END IF END IF LOOP UNTIL EOF(1) CLOSE #1 PRINT "New date?" R$ = INPUT$(1) CLS LOOP UNTIL UCASE$(R$) <> "Y" ' KILL "DIRFILE". END ' This function gets the file name and extension from ' the directory-listing line. FUNCTION GetName$ (DirLine$) STATIC BaseName$ = RTRIM$(LEFT$(DirLine$,8)) ' Check for extension. ExtName$ = RTRIM$(MID$(DirLine$,10,3)) IF ExtName$ <> "" THEN BaseName$ = BaseName$ + "." + ExtName$ END IF GetName$ = BaseName$ END FUNCTION ■ Output Enter target drive and directory: c:\bas\temp Enter date (MM-DD-YY): 6-11-87 COPY CONF.DAT c:\bas\temp COPY TEST.BAS c:\bas\temp COPY TEMPFILE c:\bas\temp New date? n ──────────────────────────────────────────────────────────────────────────── SIN Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the sine of the angle x, where x is in radians ■ Syntax SIN(x) ■ Remarks When x is a double-precision value, the SIN function is calculated with double-precision accuracy. When x is not double precision, SIN is calculated with single-precision accuracy. ■ See Also ATN, COS, TAN ■ Example The example plots the graph of the polar equation r = 1 + sin n (Θ). This figure is sometimes known as a cardioid, owing to its resemblance to a heart when n equals 1. CONST PI = 3.141593 SCREEN 1 : COLOR 1,1 'Medium resolution, blue background. WINDOW (-3,-2)-(3,2) 'Convert screen to Cartesian 'coordinates. INPUT "Number of petals = ", N CLS PSET (1,0) 'Set initial point. FOR Angle = 0 TO 2*PI STEP .02 R = 1 + SIN(N*Angle) 'Polar equation for "flower." X = R * COS(Angle) 'Convert polar coordinates to Y = R * SIN(Angle) 'Cartesian coordinates. LINE -(X,Y) 'Draw line from previous point to 'new point. NEXT ──────────────────────────────────────────────────────────────────────────── SLEEP Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Suspends execution of the calling program ■ Syntax SLEEP « seconds » ■ Remarks The optional argument seconds determines the number of seconds the program is suspended. The SLEEP statement suspends the program until one of the following events occurs: ■ The time period in the seconds argument elapses. ■ A key is pressed. ■ An enabled event occurs. If seconds is zero or not specified, the program is suspended indefinitely. Only an enabled event or a keystroke can interrupt an indefinite suspension. SLEEP responds only to keystrokes that occur after it executes. SLEEP ignores characters in the keyboard buffer that were typed before it executed. An event (such as ON COM or ON TIMER) cannot interrupt a SLEEP suspension unless its trapping is active when the event occurs. This means that trapping must have been initialized with an ON event statement, turned on with an event ON statement, and not have been disabled with an event OFF statement or an event STOP statement. ■ See Also WAIT ■ Example The following program suspends execution for 10 seconds. There is no ON event statement, so the only way to interrupt the suspension before 10 seconds have passed is to press a key. PRINT "Taking a 10 second nap..." SLEEP 10 PRINT "Awake!" END ──────────────────────────────────────────────────────────────────────────── SOUND Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Generates sound through the speaker ■ Syntax SOUND frequency,duration ■ Remarks The frequency is the desired frequency in hertz (cycles/second). It must be a numeric expression returning an integer in the range 37-32,767. The duration is the duration in clock ticks. (There are 18.2 clock ticks per second regardless of CPU speed.) The duration must be a numeric expression returning an unsigned integer in the range 0-65,535. If the duration is zero, any current SOUND statement that is running is turned off. If no SOUND statement is running, a SOUND statement with a duration of zero has no effect. ■ SEE ALSO PLAY ■ Example This program fragment produces a rising and descending glissando: FOR I = 440 TO 1000 STEP 5 SOUND I, I/1000 NEXT FOR I = 1000 TO 440 STEP -5 SOUND I, I/1000 NEXT ──────────────────────────────────────────────────────────────────────────── SPACE$ Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns a string of spaces of length n ■ Syntax SPACE$(n) ■ Remarks The expression n is rounded to an integer and must be in the range 0-32,767. ■ See Also SPC ■ Example This example illustrates the use of SPACE$: FOR I=1 TO 5 X$=SPACE$(I) PRINT X$;I NEXT I ■ Output 1 2 3 4 5 ──────────────────────────────────────────────────────────────────────────── SPC Function ──────────────────────────────────────────────────────────────────────────── ■ Action Skips n spaces in a PRINT statement ■ Syntax SPC(n) ■ Remarks SPC may only be used with PRINT and LPRINT statements. The argument n must be in the range 0-32,767. A semicolon (;) is assumed to follow the SPC(n) command. ■ See Also SPACE$ ■ Example This example illustrates the use of SPC: PRINT "OVER";SPC(15) "THERE" ■ Output OVER THERE ──────────────────────────────────────────────────────────────────────────── SQR Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the square root of n ■ Syntax SQR(n) ■ Remarks The argument n must be >= 0. ■ Example The following program plots the graphs of y = √-x for -9 <= x < 0 and of y = √x for 0 <= x <= 9: SCREEN 1 : COLOR 1 'Low-resolution color graphics mode. WINDOW (-9,-.25)-(9,3.25) 'Convert screen to Cartesian 'coordinates. LINE (-9,0)-(9,0) 'Draw X-axis. LINE (0,-.25)-(0,3.25) 'Draw Y-axis. FOR X = -9 TO 9 LINE(X,.04)-(X,-.04) 'Put tick marks on X-axis. NEXT FOR Y = .25 TO 3.25 STEP .25 LINE (-.08,Y)-(.12,Y) 'Put tick marks on Y-axis. NEXT PSET (-9,3) 'Plot the first point of function. FOR X = -9 TO 9 STEP .25 Y = SQR(ABS(X)) 'SQR argument cannot be negative. LINE -(X,Y),2 'Draw a line to the next point. NEXT ──────────────────────────────────────────────────────────────────────────── STATIC Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Makes simple variables or arrays local to either a DEF FN function, a FUNCTION, or a SUB and preserves values between calls ■ Syntax STATIC variablelist ■ Remarks A STATIC statement variablelist has the following syntax: variable«( )»«AS type» «, variable«( )»«AS type»»... The variablelist takes the following arguments: Argument Description ────────────────────────────────────────────────────────────────────────── variable Either a variable name or an array name. AS type Declares the type of variable. The type argument can be INTEGER, LONG, SINGLE, DOUBLE, STRING, or a user-defined type. ────────────────────────────────────────────────────────────────────────── The STATIC statement can appear only in a SUB, FUNCTION, or DEF FN function. Earlier versions of BASIC required the number of dimensions in parentheses after an array name. In QuickBASIC, the number of dimensions is optional. Variables declared in a STATIC statement override variables of the same name shared by DIM or COMMON statements in the module-level code. Variables in a STATIC statement also override global constants of the same name. Usually, variables used in DEF FN functions are global to the module; however, you can use the STATIC statement inside a DEF FN statement to declare a variable as local to only that function. ──────────────────────────────────────────────────────────────────────────── NOTE The STATIC attribute on SUB and FUNCTION statements declares the default for variables to be static. Variables having the same name as variables shared by the module-level code are still shared. In contrast, the STATIC statement makes specific variables static and overrides any variables shared by the module-level code. The ¢STATIC metacommand affects how memory is allocated for arrays. See Chapter 2, "Data Types," for a discussion of the differences among these statements and attributes. ──────────────────────────────────────────────────────────────────────────── ■ See Also COMMON, DEF FN, DIM, FUNCTION, SHARED, SUB ■ Examples This example contrasts the STATIC and SHARED statements within a subprogram AUGMENT. The variables R and N are both local to this subprogram, while the variables REP and NUM are shared between the main program and the subprogram. The STATIC R,N statement ensures that R and N retain the last values assigned to them each time the main program calls the subprogram. Rep = 0 : Num = 0 PRINT "Before loop, REP = ";Rep;", NUM = ";Num; PRINT ", R = ";R;", N = ";N FOR I = 1 TO 10 CALL Augment NEXT PRINT "After loop, REP = ";Rep;", NUM = ";Num; PRINT ", R = ";R;", N = ";N END SUB Augment STATIC SHARED Rep,Num 'Shared with main program. STATIC R,N 'Not shared with main program. R = R + 1 'Both R and N initially equal 0. N = N + 2 Rep = R Num = N END SUB ■ Output Before loop, REP = 0 , NUM = 0 , R = 0 , N = 0 After loop, REP = 10 , NUM = 20 , R = 0 , N = 0 The following program searches for every occurrence of a certain string expression (stored in the variable OLD$) in the specified file and replaces that string with the string stored in NW$. The name of the file with these changes is the old filename with the extension .NEW. The program also prints the number of substitutions and the number of lines changed. INPUT "Name of file";F1$ INPUT "String to replace";Old$ INPUT "Replace with";Nw$ Rep = 0 : Num = 0 M = LEN(Old$) OPEN F1$ FOR INPUT AS #1 CALL Extension OPEN F2$ FOR OUTPUT AS #2 DO WHILE NOT EOF(1) LINE INPUT #1, Temp$ CALL Search PRINT #2, Temp$ LOOP CLOSE PRINT "There were ";Rep;" substitutions in ";Num;" lines." PRINT "Substitutions are in file ";F2$ END SUB Extension STATIC SHARED F1$,F2$ Mark = INSTR(F1$,".") IF Mark = 0 THEN F2$ = F1$ + ".NEW" ELSE F2$ = LEFT$(F1$,Mark - 1) + ".NEW" END IF END SUB SUB Search STATIC SHARED Temp$,Old$,Nw$,Rep,Num,M STATIC R Mark = INSTR(Temp$,Old$) WHILE Mark Part1 = LEFT$(Temp$,Mark - 1) Part2 = MID$(Temp$,Mark + M) Temp$ = Part1$ + Nw$ + Part2$ R = R + 1 Mark = INSTR(Temp$,Old$) WEND IF Rep = R THEN EXIT SUB ELSE Rep = R Num = Num + 1 END IF END SUB ■ Output Name of file? CHAP1.S String to replace? CHAPTER 1 Replace with? INTRODUCTION There were 23 substitutions in 19 lines. Substitutions are in file CHAP1.NEW The file CHAP1.NEW now contains every line in CHAP1.S, with each occurrence of the string CHAPTER 1 replaced by INTRODUCTION. ──────────────────────────────────────────────────────────────────────────── STICK Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the x- and y-coordinates of the two joysticks ■ Syntax STICK(n) ■ Remarks The argument n is a numeric expression whose value is an unsigned integer in the range 0 to 3: Argument Value Returned ────────────────────────────────────────────────────────────────────────── 0 The x-coordinate of joystick A 1 The y-coordinate of joystick A when STICK(0) was last called 2 The x-coordinate of joystick B when STICK(0) was last called 3 The y-coordinate of joystick B when STICK(0) was last called ────────────────────────────────────────────────────────────────────────── The x- and y-coordinates have a range of 1 to 200. You must use STICK(0) before you use STICK(1), STICK(2), or STICK(3). STICK(0) not only returns the x-coordinate of joystick A, it also records the other joystick coordinates. These recorded coordinates are returned by calling STICK(1)-STICK(3). ■ Example The following fragment prints the coordinates of joystick B: TEMP = STICK(0) PRINT STICK(2), STICK(3) ──────────────────────────────────────────────────────────────────────────── STOP Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Terminates the program ■ Syntax STOP ■ Remarks STOP statements can be used anywhere in a program to terminate execution. When running in the QuickBASIC environment, the STOP statement leaves files open and does not exit to the operating system. In contrast, a STOP statement in a stand-alone .EXE file does close all files and return to the operating system. If you use the /D, /E, or /X compile options on the bc command line, the STOP statement prints the number of the line where execution stopped, if your program has line numbers. If there is no line number associated with the STOP statement, the most recent line number is printed. If your program has no line numbers, then the line number printed is 0. In the past, STOP statements were used for debugging. QuickBASIC's new debugging features make this use of STOP unnecessary. ■ Example There is no programming example for the STOP statement. ──────────────────────────────────────────────────────────────────────────── STR$ Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns a string representation of the value of a numeric expression ■ Syntax STR$(numeric-expression) ■ Remarks If numeric-expression is positive, the string returned by the STR$ function contains a leading blank. The VAL function complements STR$. ■ See Also VAL ■ Example The following example contains a FUNCTION that uses the STR$ function to convert a number to its string representation. The FUNCTION then strips out the leading and trailing blanks that BASIC prints with numeric output. FUNCTION NumRemBlanks$(X) STATIC X$ = STR$(X) NumRemBlanks$ = LTRIM$(RTRIM$(X$)) END FUNCTION PRINT "Enter 0 to end." DO INPUT "Find cosine of: ",Num IF Num = 0 THEN EXIT DO PRINT "COS(" NumRemBlanks$(Num) ") = " COS(Num) LOOP ■ Output Enter 0 to end. Find cosine of: 3.1 COS(3.1) = -.9991351 Find cosine of: 0 ──────────────────────────────────────────────────────────────────────────── STRIG Function and Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the status of a specified joystick trigger ■ Syntax 1 (Function) STRIG(n) ■ Syntax 2 (Statement) STRIG {ON | OFF} ■ Remarks The STRIG function is used to test the joystick trigger status. In previous versions of BASIC, the statement STRIG ON enables testing of the joystick triggers; STRIG OFF disables joystick trigger testing. QuickBASIC ignores STRIG ON and STRIG OFF statements──the statements are provided for compatibility with earlier versions. The numeric expression n is an unsigned integer in the range 0-7, indicating the joystick and trigger to check. The following list describes the values returned by the STRIG(n) function for different values of n: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Argument Value Returned ────────────────────────────────────────────────────────────────────────── 0 Returns -1 if the lower button on joystick A has been pressed since the last STRIG(0) call; otherwise returns 0 1 Returns -1 if the lower button on joystick A is currently down; otherwise returns 0 2 Returns -1 if the lower button on joystick B has Argument Value Returned ────────────────────────────────────────────────────────────────────────── 2 Returns -1 if the lower button on joystick B has been pressed since the last STRIG(2) call; otherwise returns 0 3 Returns -1 if the lower button on joystick B is currently down; otherwise returns 0 4 Returns -1 if the upper button on joystick A has been pressed since the last STRIG(4) call; otherwise returns 0 5 Returns -1 if the upper button on joystick A is currently down; otherwise returns 0 6 Returns -1 if the upper button on joystick B has been pressed since the last STRIG(6) call; otherwise returns 0 7 Returns -1 if the upper button on joystick B is Argument Value Returned ────────────────────────────────────────────────────────────────────────── 7 Returns -1 if the upper button on joystick B is currently down; otherwise returns 0 ────────────────────────────────────────────────────────────────────────── You can also use event trapping to get information from the joystick by using the ON STRIG statement (see the ON event statement). You cannot use the STRIG function inside a joystick event trap because the event that caused the trap is destroyed. ■ Differences From Basica If you are compiling from the BC command line, you must use the /V or /W option if a program contains a STRIG statement. ■ See Also ON event; STRIG ON, OFF, and STOP ■ Example The following example illustrates STRIG: 'Wait for trigger A to be pressed. DO GotATrig = STRIG(0) LOOP UNTIL GotATrig 'As long as trigger A is down, beep. DO GotATrig = STRIG(1) BEEP LOOP WHILE GotATrig ──────────────────────────────────────────────────────────────────────────── STRIG ON, OFF, and STOP Statements ──────────────────────────────────────────────────────────────────────────── ■ Action Enables, disables, or inhibits trapping of joystick activity ■ Syntax STRIG(n) ON STRIG(n) OFF STRIG(n) STOP ■ Remarks The argument, n, is a numeric expression indicating the joystick button to trap: Value Button ────────────────────────────────────────────────────────────────────────── 0 Lower button, joystick A 2 Lower button, joystick B 4 Upper button, joystick A 6 Upper button, joystick B ────────────────────────────────────────────────────────────────────────── The STRIG(n) ON statement enables joystick event trapping by an ON STRIG statement (see the ON event statement). While trapping is enabled, and if a nonzero line number is specified in the ON STRIG statement, BASIC checks between every statement to see if the joystick trigger has been pressed. The STRIG(n) OFF statement disables event trapping. If a subsequent event occurs (i.e., if the trigger is pressed), it will not be remembered when the next STRIG ON is executed. The STRIG(n) STOP statement inhibits event trapping. If an event occurs it is remembered, and the event trap takes place as soon as trapping is reenabled. ■ See Also ON event, STRIG ■ Example There is no programming example for the STRIG statement. ──────────────────────────────────────────────────────────────────────────── STRING$ Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns a string whose characters all have a given ASCII code or whose characters are all the first character of a string expression ■ Syntax STRING$(m,n) STRING$(m,stringexpression) ■ Remarks The STRING$ function has the following arguments: Argument Description ────────────────────────────────────────────────────────────────────────── m A numeric expression indicating the length of the string to return. n The ASCII code of the character to use to build the string. It is a numeric expression that evaluates to an integer value in the range 0-255. stringexpression The string expression whose first character is used to build the return string. ────────────────────────────────────────────────────────────────────────── ■ Examples The following example uses STRING$ to create part of a report heading: Dash$ = STRING$(10,45) PRINT Dash$;"MONTHLY REPORT";Dash$ ■ Output ----------MONTHLY REPORT---------- The following program uses STRING$ to generate a bar graph: PRINT TAB(7);"Daily Mean Temperature in Seattle" : PRINT 'Get data for each month and graph. FOR Month = 1 TO 12 STEP 2 READ Month$, Temp 'Print Temp-35 stars. PRINT Month$;" +"; STRING$(Temp-35,"*") PRINT " |" NEXT Month 'Print horizontal line. PRINT " +"; FOR X = 1 TO 7 PRINT "----+"; NEXT X PRINT 'Print temperature labels. FOR X = 4 TO 39 STEP 5 PRINT TAB(X); X+31; NEXT X PRINT DATA Jan, 40, Mar, 46, May, 56 DATA Jul, 66, Sep, 61, Nov, 46 ■ Output Daily Mean Temperature in Seattle Jan +***** | Mar +*********** | May +********************* | Jul +******************************* | Sep +************************** | Nov +*********** | +----+----+----+----+----+----+----+ 35 40 45 50 55 60 65 70 ──────────────────────────────────────────────────────────────────────────── SUB Statements ──────────────────────────────────────────────────────────────────────────── ■ Action Marks the beginning and end of a subprogram ■ Syntax SUB globalname«(parameterlist)» «STATIC» . . . «EXIT SUB» . . . END SUB ■ Remarks The SUB statement takes the following arguments: Argument Description ────────────────────────────────────────────────────────────────────────── globalname A variable name up to 40 characters long. This name cannot appear in any other FUNCTION or SUB statement in the same program or the user library. parameterlist Contains the names of simple variables and arrays passed to the subprogram when the SUB is invoked. Each name is separated from the preceding name by a comma. Note that these variables and arrays are passed by reference, so any change to an argument's value in the subprogram also changes its value in the calling program. See below for a complete description of the syntax. ────────────────────────────────────────────────────────────────────────── A SUB parameterlist has the following syntax: variable«( )» «AS type» «, variable«( )» «AS type»»... A variable is a BASIC variable name. Previous versions of BASIC required the number of dimensions in parentheses after an array name. In QuickBASIC, the number of dimensions is not required. The argument type is the type of the variable. The type argument can be INTEGER, LONG, SINGLE, DOUBLE, STRING, or a user-defined type. You may not use a fixed-length string, or an array of fixed-length strings, as a parameter. However, you may use a simple fixed-length string as an argument in a CALL statement──QuickBASIC converts a simple fixed-length string argument to a variable-length string argument before passing the string to a SUB. A subprogram is a separate procedure, like a FUNCTION. However, a SUB cannot be used in an expression, unlike a FUNCTION. SUB and END SUB mark the beginning and end of a subprogram. You may also use the optional EXIT SUB statement to exit a subprogram. Subprograms are called by a CALL statement or by using the subprogram name followed by the argument list. See the entry for the CALL statement. QuickBASIC subprograms can be recursive──they can call themselves to perform a given task. See the second example below and Section 4.4, "Recursion." The STATIC attribute indicates that all variables local to the SUB are static──their values are saved between calls. Using the STATIC keyword slightly increases execution speed. STATIC is not usually used with recursive subprograms. See the examples below. Any subprogram variables or arrays are considered local to that subprogram unless they are explicitly declared as shared variables in a SHARED statement. You cannot define SUB procedures, DEF FN functions, or FUNCTION procedures inside a SUB procedure. ──────────────────────────────────────────────────────────────────────────── NOTE You cannot use GOSUB, GOTO, or RETURN to enter or exit a subprogram. ──────────────────────────────────────────────────────────────────────────── See Chapter 2, "SUB and FUNCTION Procedures," in Programming in BASIC for more information. ■ See Also CALL (BASIC), DECLARE (BASIC), SHARED, STATIC ■ Examples In this example, the main program calls a subprogram, LINESEARCH, which searches for the given string, P$, in each line of input from file F$. When the subprogram finds P$ in a line, it prints the line, along with the number of the line. Notice that the value of Num is saved between calls because the STATIC keyword is used on the SUB statement. INPUT "File to be searched";F$ INPUT "Pattern to search for";P$ OPEN F$ FOR INPUT AS #1 DO WHILE NOT EOF(1) LINE INPUT #1, Test$ CALL Linesearch(Test$,P$) LOOP SUB Linesearch(Test$,P$) STATIC Num = Num + 1 X = INSTR(Test$,P$) IF X > 0 THEN PRINT "Line #";Num;": ";Test$ END SUB ■ Output File to be searched? search.bas Pattern to search for? SUB Line # 9 : SUB Linesearch(Test$,P$) STATIC Line # 13 : END SUB The following example uses a recursive SUB to solve the classic Tower of Hanoi puzzle for a variable number of disks. For large numbers of disks, the stack size must be increased using the CLEAR statement. DECLARE SUB Hanoi (N%, Srce%, Dest%, Hold%) DEFINT A-Z DIM SHARED MoveCount MoveCount = 0 CLS PRINT "Tower of Hanoi Puzzle" INPUT "Enter number of disks: ", Disks ' Call the recursive Hanoi SUB to solve the puzzle. CALL Hanoi(Disks, 1, 3, 2) PRINT "Puzzle complete in"; MoveCount; "moves." END ' Move N disks from Srce to Dest using Hold as holding peg. SUB Hanoi (N, Srce, Dest, Hold) IF N <= 1 THEN ' Only 1 disk. Move it directly to Dest. PRINT "Move a disk from"; Srce; "to"; Dest MoveCount = MoveCount + 1 ELSE ' More than one disk. ' Move the N-1 disks to Hold, using Dest as holding peg. CALL Hanoi(N - 1, Srce, Hold, Dest) ' Move the Nth disk directly to Dest. PRINT "Move a disk from"; Srce; "to"; Dest: MoveCount = MoveCount + 1 ' Move the N-1 disks to Dest, using Srce as holding peg. CALL Hanoi(N - 1, Hold, Dest, Srce) END IF END SUB ■ Output Tower of Hanoi Puzzle Enter number of disks: 3 Move a disk from 1 to 3 Move a disk from 1 to 2 Move a disk from 3 to 2 Move a disk from 1 to 3 Move a disk from 2 to 1 Move a disk from 2 to 3 Move a disk from 1 to 3 Puzzle complete in 7 moves. ──────────────────────────────────────────────────────────────────────────── SWAP Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Exchanges the values of two variables ■ Syntax SWAP variable1,variable2 ■ Remarks Any type of variable can be swapped (integer, long, single precision, double precision, string, or record). However, the two variables must be exactly the same type or an error message appears (Type mismatch). For example, trying to swap an integer with a single-precision value produces Type mismatch. ■ Example The following subroutine (ShellSort) sorts the elements of a string array in descending order using a Shell sort. ShellSort uses SWAP to exchange array elements that are out of order. ' Sort the word list using a Shell sort. SUB ShellSort (Array$(), Num%) STATIC Span% = Num% \ 2 DO WHILE Span% > 0 FOR I% = Span% TO Num% - 1 J% = I% - Span% + 1 FOR J% = (I% - Span% + 1) TO 1 STEP -Span% IF Array$(J%) <= Array$(J% + Span%) THEN EXIT FOR ' Swap array elements that are out of order. SWAP Array$(J%), Array$(J% + Span%) NEXT J% NEXT I% Span% = Span% \ 2 LOOP END SUB ──────────────────────────────────────────────────────────────────────────── SYSTEM Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Closes all open files and returns control to the operating system ■ Syntax SYSTEM ■ Remarks When a SYSTEM command is executed, all files are closed and BASIC exits to the operating system (for stand-alone executable programs) or stops program execution (if the program is run in the QuickBASIC environment). ──────────────────────────────────────────────────────────────────────────── NOTE A program containing a SYSTEM statement exits to the operating system if run from the QuickBASIC command line with the /RUN option. Entering a SYSTEM statement in the Immediate window terminates QuickBASIC. ──────────────────────────────────────────────────────────────────────────── ■ Differences From Basica END and SYSTEM are distinct in BASICA but act identically in QuickBASIC. ■ Example There is no programming example for the SYSTEM statement. ──────────────────────────────────────────────────────────────────────────── TAB Function ──────────────────────────────────────────────────────────────────────────── ■ Action Moves the print position ■ Syntax TAB(column) ■ Remarks The argument, column, is a numeric expression that is the column number of the new print position. If the current print position is already beyond column, the TAB function moves the print position to that column on the next line. Column 1 is the leftmost position, and the rightmost position is the current line width of the output device minus one. If column is greater than the output width, TAB wraps the output and the print position becomes 1 + (column MOD width). If column is less than 1, TAB moves the print position to column 1. TAB can only be used in PRINT and LPRINT statements. ■ See Also WIDTH ■ Examples The following example uses TAB to locate columns of output: FOR I = 1 TO 4 READ A$,B$ PRINT A$ TAB(25) B$ NEXT DATA NAME, AMOUNT,,, G.T. JONES, $25.00, H.L. STEVENS, $32.25 ■ Output NAME AMOUNT G.T. JONES $25.00 H.L. STEVENS $32.25 The following example shows the effects of different values used as arguments to TAB: 'Assumes 80-column screen width. PRINT TAB(1287); "one" PRINT TAB(255); "two" PRINT TAB(-5); "three" PRINT "123456789012345678901234567890" TAB(20) "four" ■ Output one two three 123456789012345678901234567890 four ──────────────────────────────────────────────────────────────────────────── TAN Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the tangent of the angle x, where x is in radians ■ Syntax TAN(x) ■ Remarks TAN is calculated with single-precision accuracy unless x is a double-precision value, in which case TAN is calculated with double-precision accuracy. ■ Differences From Basica In BASICA, if TAN overflows, the interpreter displays the Overflow error message, returns machine infinity as the result, and continues execution. If TAN overflows, QuickBASIC does not display machine infinity and execution halts (unless the program has an error-handling routine). ■ Example The following example computes the height of an object using the distance from the object and the angle of elevation. The program draws the triangle produced by the base and the computed height. SCREEN 2 INPUT "LENGTH OF BASE: ",Baselen INPUT "ANGLE OF ELEVATION (DEGREES,MINUTES): ",Deg,Min Ang = (3.141593/180)*(Deg + Min/60) 'Convert to radians. Height = Baselen*TAN(Ang) 'Calculate height. PRINT "HEIGHT =" Height H = 180 - Height B = 15 + Baselen LINE (15,180)-(B,180):LINE -(B,H) 'Draw triangle. LINE -(10,180) LOCATE 24,1 : PRINT "Press any key to continue..."; DO LOOP WHILE INKEY$="" ──────────────────────────────────────────────────────────────────────────── TIME$ Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the current time from the operating system ■ Syntax TIME$ ■ Remarks The TIME$ function returns an eight-character string in the pattern hh:mm:ss, where hh is the hour (00-23), mm is minutes (00-59), and ss is seconds (00-59). A 24-hour clock is used; therefore, 8:00 PM is shown as 20:00:00. To set the time, use the TIME$ statement. ■ See Also TIME$ Statement, TIMER ■ Example The following example converts the 24-hour time returned by TIME$ to a 12-hour time: 'Convert the 24-hour clock used by TIME$ to '12-hour output followed by "AM" or "PM." T$ = TIME$ Hr = VAL(T$) IF Hr < 12 THEN Ampm$ = " AM" ELSE Ampm$ = " PM" IF Hr > 12 THEN Hr = Hr - 12 PRINT "The time is" STR$(Hr) RIGHT$(T$,6) Ampm$ ■ Output The time is 11:26:31 AM ──────────────────────────────────────────────────────────────────────────── TIMER Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the number of seconds elapsed since midnight ■ Syntax TIMER ■ Remarks The TIMER function can be used with the RANDOMIZE statement to generate a random number. It can also be used to time programs or parts of programs. ■ Example The following program searches for the prime numbers from 3 to 10,000 using a variation of the Sieve of Eratosthenes. The TIMER function is used to time the program. DEFINT A-Z CONST UNMARK = 0, MARKIT = NOT UNMARK DIM Mark(10000) Start! = TIMER Num = 0 FOR N = 3 TO 10000 STEP 2 IF NOT Mark(N) THEN 'PRINT N, 'To print the primes, remove the 'remark delimiter in front of the 'PRINT statement. Delta = 2*N FOR I = 3*N TO 10000 STEP Delta Mark(I) = MARKIT NEXT Num = Num + 1 END IF NEXT Finish! = TIMER PRINT : PRINT "Program took"; Finish!-Start!; PRINT "seconds to find the"; Num; "primes" END ■ Output Program took .1601563 seconds to find the 1228 primes ──────────────────────────────────────────────────────────────────────────── TIMER ON, OFF, and STOP Statements ──────────────────────────────────────────────────────────────────────────── ■ Action Enables, disables, or inhibits timer event trapping ■ Syntax TIMER ON TIMER OFF TIMER STOP ■ Remarks TIMER ON enables timer event trapping by an ON TIMER statement (see the statement ON event). While trapping is enabled, a check is made after every statement to see if the specified time has elapsed. If it has, the ON TIMER event-handling routine is executed. TIMER OFF disables timer event trapping. If an event takes place, it is not remembered if a subsequent TIMER ON is executed. TIMER STOP disables the timer event trapping. However, if an event occurs, it is remembered and the ON TIMER event-handling routine is executed as soon as trapping is reenabled with TIMER ON. ■ See Also ON event ■ Example The following example displays the time of day on line 1, and updates the display once a minute: TIMER ON ON TIMER(60) GOSUB Display DO WHILE INKEY$ = "" : LOOP END Display: Oldrow = CSRLIN 'Save current row. Oldcol = POS(0) 'Save current column. LOCATE 1,1 : PRINT TIME$; LOCATE Oldrow,Oldcol 'Restore row & column. RETURN ──────────────────────────────────────────────────────────────────────────── TIME$ Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Sets the time ■ Syntax TIME$=stringexpression ■ Remarks The stringexpression must be in one of the following forms: Form Description ────────────────────────────────────────────────────────────────────────── hh Sets the hour; minutes and seconds default to 00 hh:mm Sets the hour and minutes; seconds default to 00 hh:mm:ss Sets the hour, minutes, and seconds ────────────────────────────────────────────────────────────────────────── A 24-hour clock is used, so 8:00 PM would be entered as 20:00:00. This statement complements the TIME$ function, which returns the current time. ■ See Also TIME$ Function ■ Example The following example sets the current time to 8:00 AM: TIME$="08:00:00" ──────────────────────────────────────────────────────────────────────────── TRON/TROFF Statements ──────────────────────────────────────────────────────────────────────────── ■ Action Traces the execution of program statements ■ Syntax TRON TROFF ■ Remarks In the QuickBASIC environment, executing a TRON statement has the same effect as selecting Trace On from the Debug menu──each statement is highlighted on the screen as it executes. The TROFF statement turns off the program trace. The TRON and TROFF statements only display line numbers when compiled with the Debug option or the /D option on the BC command line. ──────────────────────────────────────────────────────────────────────────── NOTE The debugging features of the QuickBASIC environment make these statements unnecessary. ──────────────────────────────────────────────────────────────────────────── ■ Example There is no programming example for the TRON statement. ──────────────────────────────────────────────────────────────────────────── TYPE Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Defines a data type containing one or more elements ■ Syntax TYPE usertype elementname AS typename elementname AS typename . . . END TYPE ■ Remarks The TYPE statement takes the following arguments: Argument Description ────────────────────────────────────────────────────────────────────────── usertype A name given to the user-defined data type. Follows the same rules as a BASIC variable name. elementname The name of an element of the user-defined data type. Follows the same rules as a BASIC variable name. Cannot be the name of an array. typename May be any of the following BASIC data types: INTEGER, LONG, SINGLE, DOUBLE, fixed-length string (see note below), or user-defined type. ────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── NOTE Strings in user types must be fixed-length strings. String lengths are indicated by an asterisk and a numeric constant. For example, the following line defines an element named Keyword in a user-defined type as a string with length 40: Keyword AS STRING*40 ──────────────────────────────────────────────────────────────────────────── A user-defined type must be declared in a TYPE declaration before it can be used in the program. Although a user-defined type can only be declared in the module-level code, you may declare a variable to be of a user-defined type anywhere in the module, even in a SUB or FUNCTION. Use the DIM, REDIM, COMMON, STATIC, or SHARED statements to declare a variable to be of a user-defined type. ■ Example The following example simulates a deck of cards by using a user-defined type. The program builds a deck of cards (an array of user-defined type Card), shuffles the deck, and displays the first five cards. ' This program uses a user-defined type to ' simulate a deck of cards. ' Define the Card type--an integer value and a string ' representing the suit. TYPE Card Value AS INTEGER Suit AS STRING*9 END TYPE DEFINT A-Z ' Define the Deck as a 52-element array of Cards. DIM Deck(1 TO 52) AS Card ' Build, shuffle, and deal the top five cards. CALL BuildDeck(Deck()) CALL Shuffle(Deck()) FOR I%=1 TO 5 CALL ShowCard(Deck(I%)) NEXT I% ' Build the deck--fill the array of Cards with ' appropriate values. SUB BuildDeck(Deck(1) AS Card) STATIC DIM Suits(4) AS STRING*9 Suits(1)="Hearts" Suits(2)="Clubs" Suits(3)="Diamonds" Suits(4)="Spades" ' This loop controls the suit. FOR I%=1 TO 4 ' This loop controls the face value. FOR J%=1 TO 13 ' Figure out which card (1...52) you're creating. CardNum%=J%+(I%-1)*13 ' Place the face value and suit into the Card. Deck(CardNum%).Value=J% Deck(CardNum%).Suit=Suits(I%) NEXT J% NEXT I% END SUB ' Shuffle a deck (an array containing Card elements). SUB Shuffle(Deck(1) AS Card) STATIC RANDOMIZE TIMER ' Shuffle by transposing 1000 randomly selected pairs of cards. FOR I%=1 TO 1000 CardOne%=INT(52*RND+1) CardTwo%=INT(52*RND+1) ' Notice that SWAP works on arrays of user types. SWAP Deck(CardOne%),Deck(CardTwo%) NEXT I% END SUB ' Display a single card by converting and printing the ' face value and the suit. SUB ShowCard (SingleCard AS Card) STATIC SELECT CASE SingleCard.Value CASE 13 PRINT "King "; CASE 12 PRINT "Queen"; CASE 11 PRINT "Jack "; CASE 1 PRINT "Ace "; CASE ELSE PRINT USING " ## ";SingleCard.Value; END SELECT PRINT " ";SingleCard.Suit END SUB ■ Output 3 Clubs 4 Hearts 3 Diamonds Jack Clubs 8 Spades ──────────────────────────────────────────────────────────────────────────── UBOUND Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the upper bound (largest available subscript) for the indicated dimension of an array ■ Syntax UBOUND(array«,dimension») ■ Remarks The argument dimension is an integer from 1 to the number of dimensions in array. For an array dimensioned as follows, UBOUND returns the values listed below: DIM A(1 TO 100, 1 TO 50, -3 TO 4) Invocation Value Returned ────────────────────────────────────────────────────────────────────────── UBOUND(A,1) 100 UBOUND(A,2) 50 UBOUND(A,3) 4 ────────────────────────────────────────────────────────────────────────── You can use the shortened syntax UBOUND(array) for one-dimensional arrays since the default value for dimension is 1. Use the LBOUND function to find the lower limit of an array dimension. ■ See Also LBOUND ■ Example LBOUND and UBOUND can be used together to determine the size of an array passed to a subprogram, as in the following program fragment: CALL PRNTMAT(ARRAY()) . . . SUB PRNTMAT(A()) STATIC FOR I% = LBOUND(A,1) TO UBOUND(A,1) FOR J% = LBOUND(A,2) TO UBOUND(A,2) PRINT A(I%,J%);" "; NEXT J% PRINT:PRINT NEXT I% END SUB ──────────────────────────────────────────────────────────────────────────── UCASE$ Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns a string expression with all letters in uppercase ■ Syntax UCASE$ (stringexpression) ■ Remarks The stringexpression argument can be any string expression. The UCASE$ function works with both variable- and fixed-length strings. The UCASE$ and LCASE$ statements are helpful in making string comparisons case insensitive. ■ See Also LCASE$ ■ Example The following program contains a FUNCTION, YesQues, that returns a Boolean value depending on how the user responds. The program YesQues uses UCASE$ to make a case-insensitive test of the user's response. DEFINT A-Z FUNCTION YesQues(Prompt$,Row,Col) STATIC OldRow=CSRLIN OldCol=POS(0) ' Print prompt at Row, Col. LOCATE Row,Col : PRINT Prompt$ "(Y/N):"; DO ' Get the user to press a key. DO Resp$=INKEY$ LOOP WHILE Resp$="" Resp$=UCASE$(Resp$) ' Test to see if it's yes or no. IF Resp$="Y" OR Resp$="N" THEN EXIT DO ELSE BEEP END IF LOOP ' Print the response on the line. PRINT Resp$; ' Move the cursor back to the old position. LOCATE OldRow,OldCol ' Return a Boolean value by returning the result of a test. YesQues=(Resp$="Y") END FUNCTION DO LOOP WHILE NOT YesQues("Do you know the frequency?",12,5) ──────────────────────────────────────────────────────────────────────────── UEVENT Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Enables, disables, or suspends event trapping for a user-defined event ■ Syntax UEVENT ON UEVENT OFF UEVENT STOP ■ Remarks The effects of the UEVENT statements are like that of other event-trapping statements. When UEVENT ON is executed, the event-trapping routine is enabled. Occurrences of the event trigger execution of the event-handling routine. When UEVENT OFF is executed, the event-trapping routine is disabled. Any occurrences of the event are ignored. When UEVENT STOP is executed, the event-trapping routine is suspended. An event occurrence is remembered and the event-trapping routine performed as soon as a UEVENT ON statement is executed. ■ See Also ON UEVENT ■ Example See the example for ON UEVENT. ──────────────────────────────────────────────────────────────────────────── UNLOCK Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Releases locks applied to parts of a file ■ Syntax UNLOCK «#» filenumber «,{record | «start» TO end}» ■ Remarks The UNLOCK statement is used only after a LOCK statement. See the LOCK statement for a complete discussion. For binary-mode files, the arguments record, start, and end represent the number of a byte relative to the beginning of the file. The first byte in a file is byte 1. For random-access files, these arguments are the number of a record relative to the beginning of the file. The first record is record 1. ■ See Also LOCK ■ Example See the example for LOCK. ──────────────────────────────────────────────────────────────────────────── Creating a User-Defined Event ──────────────────────────────────────────────────────────────────────────── In previous versions of QuickBASIC, the only events that could be trapped were those already defined in the language: COM, KEY, PEN, PLAY, STRIG and TIMER. There was no way to define your own event. QuickBASIC 4.5 allows you to define your own event trap. When the event occurs, BASIC calls the routine that handles the trap, just as if the event were part of the QuickBASIC language. A user-defined event has three elements. The first is a routine that detects the event. The second is this routine's call to the BASIC procedure SetUEvent, which traps the event. The third is BASIC's call to a routine that handles the event. You create a user-defined event by writing two pieces of code. The first is the routine that detects the event. (The event could be a hardware interrupt, or perhaps an altered data value at a special memory location.) This routine can be written in BASIC, or other languages, such as C and assembler. (BASIC routines can be included in the main module. Code written in other languages must be separately compiled and added to a Quick Library.) The event-detecting routine must block; that is, it must sit waiting for the event. (A routine that does not block would have to be called repeatedly to see if the event has occurred. This defeats the purpose of a user-defined event, as it is no different from conventional polling.) When the event occurs, it calls the BASIC routine SetUEvent. It is this call that traps the event. BASIC then calls the event handler. The event handler is the second piece of code. The advantage of separating event trapping from event handling is that the handling can be tailored to the needs of the moment; the same event can be handled differently in different parts of the program. Let's consider a simple example to see how this works. Our hypothetical programmer has designed an interface board for home monitoring and control. One of its features is a mailbox alarm: opening the mailbox door closes a switch that sets the most-significant bit at a specific buss address. Here is a simple BASIC routine to monitor this switch. (The segment and address quantities are for illustration only. They are in the video RAM space, and probably wouldn't be useful for other kinds of interfaces.) MailBoxOpened: DEF SEG = &h9000 ' set the address segment value% = PEEK (&h1234) ' read value at address in that segment IF value% THEN CALL SetUEvent ' tell BASIC event has occurred DEF SEG ' return to BASIC data segment ■ RETURN Value% is either zero, or has its MSB set. In the latter case it is logically "true" (indicating that the mailbox was opened), and the SetUEvent routine is called. This routine (which is part of BASIC) tells BASIC that the expected event has occurred, and it is time to execute the event-handling routine. All event-detecting routines, regardless of the languages they are written in, must call SetUEvent. If the event-detecting routine is in a language other than BASIC, the Quick Library containing it has to be loaded before a QuickBASIC program that uses it can run or be compiled. Include a DECLARE SUB statement in the module calling the event-detection routine, so that BASIC knows how to find it. Now let's write an event-handling routine to tell our programmer his mail has arrived: MailCame: PRINT "Ta-Dah! Your day is made! The mail came!" ■ RETURN All that's left is to tell BASIC about the user-defined event handler, using the ON UEVENT statement. ON UEVENT works just like ON EVENT; it associates the user-defined event with the event-handling routine: ON UEVENT GOSUB MailCame ' associate the handler routine with user event UEVENT ON ' initiate user-event trapping . . . CALL MailBoxOpened ' call the routine that looks for the event . . . END Note that ON UEVENT deals only with the event-handler; it is not concerned with event-detection. Once the UEVENT ON statement has been executed, any call to SetUEvent will trigger the specified event-handler, regardless of how or where the call is issued. Here is a summary of the steps in creating and using a user-defined event handler: 1. Write the routine that detects the event. When the event occurs, the routine must call the BASIC routine SetUEvent. 2. If the event-detecting routine is in BASIC, place it after the END statement in the module where it will be called. If the event-detecting routine is not in BASIC, compile it and include it in a BASIC Quick Library. The module(s) that call this routine must include a DECLARE SUB statement so that BASIC can find the routine. 3. Write the routine that handles the event. 4. Use the ON UEVENT statement to tell BASIC the name of the event-handling routine associated with the user-defined event. 5. Use the UEVENT ON statement to initiate trapping. (UEVENT OFF and UEVENT STOP may be used to terminate or postpone trapping.) 6. Call the event-detecting routine. When the event occurs, BASIC will call the event-handling routine named in the ON UEVENT statement. ──────────────────────────────────────────────────────────────────────────── VAL Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the numeric value of a string of digits ■ Syntax VAL(stringexpression) ■ Remarks The stringexpression is a sequence of characters that can be interpreted as a numeric value. The VAL function stops reading the string at the first character that it cannot recognize as part of a number. The VAL function also strips leading blanks, tabs, and line feeds from the argument string. For example, VAL(" -33/LP") returns the value -33. ■ See Also STR$ ■ Example The following program prints the names and addresses of people with specific telephone area codes: INPUT "Search for which area: ", Targetarea OPEN "MAIL.DAT" FOR INPUT AS #1 DO WHILE NOT EOF(1) INPUT #1, Nm$, Phonenum$, Street$, Citystate$ 'VAL reads everything up to the first non-numeric 'character ("-" in this case). Area = VAL(Phonenum$) IF Area = Targetarea THEN PRINT : PRINT Nm$ PRINT Street$ PRINT Citystate$ END IF LOOP CLOSE : END ──────────────────────────────────────────────────────────────────────────── VARPTR, VARSEG Functions ──────────────────────────────────────────────────────────────────────────── ■ Action Returns the address of a variable ■ Syntax VARPTR(variablename) VARSEG(variablename) ■ Remarks The variablename may be any BASIC variable, including a record variable or record element. The VARPTR function returns an unsigned integer that is the offset of the variable within its segment. The VARSEG function returns an unsigned integer that is the segment part of the variable's address. If variablename is not defined before either VARPTR or VARSEG is called, the variable is created and its address is returned. When variablename is a string variable, VARPTR and VARSEG return the location of the first byte of the string descriptor. ──────────────────────────────────────────────────────────────────────────── NOTE Because many BASIC statements change the locations of variables in memory, use the values returned by VARPTR and VARSEG immediately after the functions are used. See Section 2.3.3, "Variable Storage Allocation," for a list of things that cause variable locations to move. ──────────────────────────────────────────────────────────────────────────── VARPTR and VARSEG are often used with BLOAD, BSAVE, CALL ABSOLUTE, CALL INTERRUPT, PEEK, POKE, or when passing arrays to procedures written in other languages. When using VARPTR or VARSEG to get the address of an array, use the first element of the array as the argument: DIM A(150) . . . ArrAddress=VARPTR(A(1)) You may no longer use VARPTR to get the address of a file's buffer. Use the function FILEATTR to get information about a file. In addition, programs written in earlier versions of BASIC that used VARPTR to access numeric arrays may no longer work. You must now use a combination of VARPTR and VARSEG. For example, the following QuickBASIC Version 3.0 fragment no longer works correctly: DIM Cube(675) . . . BSAVE "graph.dat",VARPTR(Cube(1)),2700 The fragment would be rewritten as follows: DIM Cube(675) . . . ' Change segment to segment containing Cube. DEF SEG=VARSEG(Cube(1)) BSAVE "graph.dat",VARPTR(Cube(1)),2700 ' Restore BASIC segment. DEF SEG You may use VARPTR alone to get the address of a variable stored in DGROUP. You must use both VARPTR and VARSEG to get the complete address of a variable stored as a far object. See Section 2.3.3, "Variable Storage Allocation," for rules to determine when a variable is stored in DGROUP. The VARSEG function combined with VARPTR replaces the PTR86 subprogram used in previous versions of QuickBASIC. ■ See Also BLOAD, BSAVE, CALL ABSOLUTE, CALL INTERRUPT, DEF SEG, PEEK, POKE ■ Example See the entries for BLOAD, BSAVE, CALL ABSOLUTE, and CALL INTERRUPT for examples of how to use VARPTR and VARSEG with those statements. The following program illustrates how to use VARPTR and VARSEG to pass a BASIC array to a C function. The C function would be separately compiled and then placed in a Quick library or linked to the BASIC main program. ' BASIC program passing an array to C function. DECLARE SUB AddArr CDECL (BYVAL Offs%, BYVAL Segm%, BYVAL Num%) DIM A(1 TO 100) AS INTEGER ' Fill the array with the numbers 1 to 15. FOR I=1 TO 15 A(I)=I NEXT I ' Call the C function. AddArr expects a far address (segment ' and offset). Because CDECL puts things on the stack from ' right to left, put the offset ( VARPTR(A(1)) ) first in the ' list, followed by the segment ( VARSEG(A(1)) ). CALL AddArr(VARPTR(A(1)),VARSEG(A(1)),15%) ' Print the modified array. FOR I=1 TO 15 PRINT A(I) NEXT I END /* Add one to the first num elements of array arr.*/ void far addarr(arr,num) int far *arr; int num; { int i; for(i=0;i<num;i++) arr[i]++; } ──────────────────────────────────────────────────────────────────────────── VARPTR$ Function ──────────────────────────────────────────────────────────────────────────── ■ Action Returns a string representation of a variable's address as needed for use in DRAW and PLAY statements ■ Syntax VARPTR$(variablename) ■ Remarks The variablename is the name of a variable in the program. If variablename is an array element, then the array must be dimensioned before the VARPTR$ function is used. The array must be an array of variable-length strings. ──────────────────────────────────────────────────────────────────────────── NOTE To guarantee correct results, use the value of VARPTR$ immediately after invoking the function. ──────────────────────────────────────────────────────────────────────────── ■ Differences From Basica In QuickBASIC programs, VARPTR$ must be used in the DRAW and PLAY statements to execute substrings containing variables. BASICA supports both the VARPTR$ syntax and the syntax containing just the variable name. ■ See Also DRAW, PLAY ■ Example See the DRAW and PLAY statement for examples. ──────────────────────────────────────────────────────────────────────────── VIEW Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Defines screen limits for graphics output ■ Syntax VIEW ««SCREEN» (x1,y1)-(x2,y2) «,«color» «,border»»» ■ Remarks The list below describes the parts of the VIEW statement: ╓┌─┌────────────────────────┌────────────────────────────────────────────────╖ Part Description ────────────────────────────────────────────────────────────────────────── SCREEN When SCREEN is used, the x-and y-coordinates are absolute to the screen, not relative to the border of the physical viewport. Only graphics within the viewport are plotted. When SCREEN is Part Description ────────────────────────────────────────────────────────────────────────── within the viewport are plotted. When SCREEN is omitted, all points are plotted relative to the viewport (x1 and x2 are added to coordinates before plotting the point). (x1,y1) - (x2,y2) Indicates a rectangular area on the screen. The placeholders x1, y1, x2, and y2 are numeric expressions that are the coordinates of diagonally opposite corners of the area. color The color attribute of the color used to fill the area. If you omit color, the area is not filled. border Any numeric expression in this area draws a line around the viewport if space is available. If you omit border, no border is drawn. ────────────────────────────────────────────────────────────────────────── The VIEW statement defines a "physical viewport," or a rectangular section of the screen into which graphics can be mapped. All coordinates used in the statement must be within the physical bounds of the screen. If VIEW is given with no arguments, the entire screen is defined as the viewport. RUN and SCREEN also define the entire screen as the viewport and disable any viewports defined with VIEW. ■ Examples The following example contrasts the output after VIEW and VIEW SCREEN are executed: SCREEN 1 'SCREEN option makes all screen coordinates absolute. VIEW SCREEN (10,10)-(200,100) 'This line will not be visible, since its end 'points are outside the viewport. LINE (5,5)-(100,5) PRINT "Press any key to continue." SUSPEND$ = INPUT$(1) 'Wait for a key to be pressed. 'No SCREEN option - all screen coordinates relative to 'this viewport. VIEW (10,10)-(200,100) 'This line is now visible, since its end points 'are added to (10,10). LINE (5,5)-(100,5) You may use multiple VIEW statements. If the newly described viewport is not wholly within the previous viewport, the screen can be reinitialized with the VIEW statement and the new viewport can be defined. If the new viewport is entirely within the previous one, as in the following example, the intermediate VIEW statement is not necessary. This example opens three viewports, each smaller than the previous one. In each case, the points of the line that lie outside the viewport borders are clipped and do not appear on the screen. SCREEN 1 CLS VIEW 'Make the viewport cover most of the screen. VIEW (10,10) - (300,180),,1 CLS LINE (0,0) - (310,190),1 LOCATE 1,11: PRINT "A big viewport" VIEW SCREEN (50,50)-(250,150),,1 CLS 'Note CLS clears only viewport. LINE (300,0)-(0,199),1 LOCATE 9,9: PRINT "A medium viewport" VIEW SCREEN (80,80)-(200,125),,1 CLS CIRCLE (150,100),20,1 LOCATE 11,9: PRINT "A small viewport" ──────────────────────────────────────────────────────────────────────────── VIEW PRINT Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Sets the boundaries of the screen text viewport ■ Syntax VIEW PRINT «topline TO bottomline» ■ Remarks The topline argument is the number of the upper line in the viewport; the bottomline is the number of the lower line. Without topline and bottomline parameters, the VIEW PRINT statement initializes the whole screen area as the text viewport. The number of lines in the screen depends on the screen mode and whether or not the /H option was used when QuickBASIC was started. See the entry for the WIDTH statement and Chapter 3, "File and Device I/O," in Programming in BASIC, for more information. Statements and functions that operate within the defined text viewport include CLS, LOCATE, PRINT, and the SCREEN function. ■ See Also CLS, LOCATE, PRINT, SCREEN Function, VIEW ■ Example See the example for CLS. ──────────────────────────────────────────────────────────────────────────── WAIT Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Suspends program execution while monitoring the status of a machine input port ■ Syntax WAIT portnumber,and-expression«,xor-expression» ■ Remarks The following list describes the arguments of the WAIT statement: Argument Description ────────────────────────────────────────────────────────────────────────── portnumber An integer expression in the range 0-255 that is the number of the port and-expression An integer expression combined with data from the port through an AND operation xor-expression An integer expression combined with data from the port using an XOR operation ────────────────────────────────────────────────────────────────────────── The WAIT statement suspends execution until a specified bit pattern is read from a designated input port. The data read from the port is combined, using an XOR operation, with xor-expression, if it appears. The result is then combined with the and-expression using an AND operation. If the result is zero, BASIC loops back and reads the data at the port again. If the result is nonzero, execution continues with the next statement. If xor-expression is omitted, it is assumed to be 0. ──────────────────────────────────────────────────────────────────────────── WARNING It is possible to enter an infinite loop with the WAIT statement if the input port fails to develop a nonzero bit pattern. In this case, you must manually restart the machine. ──────────────────────────────────────────────────────────────────────────── ■ Example The following example illustrates the WAIT statement: WAIT 32,2 ──────────────────────────────────────────────────────────────────────────── WHILE...WEND Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Executes a series of statements in a loop, as long as a given condition is true ■ Syntax WHILE condition . . . «statements» . . . WEND ■ Remarks If the condition is true (that is, if it does not equal zero), then any intervening statements are executed until the WEND statement is encountered. BASIC then returns to the WHILE statement and checks condition. If it is still true, the process is repeated. If it is not true (or if it equals zero), execution resumes with the statement following the WEND statement. ──────────────────────────────────────────────────────────────────────────── NOTE QuickBASIC's DO...LOOP statement provides a more powerful and flexible loop-control structure. ──────────────────────────────────────────────────────────────────────────── WHILE...WEND loops may be nested to any level. Each WEND matches the most recent WHILE. An unmatched WHILE statement causes an error message that reads WHILE without WEND. An unmatched WEND statement causes an error message that reads WEND without WHILE. ──────────────────────────────────────────────────────────────────────────── NOTE Do not branch into the body of a WHILE...WEND loop without executing the WHILE. This may cause run-time errors or program problems that are difficult to locate. ──────────────────────────────────────────────────────────────────────────── ■ See Also DO...LOOP ■ Example The following fragment performs a bubble sort on the array A$. The second line makes the variable Exchange true by assigning it a nonzero value and thereby forces one pass through the WHILE...WEND loop (this construction is unnecessary with DO...LOOP). When there are no more swaps, all elements of A$ are sorted, the variable Exchange is false (equal to zero), and the program continues execution with the line following the WEND statement. ' Bubble sort of array A$. CONST FALSE=0, TRUE=NOT FALSE Max = UBOUND(A$) Exchange=TRUE ' Force first pass through the array. WHILE Exchange ' Sort until no elements are exchanged. Exchange=FALSE ' Compare the array elements by pairs. When two ' are exchanged, force another pass by setting Exchange ' to TRUE. FOR I = 2 TO Max IF A$(I-1) > A$(I) THEN Exchange=TRUE SWAP A$(I-1),A$(I) END IF NEXT WEND . . . ──────────────────────────────────────────────────────────────────────────── WIDTH Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Assigns an output-line width to a file or device or changes the number of columns and lines displayed on the screen ■ Syntax WIDTH «columns»«,lines» WIDTH {#filenumber | device},width WIDTH LPRINT width ■ Remarks Both files and devices can be assigned an output-line width. The different forms of the WIDTH statement are explained in the following list: ╓┌─┌────────────────────────────────────┌────────────────────────────────────╖ Syntax Description ────────────────────────────────────────────────────────────────────────── Syntax Description ────────────────────────────────────────────────────────────────────────── WIDTH «columns»«,lines» Sets the number of columns and lines to display on the screen. The value of columns must be either 40 or 80. The default value is 80. The value of lines may be 25, 30, 43, 50, or 60, depending on both the display adapter used and the screen mode. The number of lines displayed when the program started will determine the default value. See the SCREEN statement for more information. WIDTH #filenumber, width Sets to width the line width of an output device opened as a file (for example, LPT1: or CONS:). The Syntax Description ────────────────────────────────────────────────────────────────────────── example, LPT1: or CONS:). The filenumber argument is the number associated with the file in the OPEN statement. This form permits altering the width while a file is open, since the statement takes place immediately. WIDTH device,width Sets to width the line width of device (a device file name). The device should be a string expression (for example, "CONS:"). Note that this width assignment is deferred until the next OPEN statement affecting the device; the assignment does not affect output for an already open file. Syntax Description ────────────────────────────────────────────────────────────────────────── an already open file. WIDTH LPRINT width Sets to width the line width of the line printer for use by subsequent LPRINT statements. ────────────────────────────────────────────────────────────────────────── ■ See Also SCREEN Statement ■ Example In the following example, the record width for file #1 (the lineprinter) is set to different widths: OPEN "LPT1:" FOR OUTPUT AS #1 Test$ = "1234567890" WIDTH #1, 3 PRINT #1, Test$ WIDTH #1, 4 PRINT #1, Test$ CLOSE ■ Output 123 456 789 0 1234 5678 90 ──────────────────────────────────────────────────────────────────────────── WINDOW Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Defines the dimensions of the current viewport ■ Syntax WINDOW ««SCREEN» (x1,y1)-(x2,y2)» ■ Remarks The WINDOW statement allows the user to create a customized coordinate system to draw lines, graphs, or objects without being constrained by the screen's physical coordinates (the dimensions of the screen). This is done by redefining the screen-border coordinates with the "view coordinates" (x1, y1) and (x2, y2). These view coordinates are single-precision numbers. WINDOW defines the section of the view coordinate system that is mapped to the physical coordinates of the screen. All subsequent graphics statements use these new view coordinates and are displayed within the current viewport. (The size of the viewport can be changed with the VIEW statement.) Either the RUN statement or WINDOW with no arguments disables the window transformation. The WINDOW SCREEN variant inverts the normal Cartesian direction of the y-coordinate, so y values go from negative to positive from top to bottom. Figure R.1 shows the effects of WINDOW and WINDOW SCREEN on a line drawn in screen mode 2. Notice the change in the coordinates of the screen corners. ■ Examples The following example illustrates two lines with the same end-point coordinates. The first is drawn on the default screen, and the second is on a redefined window. SCREEN 2 LINE (100,100) - (150,150), 1 LOCATE 2,20 : PRINT "The line on the default screen" WINDOW SCREEN (100,100) - (200,200) LINE (100,100) - (150,150), 1 LOCATE 8,18 : PRINT"& the same line on a redefined window" Increasing X ───────────────────────── │ ┌─────────────────────────┐ │ │(0,0) (639,0)│ Increasing│ │ │ Y │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │(0,199) (639,199)│ └─────────────────────────┘ / \ / \ / \ WINDOW (-25,-15) / WINDOW SCREEN (-25,-15)-(5,10) LINE (-15,-10)-(-5,-5) LINE (-15,-10)-(-5,-5) / \ / \ / \ / \ Increas ┌─────────────────────────┐ ─────────────── │(-25,10) (5,10)│ │ ┌───────────── │ │ │ │ │(-25,-15) Increasing│ │ (0,0) │ Increasing │ │ Y │ │ │ Y │ │ ∙\(-15, │ │ (-5,-5)∙ │ │ │ \ │ │ / │ │ │ \∙ │ │ / │ │ │ │ │ (-15,-10)∙ │ │ │ │ │(-25,-15) (5,-15)│ │ │ └─────────────────────────┘ │ │(-25,10) ───────────────────────── └───────────── Increasing X Figure R.1 WINDOW and WINDOW SCREEN The following example shows how changing the window size changes the size of a figure drawn on the screen. The effect is one of zooming in and out; as the window gets smaller, the figure appears larger on the screen, until parts of it are finally clipped because they lie outside the window. As the window gets larger, the figure appears smaller on the screen. PRINT "Press ENTER to start." INPUT;"",A$ SCREEN 1 : COLOR 7 'Grey screen. X = 500 : Xdelta = 50 DO DO WHILE X < 525 AND X > 50 X = X + Xdelta 'Change window size. CALL Zoom(X) FOR I = 1 TO 1000 'Delay loop. IF INKEY$ <> "" THEN END 'Stop if key pressed. NEXT LOOP X = X - Xdelta Xdelta = -Xdelta 'Reverse size change. LOOP SUB Zoom(X) STATIC CLS WINDOW (-X,-X)-(X,X) 'Define new window. LINE (-X,-X)-(X,X),1,B 'Draw window border. CIRCLE (0,0),60,1,,,.5 'Draw ellipse with x-radius 60. PAINT (0,0),1 'Paint ellipse. END SUB ──────────────────────────────────────────────────────────────────────────── WRITE Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Sends data to the screen ■ Syntax WRITE «expressionlist» ■ Remarks If expressionlist is omitted, a blank line is written. If expressionlist is included, the values of the expressions are written to the screen. The expressions in the list may be numeric and/or string expressions. They must be separated by commas. When the printed items are written, each item is separated from the last by a comma. Printed strings are delimited by quotation marks. After the last item in the list is printed, BASIC inserts a carriage-return and line-feed. The WRITE statement writes numeric values without leading or trailing spaces. ■ See Also PRINT ■ Example The following example shows the difference between the PRINT and WRITE statements: A=80 : B=90 : C$="That's all." : D=-1.0E-13 WRITE A,B,C$,D PRINT A,B,C$,D ■ Output 80,90,"That's all.",-1E-13 80 90 That's all. -1E-13 ──────────────────────────────────────────────────────────────────────────── WRITE # Statement ──────────────────────────────────────────────────────────────────────────── ■ Action Writes data to a sequential file ■ Syntax WRITE #filenumber,expressionlist ■ Remarks The filenumber is the number used in the OPEN statement. The file must be opened in OUTPUT or APPEND mode. The expressions in the argument expressionlist are string and/or numeric expressions, separated by commas. If you omit the expressionlist, the WRITE # statement writes a blank line to the file. The WRITE # statement, unlike the PRINT # statement, inserts commas between items as they are written to the file. You do not have to put explicit delimiters in the list. A new line is inserted once the last item in the list has been written to the file. If WRITE # attempts to write data to a sequential file restricted by a LOCK statement, an error message appears that reads Permission denied unless the error is trapped by the program. All of BASIC's usual error-handling routines can trap and examine this error. ■ See Also LOCK, OPEN, PRINT #, WRITE ■ Example The output from the following program illustrates the difference between the WRITE # and PRINT # statements: A$ = "VCR, remote control" : B$ = "$399.00" OPEN "PRICES" FOR OUTPUT AS #1 'Open PRICES for writing. PRINT #1,A$,B$ 'Store A$ and B$ in first record with PRINT #. WRITE #1,A$,B$ 'Store A$ and B$ in second record with WRITE #. CLOSE #1 ■ Output VCR, remote control $399.00 "VCR, remote control","$399.00" ════════════════════════════════════════════════════════════════════════════ Glossary CONTROL FLOW FOR...NEXT Repeats statements between FOR and NEXT a specific number of times. EXIT FOR alternative exit from FOR...NEXT DO...LOOP Repeats statements between DO and LOOP, while (until) a condition is(becomes) true. EXIT DO alternative exit from DO...LOOP WHILE...WEND Repeats statements between WHILE and WEND while a given condition is true. IF...THEN...ELSE... END IF Conditionally executes or branches todifferent statements. SELECT CASE Conditionally executes statements based on value of a variable. GOSUB...RETURN Transfers contol to a specific line in a module; control returns to the line following GOSUB. (Old style; SUB is a more powerful alternative.) RUN Restarts current program, or loads and runs another program. CHAIN "program" Passes execution to program specified, then returns. SLEEP Suspends program execution. WAIT Suspends program execution while monitoring status of a machine input port. PROCEDURES SUB...END SUB Mark the beginning and end of a SUBprocedure. EXIT SUB alternative exit from a SUB procedure FUNCTION... END FUNCTION Mark the beginning and end of aFUNCTION procedure. EXIT FUNCTION alternative exit from aFUNCTION procedure DEF FN...END DEF Mark the beginning and end of a DEF FN function. (Old style; FUNCTION is a more powerful alternative.) EXIT DEF alternative exit from aDEF FN function CALL, CALLS Transfers control to a BASIC SUB procedure, or a procedure written in another language and compiled separately. STANDARD I/O BEEP Makes the speaker beep. SOUND Makes a sound of specified frequency and duration. PRINT [USING] Outputs [formatted] text to the screen. WIDTH Sets screen width and number of lines. INKEY$ Reads a character from the keyboard. INP (n) Returns the value read from I/O port n. INPUT Reads string and/or numerical input from the keyboard and stores it in a list ofvariables. INPUT$ Reads characters from the keyboard into a string variable. LINE INPUT Reads an entire line (up to 255 chars) into a string variable. LOCATE Moves cursor to a specified screen row and column. SPC Skips spaces in printed output. TAB Skips to a specified display column. CSRLIN Returns row number of cursor. POS Returns line number of cursor. LPOS Returns position of line printer's print head within the printer buffer. VIEW PRINT Sets top and bottom rows for displaying print. LPRINT [USING] Prints [formatted] data on LPT1: printer. OPEN COMn: Opens and initializes a communications channel for I/O. OUT Sends a byte to a machine I/O port. PEN Returns the light pen coordinates. STICK Returns the x and y coordinates of the two joysticks. STRIG Returns the status of a specified joystick trigger (fire button). READ Returns values from a DATA statement and assigns them to variables. RESTORE Allows DATA statements to be reread from a specified line. FILE I/O OPEN Opens a file for reading or writing records. CLOSE Ends I/O operations to a file. RESET Closes all disk files. PRINT [USING] # Stores a [formatted] list of variables in a file. WRITE # Stores a list of variables as record fields in a file. FIELD Allocates space for variables in a random-access file buffer. WIDTH Specifies a standard length for each record in a file. PUT Stores contents of a variable in a file. INPUT # Reads fields from a record; assigns each to a variable. INPUT$ Reads a string of characters from a file. LINE INPUT # Reads a record and stores it in a string variable. GET Reads data from a file; assigns data to elements of a variable. FREEFILE Returns the next available file number. EOF Tests whether the end of a disk file has been reached. FILEATTR Returns a number indicating the mode in which a file was opened. LOC Gives the current position within a file. LOF Gives the number of bytes in an open file. SEEK (function) Gives the location where the next file I/O operation will occur. SEEK (statement) Sets the byte position for the next file I/O operation. IOCTL Transmits a control data string to a device driver. IOCTL$ Receives a control data string from a device driver. LOCK...UNLOCK Controls access by other processes to all or part of an open file. STRING PROCESSING LEFT$ Returns characters from the left side of the string. RIGHT$ Returns characters from the right side of the string. MID$ function Returns characters from anywhere in the string. MID$ statement Replaces part of a string with another string. LTRIM$ Strips leading blanks from string. RTRIM$ Strips trailing blanks from string. INSTR Searches for a string within another string. LCASE$ Converts a string to all lower-case letters. UCASE$ Converts a string to all upper-case letters. LSET Left-justifies a fixed-length string. RSET Right-justifies a fixed-length string. STR$ Returns the string representation of the decimal value of a numeric expression. HEX$ Returns the string representation of the hex value of a numeric expression. VAL Returns the numeric value of a stringexpression. SPACE$ Returns a string of blanks. STRING$ Returns a string of one repeatedcharacter. LEN Returns the number of characters in a string. ASC Returns the ASCII value of a character. CHR$ Returns the character with the given ASCII value. SADD Returns the address of the specifiedstring expression. GRAPHICS SCREEN Specifies a BASIC screen mode. PSET Sets a pixel to the foreground color. PRESET Sets a pixel to the background color. LINE Draws a straight line or a box. CIRCLE Draws a circle or an ellipse. DRAW Combines BASIC graphics features into a graphics macro language. WINDOW Sets the logical coordinates for a screen viewport. VIEW Specifies a viewport rectangle for graphics output. PMAP Maps pixel physical coordinates to logical coordinates. POINT Returns physical or logical coordinates of cursor, or color number of pixel. COLOR Sets default colors for graphics output. PALETTE Assigns colors to color numbers. PAINT Fills an area with color or a pattern. GET Saves a rectangular area of graphics screen in memory. PUT Displays graphics stored by GET. PCOPY Copies one screen storage page to another. ERROR AND EVENT TRAPPING ON ERROR GOTO line Program branches to line number or line label when error occurs. RESUME Returns control after executing error-handling routine. ERR Returns code for run-time error. ERL Returns line number on which erroroccurred. ERDEV Returns code for last device which caused an error. ERDEV$ Returns name of last device which caused an error. ERROR Simulates occurrence of a BASIC error. ON event GOSUB line Branches to routine labelled with line, whenever event occurs. event ON Enables trapping of event. event OFF ──────────────────────────────────────────────────────────────────────────── Appendix A Keyboard Scan Codes and ASCII Character Codes A.1 Keyboard Scan Codes A.2 ASCII Character Codes A.1 Keyboard Scan Codes The table on the next page shows the DOS keyboard scan codes. These codes are returned by the INKEY$ function. Key combinations with NUL in the Char column return two bytes──a null byte (&H00) followed by the value listed in the Dec and Hex columns. For example, pressing ALT+F1 returns a null byte followed by a byte containing 104 (&H68). ┌────────┬───────┬────────────┬─────────────┬─────────────┬──────────────┐ │ │ │ │ASCII or │ASCII or │ ASCII or │ │ │Scan │ ASCII or │Extended │Extended │ Extended │ │ Key │Code │ Extended │with SHIFT │with CTRL │ with ALT │ ├────────┼───────┼────────────┼─────────────┼─────────────┼──────────────┤ │ │Dec Hex│Dec Hex Char│Dec Hex Char │Dec Hex Char │ Dec Hex Char │ ├────────┼───────┼────────────┼─────────────┼─────────────┼──────────────┤ │ESC │ 1 01 │ 27 1B │ 27 1B │ 27 1B │ │ │1! │ 2 02 │ 49 31 1 │ 33 21 ! │ │ 120 78 NUL │ │2@ │ 3 03 │ 50 32 2 │ 64 40 @ │ 3 03 NUL │ 121 79 NUL │ │3# │ 4 04 │ 51 33 3 │ 35 23 # │ │ 122 7A NUL │ │4$ │ 5 05 │ 52 34 4 │ 36 24 $ │ │ 123 7B NUL │ │5% │ 6 06 │ 53 35 5 │ 37 25 % │ │ 124 7C NUL │ │6^ │ 7 07 │ 54 36 6 │ 94 5E ^ │ 30 IE │ 125 7D NUL │ │7& │ 8 08 │ 55 37 7 │ 38 26 & │ │ 126 7E NUL │ │8* │ 9 09 │ 56 38 8 │ 42 2A * │ │ 127 7F NUL │ │9( │10 0A │ 57 39 9 │ 40 28 ( │ │ 128 80 NUL │ │0) │11 0B │ 48 30 0 │ 41 29 ) │ │ 129 81 NUL │ │-_ │12 0C │ 45 2D - │ 95 5F - │ 31 IF │ 130 82 NUL │ │=+ │13 0D │ 61 3D = │ 43 2B + │ │ 131 83 NUL │ │BKSP │14 0E │ 8 08 │ 8 08 │127 7F │ │ │TAB │15 0F │ 9 09 │ 15 OF NUL│ │ │ │Q │16 10 │113 71 q │ 81 51 Q │ 17 11 │ 16 10 NUL │ │W │17 11 │119 77 w │ 87 57 W │ 23 17 │ 17 11 NUL │ │E │18 12 │101 65 e │ 69 45 E │ 5 05 │ 18 12 NUL │ │R │19 13│114 72 r │ 82 52 R │ 18 12 │ 19 13 NUL │ │T │20 14│116 74 t │ 84 54 T │ 20 14 │ 20 14 NUL │ │Y │21 15│121 79 y │ 89 59 Y │ 25 19 │ 21 15 NUL │ │U │22 16│117 75 u │ 85 55 U │ 21 15 │ 22 16 NUL │ │I │23 17│105 69 i │ 73 49 I │ 9 09 │ 23 17 NUL │ │O │24 18│111 6F o │ 79 4F O │ 15 0F │ 24 18 NUL │ │P │25 19│112 70 p │ 80 50 P │ 16 10 │ 25 19 NUL │ │[{ │26 1A│ 91 5B [ │123 7B { │ 27 1B │ │ │]} │27 1B│ 93 5D ] │125 7D } │ 29 1D │ │ │ENTER │28 1C│ 13 OD CR│ 13 OD CR │ 10 OA LF │ │ │CTRL │29 1D│ │ │ │ │ │A │30 1E│ 97 61 a │ 65 41 A │ 1 01 │ 30 1E NUL │ │S │31 1F│115 73 s │ 83 53 S │ 19 13 │ 31 1F NUL │ │D │32 20│100 64 d │ 68 44 D │ 4 04 │ 32 20 NUL │ │F │33 21│102 66 f │ 70 46 F │ 6 06 │ 33 21 NUL │ │G │34 22│103 67 g │ 71 47 G │ 7 07 │ 34 22 NUL │ │H │35 23│104 68 h │ 72 48 H │ 8 08 │ 35 23 NUL │ │J │36 24│106 6A j │ 74 4A J │ 10 0A │ 36 24 NUL │ │K │37 25│107 6B k │ 75 4B K │ 11 0B │ 37 25 NUL │ │L │38 26│108 6C l │ 76 4C L │ 12 0C │ 38 26 NUL │ │;: │39 27│ 59 3B ; │ 58 3A : │ │ │ │'" │40 28│ 39 27 ' │ 34 22 " │ │ │ │`~ │41 29│ 96 60 ` │126 7E ~ │ │ │ │L SHIFT │42 2A│ │ │ │ │ │\| │43 2B│ 92 5C \ │124 7C | │ 28 1C │ │ │Z │44 2C │122 7A z │ 90 5A Z │ 26 1A │ 44 2C NUL │ │X │45 2D │120 78 x │ 88 58 X │ 24 18 │ 45 2D NUL │ │C │46 2E │ 99 63 c │ 67 43 C │ 3 03 │ 46 2E NUL │ │V │47 2F │118 76 v │ 86 56 V │ 22 16 │ 47 2F NUL │ │B │48 30 │ 98 62 b │ 66 42 B │ 2 OE │ 48 30 NUL │ │N │49 31 │110 6E n │ 78 4E N │ 14 OD │ 49 31 NUL │ │M │50 32 │109 6D m │ 77 4D M │ 13 │ 50 32 NUL │ │,< │51 33 │ 44 2C ' │ 60 3C < │ │ │ │.> │52 34 │ 46 2E . │ 62 3E > │ │ │ │/? │53 35 │ 47 2F / │ 63 3F ? │ │ │ │R SHIFT │54 36 │ │ │ │ │ │* PRTSC │55 37 │ 42 2A * │ INT 5 │ 16 10 │ │ │ALT │56 38 │ │ │ │ │ │SPACE │57 39 │ 32 20 SPC│ 32 20 SPC│ 32 20 SPC │ 32 20 SPC │ │CAPS │58 3A │ │ │ │ │ │F1 │59 3B │ 59 3B NUL│ 84 54 NUL│ 94 5E NUL │ 104 68 NUL │ │F2 │60 3C │ 60 3C NUL│ 85 55 NUL│ 95 5F NUL │ 105 69 NUL │ │F3 │61 3D │ 61 3D NUL│ 86 56 NUL│ 96 60 NUL │ 106 6A NUL │ │F4 │62 3E │ 62 3E NUL│ 87 57 NUL│ 97 61 NUL │ 107 6B NUL │ │F5 │63 3F │ 63 3F NUL│ 88 58 NUL│ 98 62 NUL │ 108 6C NUL │ │F6 │64 40 │ 64 40 NUL│ 89 59 NUL│ 99 63 NUL │ 109 6D NUL │ │F7 │65 41 │ 65 41 NUL│ 90 5A NUL│100 64 NUL │ 110 6E NUL │ │F8 │66 42 │ 66 46 NUL│ 91 5B NUL│101 65 NUL │ 111 6F NUL │ │F9 │67 43 │ 67 43 NUL│ 92 5C NUL│102 66 NUL │ 112 70 NUL │ │F10 │68 44 │ 68 44 NUL│ 93 5D NUL│103 67 NUL │ 113 71 NUL │ │NUM │69 45 │ │ │ │ │ │SCROLL │70 46 │ │ │ │ │ │HOME │71 47 │ 71 47 NUL │ 55 37 7 │119 77 NUL │ │ │UP │72 48 │ 72 48 NUL │ 56 38 8 │ │ │ │PGUP │73 49 │ 73 49 NUL │ 57 39 9 │132 84 NUL │ │ │GREY- │74 4A │ 45 2D - │ 45 2D - │ │ │ │LEFT │75 4B │ 75 4B NUL │ 52 34 4 │115 73 NUL │ │ │CENTER │76 4C │ │ 53 35 5 │ │ │ │RIGHT │77 4D │ 77 4D NUL │ 54 36 6 │116 74 NUL │ │ │GREY+ │78 4E │ 43 2B + │ 43 2b + │ │ │ │END │79 4F │ 79 4F NUL │ 49 31 1 │117 75 NUL │ │ │DOWN │80 50 │ 80 50 NUL │ 50 32 2 │ │ │ │PGDN │81 51 │ 81 51 NUL │ 51 33 3 │118 76 NUL │ │ │INS │82 52 │ 82 52 NUL │ 48 30 0 │ │ │ │DEL │83 53 │ 83 53 NUL │ 46 2E . │ │ │ └────────┴───────┴────────────┴─────────────┴─────────────┴──────────────┘ ┌──────────────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │Ctrl Dec Hex Char Code│ │Dec Hex Char│ │Dec Hex Char│ │Dec Hex Char│ ├────┬───┬───┬────┬────┤ ├───┬───┬────┤ ├───┬───┬────┤ ├───┬───┬────┤ │ ^@ │ 0│00 │ │ NUL│ │ 32│ 20│ │ │ 64│40 │ @ │ │ 96│60 │ ` │ │ ^A │ 1│01 │ │ SOH│ │ 33│ 21│ ! │ │ 65│41 │ A │ │ 97│61 │ a │ │ ^B │ 2│02 │ │ STX│ │ 34│ 22│ " │ │ 66│42 │ B │ │ 98│62 │ b │ │ ^C │ 3│03 │ │ ETX│ │ 35│ 23│ # │ │ 67│43 │ C │ │ 99│63 │ c │ │ ^D │ 4│04 │ │ EOT│ │ 36│ 24│ $ │ │ 68│44 │ D │ │100│64 │ d │ │ ^E │ 5│05 │ │ ENQ│ │ 37│ 25│ % │ │ 69│45 │ E │ │101│65 │ e │ │ ^F │ 6│06 │ │ ACK│ │ 38│ 26│ & │ │ 70│46 │ F │ │102│66 │ f │ │ ^G │ 7│07 │ │ BEL│ │ 39│ 27│ ' │ │ 71│47 │ G │ │103│67 │ g │ │ ^H │ 8│08 │ │ BS │ │ 40│ 28│ ( │ │ 72│48 │ H │ │104│68 │ h │ │ ^I │ 9│09 │ │ HT │ │ 41│ 29│ ) │ │ 73│49 │ I │ │105│69 │ i │ │ ^J │ 10│0A │ │ LF │ │ 42│ 2A│ * │ │ 74│4A │ J │ │106│6A │ j │ │ ^K │ 11│0B │ │ VT │ │ 43│ 2B│ + │ │ 75│4B │ K │ │107│6B │ k │ │ ^L │ 12│0C │ │ FF │ │ 44│ 2C│ , │ │ 76│4C │ L │ │108│6C │ l │ │ ^M │ 13│0D │ │ CR │ │ 45│ 2D│ - │ │ 77│4D │ M │ │109│6D │ m │ │ ^N │ 14│0E │ │ SO │ │ 46│ 2E│ . │ │ 78│4E │ N │ │110│6E │ n │ │ ^O │ 15│0F │ │ SI │ │ 47│ 2F│ / │ │ 79│4F │ O │ │111│6F │ o │ │ ^P │ 16│10 │ │ DLE│ │ 48│ 30│ 0 │ │ 80│50 │ P │ │112│70 │ p │ │ ^Q │ 17│11 │ │ DC1│ │ 49│ 31│ 1 │ │ 81│51 │ Q │ │113│71 │ q │ │ ^R │ 18│12 │ │ DC2│ │ 50│ 32│ 2 │ │ 82│52 │ R │ │114│72 │ r │ │ ^S │ 19│13 │ │ DC3│ │ 51│ 33│ 3 │ │ 83│53 │ S │ │115│73 │ s │ │ ^T │ 20│14 │ │ DC4│ │ 52│ 34│ 4 │ │ 84│54 │ T │ │116│74 │ t │ │ ^U │ 21│15 │ │ NAK│ │ 53│ 35│ 5 │ │ 85│55 │ U │ │117│75 │ u │ │ ^V │ 22│ 16│ │ SYN│ │ 54│ 36│ 6 │ │ 86│ 56│ V │ │118│ 76│ v │ │ ^W │ 23│ 17│ │ ETB│ │ 55│ 37│ 7 │ │ 87│ 57│ W │ │119│ 77│ w │ │ ^X │ 24│ 18│ │ CAN│ │ 56│ 38│ 8 │ │ 88│ 58│ X │ │120│ 78│ x │ │ ^Y │ 25│ 19│ │ EM │ │ 57│ 39│ 9 │ │ 89│ 59│ Y │ │121│ 79│ y │ │ ^Z │ 26│ 1A│ │ SUB│ │ 58│ 3A│ : │ │ 90│ 5A│ Z │ │122│ 7A│ z │ │ ^[ │ 27│ 1B│ │ ESC│ │ 59│ 3B│ ; │ │ 91│ 5B│ [ │ │123│ 7B│ { │ │ ^\ │ 28│ 1C│ │ FS │ │ 60│ 3C│ < │ │ 92│ 5C│ \ │ │124│ 7C│ | │ │ ^} │ 29│ 1D│ │ GS │ │ 61│ 3D│ = │ │ 93│ 5D│ ] │ │125│ 7D│ } │ │ ^^ │ 30│ 1E│ │ RS │ │ 62│ 3E│ > │ │ 94│ 5E│ ^ │ │126│ 7E│ ~ │ │ ^_ │ 31│ 1F│ │ US │ │ 63│ 3F│ ? │ │ 95│ 5F│ _ │ │127│ 7F│ │ └────┴───┴───┴────┴────┘ └───┴───┴────┘ └───┴───┴────┘ └───┴───┴────┘ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │Dec Hex Char│ │Dec Hex Char│ │Dec Hex Char│ │Dec Hex Char│ ├───┬───┬────┤ ├───┬───┬────┤ ├───┬───┬────┤ ├───┬───┬────┤ │128│ 80│ Ç │ │160│ A0│ á │ │192│ C0│ └ │ │224│ E0│ α │ │129│ 81│ ü │ │161│ A1│ í │ │193│ C1│ ┴ │ │225│ E1│ ß │ │130│ 82│ é │ │162│ A2│ ó │ │194│ C2│ ┬ │ │226│ E2│ Γ │ │131│ 83│ â │ │163│ A3│ ú │ │195│ C3│ ├ │ │227│ E3│ π │ │132│ 84│ ä │ │164│ A4│ ñ │ │196│ C4│ ─ │ │228│ E4│ Σ │ │133│ 85│ à │ │165│ A5│ Ñ │ │197│ C5│ ┼ │ │229│ E5│ σ │ │134│ 86│ å │ │166│ A6│ ª │ │198│ C6│ ╞ │ │230│ E6│ µ │ │135│ 87│ ç │ │167│ A7│ º │ │199│ C7│ ╟ │ │231│ E7│ τ │ │136│ 88│ ê │ │168│ A8│ ¿ │ │200│ C8│ ╚ │ │232│ E8│ Φ │ │137│ 89│ ë │ │169│ A9│ ⌐ │ │201│ C9│ ╔ │ │233│ E9│ Θ │ │138│ 90│ è │ │170│ AA│ ¬ │ │202│ CA│ ╩ │ │234│ EA│ Ω │ │139│ 91│ ï │ │171│ AB│ ½ │ │203│ CB│ ╦ │ │235│ EB│ δ │ │140│ 92│ î │ │172│ AC│ ¼ │ │204│ CC│ ╠ │ │236│ EC│ ∞ │ │141│ 93│ ì │ │173│ AD│ ¡ │ │205│ CD│ ═ │ │237│ ED│ φ │ │142│ 94│ Ä │ │174│ AE│ « │ │206│ CE│ ╬ │ │238│ EE│ ε │ │143│ 95│ Å │ │175│ AF│ » │ │207│ CF│ ╧ │ │239│ EF│ ∩ │ │144│ 96│ É │ │176│ B0│ ░ │ │208│ D0│ ╨ │ │240│ F0│ ≡ │ │145│ 97│ æ │ │177│ B1│ ▒ │ │209│ D1│ ╤ │ │241│ F1│ ± │ │146│ 98│ Æ │ │178│ B2│ ▓ │ │210│ D2│ ╥ │ │242│ F2│ ≥ │ │147│ 99│ ô │ │179│ B3│ │ │ │211│ D3│ ╙ │ │243│ F3│ ≤ │ │148│ 9A│ ö │ │180│ B4│ ┤ │ │212│ D4│ ╘ │ │244│ F4│ ⌠ │ │149│ 9B│ ò │ │181│ B5│ ╡ │ │213│ D5│ ╒ │ │245│ F5│ ⌡ │ │150│ 96│ û │ │182│ B6│ ╢ │ │214│ D6│ ╓ │ │246│ F6│ ÷ │ │151│ 97│ ù │ │183│ B7│ ╖ │ │215│ D7│ ╫ │ │247│ F7│ ≈ │ │152│ 98│ ÿ │ │184│ B8│ ╕ │ │216│ D8│ ╪ │ │248│ F8│ ° │ │153│ 99│ Ö │ │185│ B9│ ╣ │ │217│ D9│ ≈ │ │249│ F9│ ∙ │ │154│ 9A│ Ü │ │186│ BA│ ║ │ │218│ DA│ ┌ │ │250│ FA│ · │ │155│ 9B│ ¢ │ │187│ BB│ ╗ │ │219│ DB│ █ │ │251│ FB│ √ │ │156│ 9C│ £ │ │188│ BC│ ╝ │ │220│ DC│ ▄ │ │252│ FC│ ⁿ │ │157│ 9D│ ¥ │ │189│ BD│ ╜ │ │221│ DD│ ▌ │ │253│ FD│ ² │ │158│ 9E│ ₧ │ │190│ BE│ ╛ │ │222│ DE│ ▐ │ │254│ FE│ ■ │ │159│ 9F│ ƒ │ │191│ BF│ ┐ │ │223│ DF│ ▀ │ │255│ FF│ │ └───┴───┴────┘ └───┴───┴─┴──┘ └───┴───┴────┘ └───┴───┴────┘ A.2 ASCII Character Codes ╓┌─┌───────────┌────────────┌───────────┌────────────────────────────────────╖ Number Char Dec Hex Control ────────────────────────────────────────────────────────────────────────── 0 00H NUL (Null) 1 01H SOH (Start of heading) 2 02H STX (Start of text) 3 03H ETX (End of text) 4 04H EOT (End of transmission) 5 05H ENQ (Enquiry) 6 06H ACK (Acknowledge) 7 07H BEL (Bell) Number Char Dec Hex Control ────────────────────────────────────────────────────────────────────────── 7 07H BEL (Bell) 8 08H BS (Backspace) 9 09H HT (Horizontal tab) 10 0AH LF (Linefeed) 11 0BH VT (Vertical tab) 12 0CH FF (Formfeed) 13 0DH CR (Carriage return) 14 EH SO (Shift out) 15 0FH SI (Shift in) 16 10H DLE (Data link escape) 17 11H DC1 (Device control 1) 18 12H DC2 (Device control 2) 19 13H DC3 (Device control 3) 20 14H DC4 (Device control 4) 21 15H NAK (Negative acknowledge) 22 16H SYN (Synchronous idle) 23 17H ETB (End transmission block) 24 18H CAN (Cancel) Number Char Dec Hex Control ────────────────────────────────────────────────────────────────────────── 24 18H CAN (Cancel) 25 19H EM (End of medium) 26 1AH SUB (Substitute) 27 1BH ESC (Escape) 28 1CH FS (File separator) 29 1DH GS (Group separator) 30 1EH RS (Record separator) 31 1FH US (Unit separator) 32 20H ! 33 21H " 34 22H # 35 23H $ 36 24H % 37 25H & 38 26H ' 39 27H ( 40 28H ) 41 29H Number Char Dec Hex Control ────────────────────────────────────────────────────────────────────────── ) 41 29H * 42 2AH + 43 2BH , 44 2CH - 45 2DH . 46 2EH / 47 2FH 0 48 30H 1 49 31H 2 50 32H 3 51 33H 4 52 34H 5 53 35H 6 54 36H 7 55 37H 8 56 38H 9 57 39H : 58 3AH Number Char Dec Hex Control ────────────────────────────────────────────────────────────────────────── : 58 3AH ; 59 3BH < 60 3CH = 61 3DH > 62 3EH ? 63 3FH @ 64 40H A 65 41H B 66 42H C 67 43H D 68 44H E 69 45H F 70 46H G 71 47H H 72 48H I 73 49H J 74 4AH K 75 4BH Number Char Dec Hex Control ────────────────────────────────────────────────────────────────────────── K 75 4BH L 76 4CH M 77 4DH N 78 4EH O 79 4FH P 80 50H Q 81 51H R 82 52H S 83 53H T 84 54H U 85 55H V 86 56H W 87 57H X 88 58H Y 89 59H Z 90 5AH [ 91 5BH \ 92 5CH Number Char Dec Hex Control ────────────────────────────────────────────────────────────────────────── \ 92 5CH ] 93 5DH ^ 94 5EH _ 95 5FH g 96 60H a 97 61H b 98 62H c 99 63H d 100 64H e 101 65H f 102 66H g 103 67H h 104 68H i 105 69H j 106 6AH k 107 6BH l 108 6CH m 109 6DH Number Char Dec Hex Control ────────────────────────────────────────────────────────────────────────── m 109 6DH n 110 6EH o 111 6FH p 112 70H q 113 71H r 114 72H s 115 73H t 116 74H u 117 75H v 118 76H w 119 77H x 120 78H y 121 79H z 122 7AH { 123 7BH | 124 7CH } 125 7DH ~ 126 7EH Number Char Dec Hex Control ────────────────────────────────────────────────────────────────────────── ~ 126 7EH 127 7FH DEL (Delete) Ç 128 80H ü 129 81H é 130 82H â 131 83H ä 132 84H à 133 85H å 134 86H ç 135 87H ê 136 88H ë 137 89H è 138 8AH ï 139 8BH î 140 8CH ì 141 8DH Ä 142 8EH Å 143 8FH Number Char Dec Hex Control ────────────────────────────────────────────────────────────────────────── Å 143 8FH É 144 90H æ 145 91H Æ 146 92H ô 147 93H ö 148 94H ò 149 95H û 150 96H ù 151 97H ÿ 152 98H Ö 153 99H Ü 154 9AH ¢ 155 9BH £ 156 9CH ¥ 157 9DH ₧ 158 9EH ƒ 159 9FH á 160 A0H Number Char Dec Hex Control ────────────────────────────────────────────────────────────────────────── á 160 A0H í 161 A1H ó 162 A2H ú 163 A3H ñ 164 A4H Ñ 165 A5H ª 166 A6H º 167 A7H ¿ 168 A8H ⌐ 169 A9H ¬ 170 AAH ½ 171 ABH ¼ 172 ACH ¡ 173 ADH « 174 AEH » 175 AFH ░ 176 B0H ▒ 177 B1H Number Char Dec Hex Control ────────────────────────────────────────────────────────────────────────── ▒ 177 B1H ▓ 178 B2H │ 179 B3H ┤ 180 B4H ╡ 181 B5H ╢ 182 B6H ╖ 183 B7H ╕ 184 B8H ╣ 185 B9H ║ 186 BAH ╗ 187 BBH ╝ 188 BCH ╜ 189 BDH ╛ 190 BEH ┐ 191 BFH └ 192 C0H ┴ 193 C1H ┬ 194 C2H Number Char Dec Hex Control ────────────────────────────────────────────────────────────────────────── ┬ 194 C2H ├ 195 C3H ─ 196 C4H ┼ 197 C5H ╞ 198 C6H ╟ 199 C7H ╚ 200 C8H ╔ 201 C9H ╩ 202 CAH ╦ 203 CBH ╠ 204 CCH ═ 205 CDH ╬ 206 CEH ╧ 207 CFH ╨ 208 D0H ╤ 209 D1H ╥ 210 D2H ╙ 211 D3H Number Char Dec Hex Control ────────────────────────────────────────────────────────────────────────── ╙ 211 D3H ╘ 212 D4H ╒ 213 D5H ╓ 214 D6H ╫ 215 D7H ╪ 216 D8H ┘ 217 D9H ┌ 218 DAH █ 219 DBH ▄ 220 DCH ▌ 221 DDH ▐ 222 DEH ▀ 223 DFH 224 E0H ß 225 E1H Γ 226 E2H π 227 E3H Σ 228 E4H Number Char Dec Hex Control ────────────────────────────────────────────────────────────────────────── Σ 228 E4H σ 229 E5H µ 230 E6H τ 231 E7H Φ 232 E8H Θ 233 E9H Ω 234 EAH δ 235 EBH ∞ 236 ECH φ 237 EDH ε 238 EEH ∩ 239 EFH ≡ 240 F0H ± 241 F1H ≥ 242 F2H ≤ 243 F3H ⌠ 244 F4H ⌡ 245 F5H Number Char Dec Hex Control ────────────────────────────────────────────────────────────────────────── ⌡ 245 F5H ÷ 246 F6H ≈ 247 F7H ° 248 F8H ∙ 249 F9H · 250 FAH √ 251 FBH ⁿ 252 FCH ² 253 FDH ■ 254 FEH 255 FFH ────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Appendix B Error Messages B.1 Error-Message Display B.2 Invocation, Compile-Time, and Run-Time Error Messages B.3 LINK Error Messages B.4 LIB Error Messages During development of a BASIC program with QuickBASIC, the following types of errors can occur: ■ Invocation errors ■ Compile-time errors ■ Link-time errors ■ Run-time errors Each type of error is associated with a particular step in the program development process. Invocation errors occur when you invoke QuickBASIC with the QB or BC commands. Compile-time errors (and warnings) occur during compilation, and run-time errors occur when the program is executing. Link-time errors occur only when you use the LINK command to link object files created with BC or other language compilers. Section B.2 lists alphabetically the invocation, compile-time, and run-time error messages, along with any error codes that are assigned. Table B.1 lists the run-time error messages and error codes in numerical order. Section B.3 lists the Microsoft Overlay Linker error messages, and Section B.4, the Microsoft Library Manager error messages. B.1 Error-Message Display When a run-time error occurs within the QuickBASIC environment (with default screen options), the error message appears in a dialog box and the cursor is placed on the line where the error occurred. In stand-alone executable programs (that is, programs that are executed by entering the base name of the executable file at the system prompt), the run-time system prints the error messages followed by an address, unless the /D, /E, or /W option is specified on the BC command line. In those cases, the error message is followed by the number of the line in which the error occurred. The standard forms of this type of error message are as follows: Error n in module module-name at address segment:offset and Error n in line linenumber of module module-name at address segment:offset An ERR code is listed for some errors. If an error occurs, the value returned by ERR is set to the appropriate code when an error-trapping subroutine is entered. (Error-trapping routines are entered via the ON ERROR statement.) The ERR value remains unchanged until a RESUME statement returns control to the main program. See Chapter 6, "Error and Event Trapping," in Programming in BASIC for more information. Table B.1 lists the error codes in numerical order. See the alphabetical listing for explanations of the errors. Table B.1 Run-Time Error Codes ╓┌─┌───────────┌────────────────────────┌───────────┌────────────────────────╖ Code Description Code Description ────────────────────────────────────────────────────────────────────────── 2 Syntax error 53 File not found 3 RETURN without GOSUB 54 Bad file mode 4 Out of DATA 55 File already open 5 Illegal function call 56 FIELD statement active 6 Overflow 57 Device I/O error 7 Out of memory 58 File already exists 9 Subscript out of range 59 Bad record length 10 Duplicate definition 61 Disk full 11 Division by zero 62 Input past end of file Code Description Code Description ────────────────────────────────────────────────────────────────────────── 13 Type mismatch 63 Bad record number 14 Out of string space 64 Bad file name 16 String formula too 67 Too many files complex 19 No RESUME 68 Device unavailable 20 RESUME without error 69 Communication-buffer overflow 24 Device timeout 70 Permission denied 25 Device fault 71 Disk not ready 27 Out of paper 72 Disk-media error Code Description Code Description ────────────────────────────────────────────────────────────────────────── 39 CASE ELSE expected 73 Advanced feature unavailable 40 Variable required 74 Rename across disks 50 FIELD overflow 75 Path/File access error 51 Internal error 76 Path not found 52 Bad file name or number ────────────────────────────────────────────────────────────────────────── QYInvocation Error B.2 Invocation, Compile-Time, and Run-Time Error Messages Advanced feature unavailable You are attempting to use a feature of QuickBASIC that is available with another version of BASIC, or supported only under a later version of DOS. (Compile-time or run-time error) ERR code: 73 Argument-count mismatch You are using an incorrect number of arguments with a BASIC subprogram or function. (Compile-time error) Array already dimensioned This error can be caused by any of the following: ■ More than one DIM statement for the same static array. ■ A DIM statement after the initial use of an array. Dynamic arrays must be deallocated with the ERASE statement before they can be redimensioned with DIM; dynamic arrays may also be redimensioned with the REDIM statement. ■ An OPTION BASE statement that occurs after an array is dimensioned. (Compile-time or run-time error) Array not defined An array is referenced but never defined. (Compile-time error) Array not dimensioned An array is referenced but not dimensioned. If you are compiling the program with BC, this error is not "fatal"; the program will execute, although program results may be incorrect. (Compile-time warning) Array too big There is not enough user data space to accommodate the array declaration. Reduce the size of the array or use the ¢DYNAMIC metacommand. You may also get this error if the array size exceeds 64K, the array is not dynamic, and the /AH option is not used. Reduce the size of the array, or make the array dynamic and use the /AH command-line option. (Compile-time error) AS clause required A variable declared with an AS clause is referenced without one. If the first declaration of a variable has an AS clause, every subsequent DIM, REDIM, SHARED, and COMMON statement that references that variable must have an AS clause. (Compile-time error) AS clause required on first declaration A variable that has not been declared using an AS clause is being referenced with an AS clause. (Compile-time error) AS missing The compiler expects an AS keyword, as in OPEN "FILENAME" FOR INPUT AS #1. (Compile-time error) Asterisk missing The asterisk is missing from a string definition in a user type. (Compile-time error) Bad file mode This error occurs in the following situations: ■ The program tries to use PUT or GET with a sequential file or execute an OPEN statement with a file mode other than I, O, or R. ■ The program tries to use a FIELD statement with a file not opened for random access. ■ The program tries to print to a file opened for input. ■ The program tries to read from a file opened for output or appending. ■ QuickBASIC tries to use an include file previously saved in compressed format. Include files must be saved in text format. Reload the include file, save it in text format, then try to run the program again. ■ You try to load a corrupt binary program. (Run-time error) ERR code: 54 Bad file name An illegal form is used for the file name with LOAD, SAVE, KILL, or OPEN (for example, the file name has too many characters). (Run-time error) ERR code: 64 Bad file name or number A statement or command references a file with a file name or number that is not specified in the OPEN statement or is out of the range of file numbers specified earlier in the program. (Run-time error) ERR code: 52 Bad record length A GET or PUT statement that specified a record variable whose length did not match the record length specified in the corresponding OPEN statement was executed. (Run-time error) ERR code: 59 Bad record number In a PUT or GET statement, the record number is less than or equal to zero. (Run-time error) ERR code: 63 BASE missing QuickBASIC expected the keyword BASE here, as in OPTION BASE. (Compile-time error) Binary source file The file you have attempted to compile is not an ASCII file. All source files saved by BASICA should be saved with the ,A option. QuickBASIC also uses this message to warn you when you try to use the /ZI or /ZD CodeView options with binary source files. (Compile-time error) Block IF without END IF There is no corresponding END IF in a block IF construct. (Compile-time error) Buffer size expected after /C: You must specify a buffer size after the /C option. (BC invocation error) BYVAL allowed only with numeric arguments BYVAL does not accept string or record arguments. (Compile-time error) /C: buffer size too large The maximum size of the communications buffer is 32,767 bytes. (BC invocation error) Cannot continue While debugging, you have made a change that prevents execution from continuing. (Run-time error) Cannot find file (filename). Input path: This error occurs when QuickBASIC cannot find a Quick library or utility (BC.EXE, LINK.EXE, LIB.EXE, or QB.EXE) required by the program. Enter the correct path name, or press CTRL+C to return to the DOS prompt. (QB invocation error) Cannot generate listing for BASIC binary source files You are attempting to compile a binary source file with the BC command and the /A option. Recompile without the /A option. (BC invocation error) Cannot start with `FN' You used "FN" as the first two letters of a subprogram or variable name. "FN" can only be used as the first two letters when calling a DEF FN function. (Compile-time error) CASE ELSE expected No matching case was found for an expression in a SELECT CASE statement. (Run-time error) ERR code: 39 CASE without SELECT The first part of a SELECT CASE statement is missing or misspelled. (Compile-time error) Colon expected after /C A colon is required between the option and the buffer size argument. (BC invocation error) Comma missing QuickBASIC expects a comma. (Compile-time error) COMMON and DECLARE must precede executable statements A COMMON statement or a DECLARE statement is misplaced. COMMON and DECLARE statements must appear before any executable statements. All BASIC statements are executable except the following: ■ COMMON ■ DEFtype ■ DIM (for static arrays) ■ OPTION BASE ■ REM ■ TYPE ■ All metacommands (Compile-time error) COMMON in Quick library too small More common variables are specified in the module than in the currently loaded Quick library. (Compile-time error) COMMON name illegal QuickBASIC encountered an illegal /blockname/ specification (for example, a blockname that is a BASIC reserved word) in a named COMMON block. (Compile-time error). Communication-buffer overflow During remote communications, the receive buffer overflowed. The size of the receive buffer is set by the /C command line option or the RB option in the OPEN COM statement. Try checking the buffer more frequently (with the LOC function) or emptying it more often (with the INPUT$ function). (Run-time error) ERR code: 69 CONST/DIM SHARED follows SUB/FUNCTION CONST and DIM SHARED statements should appear before any subprogram or FUNCTION procedure definitions. If you are compiling your program with BC, this error is not "fatal"; the program will execute, although the results may be incorrect. (Compile-time warning) Control structure in IF...THEN...ELSE incomplete An unmatched NEXT, WEND, END IF, END SELECT, or LOOP statement appears in a single-line IF...THEN...ELSE statement. (Compile-time error) Data-memory overflow There is too much program data to fit in memory. This error is often caused by too many constants, or too much static array data. If you are using the BC command, or the Make EXE File or Make Library commands, try turning off any debugging options. If memory is still exhausted, break your program into parts and use the CHAIN statement or use the ¢DYNAMIC metacommand. (Compile-time error) DECLARE required An implicit SUB or FUNCTION procedure call appears before the procedure definition. (An implicit call does not use the CALL statement.) All procedures must be defined or declared before they are implicitly called. (Compile-time error) DEF FN not allowed in control statements DEF FN function definitions are not permitted inside control constructs such as IF...THEN...ELSE and SELECT CASE. (Compile-time error) DEF without END DEF There is no corresponding END DEF in a multiline function definition. (Compile-time error) DEFtype character specification illegal A DEFtype statement is entered incorrectly. DEF can only be followed by LNG, DBL, INT, SNG, STR, or (for user-defined functions) a blank space. (Compile-time error) Device fault A device has returned a hardware error. If this message occurs while data are being transmitted to a communications file, it indicates that the signals being tested with the OPEN COM statement were not found in the specified period of time. (Run-time error) ERR code: 25 Device I/O error An I/O error occurred on a device I/O operation. The operating system cannot recover from the error. (Run-time error) ERR code: 57 Device timeout The program did not receive information from an I/O device within a predetermined amount of time. (Run-time error) ERR code: 24 Device unavailable The device you are attempting to access is not on line or does not exist. (Run-time error) ERR code: 68 Disk full There is not enough room on the disk for the completion of a PRINT, WRITE, or CLOSE operation. This error can also occur if there is not enough room for QuickBASIC to write out an object or executable file. (Run-time error) ERR code: 61 Disk-media error Disk-drive hardware has detected a physical flaw on the disk. (Run-time error) ERR code: 72 Disk not ready The disk-drive door is open, or no disk is in the drive. (Run-time error) ERR code: 71 Division by zero A division by zero is encountered in an expression, or an exponentiation operation results in zero being raised to a negative power. (Compile-time or run-time error) ERR code: 11 DO without LOOP The terminating LOOP clause is missing from a DO...LOOP statement. (Compile-time error) Document too large Your document exceeds QuickBASIC's internal limit. Divide the document into separate files. Duplicate definition You are using an identifier that has already been defined. For example, you are attempting to use the same name in a CONST statement and as a variable definition, or the same name for a procedure and a variable. This error also occurs if you attempt to redimension an array. You must use DIM or REDIM when redimensioning dynamic arrays. (Compile-time or run-time error) ERR code: 10 Duplicate label Two program lines are assigned the same number or label. Each line number or label in a module must be unique. (Compile-time error) Dynamic array element illegal Dynamic array elements are not allowed with VARPTR$. (Compile-time error) Element not defined A user-defined type element is referenced but not defined. For example, if the user-defined type MYTYPE contained elements A, B, and C, then an attempt to use the variable D as an element of MYTYPE would cause this message to appear. (Compile-time error) ELSE without IF An ELSE clause appears without a corresponding IF. Sometimes this error is caused by incorrectly nested IF statements. (Compile-time error) ELSEIF without IF An ELSEIF statement appears without a corresponding IF. Sometimes this error is caused by incorrectly nested IF statements. (Compile-time error) END DEF without DEF An END DEF statement has no corresponding DEF statement. (Compile-time error) END IF without block IF The beginning of an IF block is missing. (Compile-time error) END SELECT without SELECT The end of a SELECT CASE statement appears without a beginning SELECT CASE. The beginning of the SELECT CASE statement may be missing or misspelled. (Compile-time error) END SUB or END FUNCTION must be last line in window You are attempting to add code after a procedure. You must either return to the main module or open another module. (Compile-time error) END SUB/FUNCTION without SUB/FUNCTION You deleted the SUB or FUNCTION statement. (Compile-time error) END TYPE without TYPE An END TYPE statement is used outside a TYPE declaration. (Compile-time error) Equal sign missing QuickBASIC expects an equal sign. (Compile-time error) Error during QuickBASIC initialization Several conditions can cause this error. It is most commonly caused when there is not enough memory in the machine to load QuickBASIC. If you are loading a Quick library, try reducing the size of the library. This error may occur when you attempt to use QuickBASIC on unsupported hardware. (QB invocation error) Error in loading file (filename)──Cannot find file This error occurs when redirecting input to QuickBASIC from a file. The input file is not at the location specified on the command line. (QB invocation error) Error in loading file (filename)──Disk I/O error This error is caused by physical problems accessing the disk, for example, if the drive door is left open. (QB invocation error) Error in loading file (filename)──DOS memory-area error The area of memory used by DOS has been written to, either by an assembly language routine or with the POKE statement. (QB invocation error) Error in loading file (filename)──Invalid format You are attempting to load a Quick library that is not in the correct format. This error can occur if you are attempting to use a Quick library created with a previous version of QuickBASIC, if you are trying to use a file that has not been processed with QuickBASIC's Make Library command or the /QU option from LINK, or if you are trying to load a stand-alone (.LIB) library with QuickBASIC. (QB invocation error) Error in loading file (filename)──Out of memory More memory is required than is available. For example, there may not be enough memory to allocate a file buffer. Try reducing the size of your DOS buffers, getting rid of any terminate-and-stay resident programs, or eliminating some device drivers. If you have large arrays, try placing a ¢DYNAMIC metacommand at the top of your program. If you have documents loaded, then unloading them will free some memory. (Run-time error) EXIT DO not within DO...LOOP An EXIT DO statement is used outside of a DO...LOOP statement. (Compile-time error) EXIT not within FOR...NEXT An EXIT FOR statement is used outside of a FOR...NEXT statement. (Compile-time error) Expected: item This is a syntax error. The cursor is positioned at the unexpected item. (Compile-time error) Expression too complex This error is caused when certain internal limitations are exceeded. For example, during expression evaluation, strings that are not associated with variables are assigned temporary locations. A large number of such strings can cause this error to occur. Try simplifying expressions, and assigning strings to variables. (Compile-time error) Extra file name ignored You specified too many files on the command line; the last file name on the line is ignored. (BC invocation error) Far heap corrupt The far-heap memory has been corrupted by one of the following: ■ The QB compiler does not support a terminate-and-stay-resident program resident in DOS. ■ The POKE statement modified areas of memory used by QuickBASIC. (This may modify the descriptor for a dynamic array of numbers or fixed-length strings.) ■ The program called an other-language routine that modified areas of memory used by QuickBASIC. (This may modify the descriptor for a dynamic array of numbers or fixed-length strings. (Compile-time error) FIELD overflow A FIELD statement is attempting to allocate more bytes than were specified for the record length of a random file. (Run-time error) ERR code: 50 FIELD statement active A GET or PUT statement referred to a record variable used in a a file with space previously allocated by the FIELD statement. GET or PUT with a record variable argument may only be used on files where no FIELD statements have been executed. (Run-time error) ERR code: 56 File already exists The file name specified in a NAME statement is identical to a file name already in use on the disk. (Run-time error) ERR code: 58 File already open A sequential-output-mode OPEN statement is issued for a file that is already open, or a KILL statement is given for a file that is open. (Run-time error) ERR code: 55 File not found A FILES, KILL, NAME, OPEN or RUN statement references a file that does not exist. (Run-time error) ERR code: 53 File not found in module module-name at address segment:offset A FILES, KILL, NAME, OPEN or RUN statement references a file that does not exist. This error message is equivalent to the File not found message, but it occurs during execution of compiled programs. The module-name is the name of the calling module. The address is the location of the error in the code. (Run-time error) ERR code: 53 File previously loaded You are attempting to load a file that is already in memory. (Compile-time error) Fixed-length string illegal You are attempting to use a fixed-length string as a formal parameter. (Compile-time error) FOR index variable already in use This error occurs when an index variable is used more than once in nested FOR loops. (Compile-time error) FOR index variable illegal This error is usually caused when an incorrect variable type is used in a FOR-loop index. A FOR-loop index variable must be a simple numeric variable. (Compile-time error) FOR without NEXT Each FOR statement must have a matching NEXT statement. (Compile-time error) Formal parameter specification illegal There is an error in a function or subprogram parameter list. (Compile-time error) Formal parameters not unique A FUNCTION or SUB declaration contains duplicate parameters, as in this example: SUB GetName(A,B,C,A) STATIC. (Compile-time error) Function already defined This error occurs when a previously defined FUNCTION is redefined. (Compile-time error) Function name illegal A BASIC reserved word is used as a user-defined FUNCTION name. (Compile-time error) Function not defined You must declare or define a FUNCTION before using it. (Compile-time error) GOSUB missing The GOSUB is missing from an ON event statement. (Compile-time error) GOTO missing The GOTO is missing from an ON ERROR statement. (Compile-time error) GOTO or GOSUB expected QuickBASIC expects a GOTO or GOSUB statement. (Compile-time error) Help not found Help was requested but not found, and the program contains errors prohibiting QuickBASIC from building a variable table. Press F5 to view the line that caused the error. Identifier cannot end with %, &, !, #, or $ The above suffixes are not allowed in type identifiers, subprogram names, or names appearing in COMMON statements. (Compile-time error) Identifier cannot include period User-defined type identifier and record element names cannot contain periods. The period should only be used as a record variable separator. In addition, a variable name cannot contain a period if the part of the name before the period has been used in an identifier AS usertype clause anywhere in the program. If you have programs that use the period in variable names, it is recommended that you change them to use mixed case instead. For example, variable ALPHA.BETA would become AlphaBeta. (Compile-time error) Identifier expected You are attempting to use a number or a BASIC reserved word where an identifier is expected. (Compile-time error) Identifier too long Identifiers must not be longer than 40 characters. (Compile-time error) Illegal function call A parameter that is out of range is passed to a math or string function. A function-call error can also occur for the following reasons: ■ A negative or unreasonably large subscript is used. ■ A negative number is raised to a power that is not an integer. ■ A negative record number is given when using GET file or PUT file. ■ An improper or out-of-range argument is given to a function. ■ A BLOAD or BSAVE operation is directed to a nondisk device. ■ An I/O function or statement (LOC or LOF, for example) is performed on a device that does not support it. ■ Strings are concatenated to create a string greater than 32,767 characters in length. (Run-time error) ERR code: 5 Illegal in direct mode The statement is valid only within a program and cannot be used in the Immediate window. (Compile-time error) Illegal in procedure or DEF FN The statement is not allowed inside a procedure. (Compile-time error) Illegal number The format of the number does not correspond to a valid number format. You have probably made a typographical error. For example, the number 2p3 will produce this error. (Compile-time error) Illegal outside of SUB, FUNCTION, or DEF FN This statement is not allowed in module-level code. (Compile-time error) Illegal outside of SUB/FUNCTION The statement is not allowed in module-level code or DEF FN functions. (Compile-time error) Illegal outside of TYPE block The element AS type clause is permitted only within a TYPE...END TYPE block. (Compile-time error) Illegal type character in numeric constant A numeric constant contains an inappropriate type-declaration character. (Compile-time error) ¢INCLUDE-file access error The include file named in the ¢INCLUDE metacommand cannot be located. (Compile-time error) Include file too large Your include file exceeds QuickBASIC's internal limit. Break the file into separate files. (Compile-time error) Input file not found The source file you gave on the command line is not in the specified location. (BC invocation error) INPUT missing The compiler expects the keyword INPUT. (Compile-time error) Input past end of file An INPUT statement reads from a null (empty) file or from a file in which all data have already been read. To avoid this error, use the EOF function to detect the end of file. (Run-time error) ERR code: 62 Input runtime module path: This prompt appears if the run-time module BRUN45.EXE is not found. Enter the correct path specification. This error is severe and cannot be trapped. (Run-time error) Integer between 1 and 32767 required The statement requires an integer argument. (Compile-time error) Internal error An internal malfunction occurred in QuickBASIC. Use the Product Assistance Request form included with your documentation to report to Microsoft the conditions under which the message appeared. (Run-time error) ERR code: 51 Internal error near xxxx An internal malfunction occurred in QuickBASIC at location xxxx. Use the Product Assistance Request form included with your documentation to report the conditions under which the message appeared. (Compile-time error) Invalid character QuickBASIC found an invalid character, such as a control character, in the source file. (Compile-time error) Invalid constant An invalid expression is used to assign a value to a constant. Remember that expressions assigned to constants may contain numeric constants, symbolic constants, and any of the arithmetic or logical operators except exponentiation. A string expression assigned to a constant may consist only of a single literal string. (Compile-time error) Invalid DECLARE for BASIC procedure You are attempting to use the DECLARE statement keywords ALIAS, CDECL, or BYVAL with a BASIC procedure. ALIAS, CDECL, and BYVAL can only be used with non-BASIC procedures. (Compile-time error) Label not defined A line label is referenced (in a GOTO statement, for example), but does not occur in the program. (Compile-time error) Label not defined: label A GOTO linelabel statement refers to a nonexistent line label. (Compile-time error) Left parenthesis missing QuickBASIC expected a left parenthesis, or a REDIM statement tried to reallocate space for a scalar. (Compile-time error) Line invalid. Start again An invalid file-name character was used following the path characters "\" (backslash) or ":" (colon). (BC invocation error) Line number or label missing A line number or label is missing from a statement that requires one, for example, GOTO. (Compile-time error) Line too long Lines are limited to 255 characters. (Compile-time error) LOOP without DO The DO starting a DO...LOOP statement is missing or misspelled. (Compile-time error) Lower bound exceeds upper bound The lower bound exceeds the upper bound defined in a DIM statement. (Compile-time error) Math overflow The result of a calculation is too large to be represented in BASIC number format. (Compile-time error) ¢Metacommand error A metacommand is incorrect. If you are compiling the program with BC this error is not "fatal"; the program will execute, although the results may be incorrect. (Compile-time warning) Minus sign missing QuickBASIC expects a minus sign. (Compile-time error) Missing Event Trapping (/W) or Checking Between Statements (/V) option The program contains an ON event statement requiring one of these options. (Compile-time error) Missing On Error (/E) option When using the BC command, programs containing ON ERROR statements must be compiled with the On Error (/E) option. (Compile-time error) Missing Resume Next (/X) option When using the BC command, programs containing RESUME, RESUME NEXT, and RESUME 0 statements must be compiled with the Resume Next (/X) option. (Compile-time error) Module level code too large Your module-level code exceeds QuickBASIC's internal limit. Try moving some of the code into SUB or FUNCTION procedures. (Compile-time error) Module not found. Unload module from program? When loading the program, QuickBASIC did not find the file containing the indicated module. QuickBASIC created an empty module instead. You must delete the empty module before you can run the program. Must be first statement on the line In block IF...THEN...ELSE constructs, IF, ELSE, ELSEIF, and END IF can be preceded only by a line number or label. (Compile-time error) Name of subprogram illegal The error is caused when a subprogram name is a BASIC reserved word, or a subprogram name is used twice. (Compile-time error) Nested function definition A FUNCTION definition appears inside another FUNCTION definition, or inside an IF...THEN...ELSE clause. (Compile-time error) NEXT missing for variable A FOR statement is missing a corresponding NEXT statement. The variable is the FOR-loop index variable. (Compile-time error) NEXT without FOR Each NEXT statement must have a matching FOR statement. (Compile-time error) No line number in module-name at address segment:offset This error occurs when the error address cannot be found in the line-number table during error trapping. This happens if there are no integer line numbers between 0 and 65,527. It may also occur if the line-number table has been accidentally overwritten by the user program. This error is severe and cannot be trapped. (Run-time error) No main module. Choose Set Main Module from the Run menu to select one You are attempting to run the program after you have unloaded the main module. Every program must have a main module. (Compile-time error) No RESUME The end of the program was encountered while the program was in an error-handling routine. A RESUME statement is needed to remedy this situation. (Run-time error) ERR code: 19 Not watchable This error occurs when you are specifying a variable in a watch expression. Make sure the module or procedure in the active View window has access to the variable you want to watch. For example, module-level code cannot access variables that are local to a SUB or FUNCTION. (Run-time error) Numeric array illegal Numeric arrays are not allowed as arguments to VARPTR$. Only simple variables and string array elements are permitted. (Compile-time error) Only simple variables allowed User-defined types and arrays are not permitted in READ and INPUT statements. Array elements that are not of a user-defined type are permitted. (Compile-time error) Operation requires disk You are attempting to load from, or save to, a nondisk device such as the printer or keyboard. (Compile-time error) Option unknown: option You have given an illegal option. (BC invocation error) Out of DATA A READ statement is executed when there are no DATA statements with unread data remaining in the program. (Run-time error) ERR code: 4 Out of data space Try modifying your data space requirements as follows: ■ Use a smaller file buffer in the OPEN statement's LEN clause. ■ Use the ¢DYNAMIC metacommand to create dynamic arrays. Dynamic array data can usually be much larger than static array data. ■ Use fixed-length string arrays instead of variable-length string arrays. ■ Use the smallest data type that will accomplish your task. Use integers whenever possible. ■ Try not to use many small procedures. QuickBASIC must create several bytes of control information for each procedure. ■ Use CLEAR to modify the size of the stack. Use only enough stack space to accomplish your task. ■ Do not use source lines longer than 255 characters. Such lines require allocation of additional text buffer space. (Compile-time or run-time error) Out of memory More memory is required than is available. For example, there may not be enough memory to allocate a file buffer. Try reducing the size of your DOS buffers, or getting rid of any terminate-and-stay-resident programs, or eliminating some device drivers. If you have large arrays, try placing a ¢DYNAMIC metacommand at the top of your program. If you have documents loaded, unloading them will free some memory. (BC invocation, compile-time, or run-time error) ERR code: 7 Out of paper The printer is out of paper or is not turned on. (Run-time error) ERR code: 27 Out of stack space This error can occur when a recursive FUNCTION procedure nests too deeply, or there are too many active subroutine, FUNCTION, and SUB calls. You can use the CLEAR statement to increase the program's allotted stack space. This error cannot be trapped. (Run-time error) Out of string space String variables exceed the allocated amount of string space. (Run-time error) ERR code: 14 Overflow The result of a calculation is too large to be represented within the range allowed for either floating-point or integer numbers. (Run-time error) ERR code: 6 Overflow in numeric constant The numeric constant is too large. (Compile-time error) Parameter type mismatch A subprogram or FUNCTION parameter type does not match the DECLARE statement argument or the calling argument. (Compile-time error) Path not found During an OPEN, MKDIR, CHDIR, or RMDIR operation, DOS was unable to find the path specified. The operation is not completed. (Run-time error) ERR code: 76 Path/File access error During an OPEN, MKDIR, CHDIR, or RMDIR operation, DOS was unable to make a correct connection between the path and file name. The operation is not completed. (Compile-time or run-time error) ERR code: 75 Permission denied An attempt was made to write to a write-protected disk, or to access a locked file. (Run-time error) ERR code: 70 Procedure already defined in Quick library A procedure in the Quick library has the same name as a procedure in your program. (Compile-time error) Procedure too large The procedure has exceeded QuickBASIC's internal limit. Make the procedure smaller by dividing it into several procedures. (Compile-time error) Program-memory overflow You are attempting to compile a program whose code segment is larger than 64K. Try splitting the program into separate modules, or use the CHAIN statement. (Compile-time error) Read error on standard input A system error occurred while reading from the console or a redirected input file. (BC invocation error) Record/string assignment required The string or record variable assignment is missing from the LSET statement. (Compile-time error) Redo from start You have responded to an INPUT prompt with the wrong number or type of items. Retype your response in the correct form. (Run-time error) Rename across disks An attempt was made to rename a file with a new drive designation. This is not allowed. (Run-time prompt) ERR code: 74 Requires DOS 2.10 or later You are attempting to use QuickBASIC with an incorrect version of DOS. (QB invocation or run-time error) RESUME without error A RESUME statement is encountered before an error-trapping routine is entered. (Run-time error) ERR code: 20 RETURN without GOSUB A RETURN statement is encountered for which there is no previous, unmatched GOSUB statement. (Run-time error) ERR code: 3 Right parenthesis missing QuickBASIC expects a right (closing) parenthesis. (Compile-time error) SEG or BYVAL not allowed in CALLS BYVAL and SEG are permitted only in a CALL statement. (Compile-time error) SELECT without END SELECT The end of a SELECT CASE statement is missing or misspelled. (Compile-time error) Semicolon missing QuickBASIC expects a semicolon. (Compile-time error) Separator illegal There is an illegal delimiting character in a PRINT USING or WRITE statement. Use a semicolon or a comma as a delimiter. (Compile-time error) Simple or array variable expected The compiler expects a variable argument. (Compile-time error) Skipping forward to END TYPE statement An error in the TYPE statement has caused QuickBASIC to ignore everything between the TYPE and END TYPE statement. (Compile-time error) Statement cannot occur within $INCLUDE file SUB...END SUB and FUNCTION...END FUNCTION statement blocks are not permitted in include files. Use the Merge command from the File menu to insert the include file into the current module, or load the include file as a separate module. If you load the include file as a separate module, some restructuring may be necessary because shared variables are shared only within the scope of the module. (Compile-time error) Statement cannot precede SUB/FUNCTION definition The only statements allowed before a procedure definition are the statements REM and DEFtype. (Compile-time error) Statement ignored You are using the BC command to compile a program that contains TRON and TROFF statements without using the /D option. This error is not "fatal" ; the program will execute, although the results may be incorrect. (Compile-time warning) Statement illegal in TYPE block The only statements allowed between the TYPE and END TYPE statements are REM and element AS typename. (Compile-time error) Statement unrecognizable You have probably mistyped a BASIC statement. (Compile-time error) Statements/labels illegal between SELECT CASE and CASE Statements and line labels are not permitted between SELECT CASE and the first CASE statement. Comments and statement separators are permitted. (Compile-time error) STOP in module name at address segment:offset A STOP statement was encountered in the program. (Run-time error) String assignment required The string assignment is missing from an RSET statement. (Compile-time error) String constant required for ALIAS The DECLARE statement ALIAS keyword requires a string-constant argument. (Compile-time error) String expression required The statement requires a string-expression argument. (Compile-time error) String formula too complex Either a string formula is too long or an INPUT statement requests more than 15 string variables. Break the formula or INPUT statement into parts for correct execution. (Run-time error) ERR code: 16 String space corrupt This error occurs when an invalid string in string space is being deleted during heap compaction. The probable causes of this error are as follows: ■ A string descriptor or string back pointer has been improperly modified. This may occur if you use an assembly-language subroutine to modify strings. ■ Out-of-range array subscripts are used and string space is inadvertently modified. The Produce Debug Code option can be used at compile time to check for array subscripts that exceed the array bounds. ■ Incorrect use of the POKE and/or DEF SEG statements may modify string space improperly. ■ Mismatched COMMON declarations may occur between two chained programs. (Run-time error) String variable required The statement requires a string-variable argument. (Compile-time error) SUB or FUNCTION missing A DECLARE statement has no corresponding procedure. (Compile-time error) SUB/FUNCTION without END SUB/FUNCTION The terminating statement is missing from a procedure. (Compile-time error) Subprogram error This is a SUB or FUNCTION definition error and is usually caused by one of the following: ■ The SUB or FUNCTION is already defined. ■ The program contains incorrectly nested FUNCTION or SUB statements. ■ The SUB or FUNCTION does not terminate with an END SUB or END FUNCTION statement. (Compile-time error) Subprogram not defined A subprogram is called but never defined. (Compile-time error) Subprograms not allowed in control statements Subprogram FUNCTION definitions are not permitted inside control constructs such as IF...THEN...ELSE and SELECT CASE. (Compile-time error) Subscript out of range An array element was referenced with a subscript that was outside the dimensions of the array, or an element of an undimensioned dynamic array was accessed. This message may be generated if the Debug (/D) option was specified at compile time. You may also get this error if the array size exceeds 64K, the array is not dynamic, and the /AH option was not used. Reduce the size of the array, or make the array dynamic and use the /AH command-line option. (Run-time error) ERR code: 9 Subscript syntax illegal An array subscript contains a syntax error: for example, an array subscript contains both string and integer data types. (Compile-time error) Syntax error Several conditions can cause this error. The most common cause at compile time is a mistyped BASIC keyword or argument. At run-time, it is often caused by an improperly formatted DATA statement. (Compile-time or run-time error) ERR code: 2 Syntax error in numeric constant A numeric constant is not properly formed. (Compile-time error) THEN missing QuickBASIC expects a THEN keyword. (Compile-time error) TO missing QuickBASIC expects a TO keyword. (Compile-time error) Too many arguments in function call Function calls are limited to 60 arguments. (Compile-time error) Too many dimensions Arrays are limited to 60 dimensions. (Compile-time error) Too many files At compile time, this error occurs when include files are nested more than five levels deep. It occurs at run time when the 255-file directory maximum is exceeded by an attempt to create a new file with a SAVE or OPEN statement. (Compile-time or run-time error) ERR code: 67 Too many labels The number of lines in the line list following an ON...GOTO or ON...GOSUB statement exceeds 255 (Compile-time error) or 59 (Run-time error in compiled applications). Too many named COMMON blocks The maximum number of named COMMON blocks permitted is 126. (Compile-time error) Too many TYPE definitions The maximum number of user-defined types permitted is 240. (Compile-time error) Too many variables for INPUT An INPUT statement is limited to 60 variables. (Compile-time error) Too many variables for LINE INPUT Only one variable is allowed in a LINE INPUT statement. (Compile-time error) Type mismatch The variable is not of the required type. For example, you are trying to use the SWAP statement with a string variable and a numeric variable. (Compile-time or run-time error) ERR code: 13 TYPE missing The TYPE keyword is missing from an END TYPE statement. (Compile-time error) Type more than 65535 bytes A user-defined type cannot exceed 64K. (Compile-time error) Type not defined The usertype argument to the TYPE statement is not defined. (Compile-time error) TYPE statement improperly nested User-defined type definitions are not allowed in procedures. (Compile-time error) TYPE without END TYPE There is no END TYPE statement associated with a TYPE statement. (Compile-time error) Typed variable not allowed in expression Variables that are user-defined types are not permitted in expressions such as CALL ALPHA((X)), where X is a user-defined type. (Compile-time error) Unexpected end of file in TYPE declaration There is an end-of-file character inside a TYPE...END TYPE block. Unprintable error An error message is not available for the error condition that exists. This may be caused by an ERROR statement that doesn't have a defined error code. (Run-time error) Unrecognized switch error: "QU" You are attempting to create an .EXE file or Quick library with an incorrect version of the Microsoft Overlay Linker. You must use the linker supplied on the QuickBASIC distribution disks to create an .EXE file or Quick library. (Compile-time error) Valid options: [/RUN] file /AH /B /C:buf /G /NOHI /H /L [lib] /MBF /CMD string This message appears when you invoke QuickBASIC with an invalid option. (QB invocation error) Variable-length string required Only variable-length strings are permitted in a FIELD statement. (Compile-time error) Variable name not unique You are attempting to define the variable x as a user-defined type after x.y has been used. (Compile-time error) Variable required QuickBASIC encountered an INPUT, LET, READ, or SHARED statement without a variable argument. (Compile-time error) Variable required A GET or PUT statement didn't specify a variable when an operation is performed on a file opened in BINARY mode. (Run-time error) ERR code: 40 WEND without WHILE This error is caused when a WEND statement has no corresponding WHILE statement. (Compile-time error) WHILE without WEND This error is caused when a WHILE statement has no corresponding WEND statement. (Compile-time error) Wrong number of dimensions An array reference contains the wrong number of dimensions. (Compile-time error) B.3 LINK Error Messages This section lists and describes error messages generated by the Microsoft Overlay Linker, LINK. Fatal errors cause the linker to stop execution. Fatal error messages have the following format: location : fatal error L1xxx:messagetext Nonfatal errors indicate problems in the executable file. LINK produces the executable file. Nonfatal error messages have the following format: location : error L2xxx: messagetext Warnings indicate possible problems in the executable file. LINK produces the executable file. Warnings have the following format: location : warning L4xxx: messagetext In these messages, location is the input file associated with the error, or LINK if there is no input file. The following error messages may appear when you link object files with LINK: ╓┌─┌───────────┌─────────────────────────────────────────────────────────────╖ Number LINK Error Message ────────────────────────────────────────────────────────────────────────── L1001 option : option name ambiguous A unique option name did not appear after the option indicator (/). For example, the command LINK /N main; generates this error, since LINK cannot tell which of the three options beginning with the letter "N" was intended. L1002 option : unrecognized option name Number LINK Error Message ────────────────────────────────────────────────────────────────────────── L1002 option : unrecognized option name An unrecognized character followed the option indicator (/), as in the following example: LINK /ABCDEF main; L1003 /QUICKLIB, /EXEPACK incompatible You specified two options that cannot be used together: /QUICKLIB and /EXEPACK. L1004 option : invalid numeric value An incorrect value appeared for one of the LINK options. For example, a character string was given for an option that requires a numeric value. L1006 option : stack size exceeds 65535 bytes The value given as a parameter to the /STACKSIZE option Number LINK Error Message ────────────────────────────────────────────────────────────────────────── The value given as a parameter to the /STACKSIZE option exceeds the maximum allowed. L1007 option : interrupt number exceeds 255 For the /OVERLAYINTERRUPT option, a number greater than 255 was given as a value. L1008 option : segment limit set too high The limit on the number of segments allowed was set to greater than 3072 using the /SEGMENTS option. L1009 number : CPARMAXALLOC : illegal value The number specified in the /CPARMAXALLOC option was not in the range 1-65,535. L1020 no object modules specified Number LINK Error Message ────────────────────────────────────────────────────────────────────────── L1020 no object modules specified No object-file names were specified to LINK. L1021 cannot nest response files A response file occurred within a response file. L1022 response line too long A line in a response file was longer than 127 characters. L1023 terminated by user You entered CTRL+C or CRTL+BREAK. L1024 nested right parentheses The contents of an overlay were typed incorrectly on the Number LINK Error Message ────────────────────────────────────────────────────────────────────────── The contents of an overlay were typed incorrectly on the command line. L1025 nested left parentheses The contents of an overlay were typed incorrectly on the command line. L1026 unmatched right parenthesis A right parenthesis was missing from the contents specification of an overlay on the command line. L1027 unmatched left parenthesis A left parenthesis was missing from the contents specification of an overlay on the command line. L1043 relocation table overflow Number LINK Error Message ────────────────────────────────────────────────────────────────────────── L1043 relocation table overflow More than 32,768 long calls, long jumps, or other long pointers appeared in the program. Try replacing long references with short references, where possible, and recreate the object module. L1045 too many TYPDEF records An object module contained more than 255 TYPDEF records. These records describe communal variables. This error can appear only with programs produced by the Microsoft FORTRAN Compiler or other compilers that support communal variables. (TYPDEF is a DOS term. It is explained in the Microsoft MS-DOS Programmer's Reference and in other reference books on DOS.) L1046 too many external symbols in one module An object module specified more than the limit of 1023 Number LINK Error Message ────────────────────────────────────────────────────────────────────────── An object module specified more than the limit of 1023 external symbols. Break the module into smaller parts. L1047 too many group, segment, and class names in one module The program contained too many group, segment, and class names. Reduce the number of groups, segments, or classes, and recreate the object file. L1048 too many segments in one module An object module had more than 255 segments. Split the module or combine segments. L1049 too many segments The program had more than the maximum number of segments. Use the /SEGMENTS option, which has a default value of 128, to specify the maximum legal number of segments. The default is Number LINK Error Message ────────────────────────────────────────────────────────────────────────── specify the maximum legal number of segments. The default is 128 in the /SEGMENTS option, which specifies the maximum legal number. Relink using the /SEGMENTS option with an appropriate number of segments. L1050 too many groups in one module LINK encountered over 21 group definitions (GRPDEF) in a single module. Reduce the number of group definitions or split the module. (Group definitions are explained in the Microsoft MS-DOS Programmer's Reference and in other reference books on DOS.) L1051 too many groups The program defined more than 20 groups, not counting DGROUP. Reduce the number of groups. L1052 too many libraries Number LINK Error Message ────────────────────────────────────────────────────────────────────────── L1052 too many libraries An attempt was made to link with more than 32 libraries. Combine libraries, or use modules that require fewer libraries. L1053 out of memory for symbol table There is no fixed limit to the size of the symbol table. However, it is limited by the amount of available memory. Combine modules or segments and recreate the object files. Eliminate as many public symbols as possible. L1054 requested segment limit too high LINK did not have enough memory to allocate tables describing the number of segments requested. (The default is 128 or the value specified with the /SEGMENTS option.) Try linking again using the /SEGMENTS option to select a smaller number of Number LINK Error Message ────────────────────────────────────────────────────────────────────────── using the /SEGMENTS option to select a smaller number of segments (for example, use 64 if the default was used previously), or free some memory by eliminating resident programs or shells. L1056 too many overlays The program defined more than 63 overlays. L1057 data record too large A LEDATA record (in an object module) contained more than 1024 bytes of data. This is a translator error. (LEDATA is a DOS term, which is explained in the Microsoft MS-DOS Programmer's Reference and in other DOS reference books.) Note which translator (compiler or assembler) produced the incorrect object module and the circumstances. Please report this error to Microsoft Corporation using the Product Assistance Request form included with the documentation. Number LINK Error Message ────────────────────────────────────────────────────────────────────────── form included with the documentation. L1063 out of memory for CodeView information Too many linked object (".OBJ") files contain debugging information. Turn off the Produce Debug Code option in the Make EXE file dialog box. L1070 segment size exceeds 64K A single segment contained more than 64K of code or data. Try compiling and linking using the large model. L1071 segment _TEXT larger than 65520 bytes This error is likely to occur only in small-model C programs, but it can occur when any program with a segment named _TEXT is linked using the /DOSSEG option. Small-model C programs must reserve code addresses 0 and 1; this range is increased Number LINK Error Message ────────────────────────────────────────────────────────────────────────── must reserve code addresses 0 and 1; this range is increased to 16 for alignment purposes. L1072 common area longer than 65536 bytes The program had more than 64K of communal variables. This error occurs only with programs produced by compilers that support communal variables. L1080 cannot open list file The disk or the root directory was full. Delete or move files to make space. L1081 out of space for run file The disk on which the executable file was being written was full. Free more space on the disk and restart LINK. Number LINK Error Message ────────────────────────────────────────────────────────────────────────── L1083 cannot open run file The disk or the root directory was full. Delete or move files to make space. L1084 cannot create temporary file The disk or root directory was full. Free more space in the directory and restart LINK. L1085 cannot open temporary file The disk or the root directory was full. Delete or move files to make space. L1086 scratch file missing An internal error has occurred. Note the circumstances of the Number LINK Error Message ────────────────────────────────────────────────────────────────────────── An internal error has occurred. Note the circumstances of the problem and contact Microsoft Corporation using the Product Assistance Request form included with the documentation. L1087 unexpected end-of-file on scratch file The disk with the temporary output file from LINK was removed. L1088 out of space for list file The disk where the listing file is being written is full. Free more space on the disk and restart LINK. L1089 filename : cannot open response file LINK could not find the specified response file. This usually indicates a typing error. L1090 cannot reopen list file Number LINK Error Message ────────────────────────────────────────────────────────────────────────── The original disk was not replaced at the prompt. Restart LINK. L1091 unexpected end-of-file on library The disk containing the library probably was removed. Replace the disk containing the library and run LINK again. L1093 object not found One of the object files specified in the input to LINK was not found. Restart LINK and specify the object file. L1101 invalid object module One of the object modules was invalid. If the error persists after recompiling, please contact Microsoft Corporation using the Product Assistance Request form included with the Number LINK Error Message ────────────────────────────────────────────────────────────────────────── the Product Assistance Request form included with the documentation. L1102 unexpected end-of-file An invalid format for a library was encountered. L1103 attempt to access data outside segment bounds A data record in an object module specified data extending beyond the end of a segment. This is a translator error. Note which translator (compiler or assembler) produced the incorrect object module and the circumstances in which it was produced. Please report this error to Microsoft Corporation using the Product Assistance Request form included with the documentation. L1104 filename : not valid library Number LINK Error Message ────────────────────────────────────────────────────────────────────────── The specified file was not a valid library file. This error causes LINK to abort. L1113 unresolved COMDEF; internal error Note the circumstances of the failure and contact Microsoft Corporation using the Product Assistance Request form included with the documentation. L1114 file not suitable for /EXEPACK; relink without For the linked program, the size of the packed load image plus packing overhead was larger than that of the unpacked load image. Relink without the /EXEPACK option. L1115 /QUICKLIB, overlays incompatible You specified overlays and used the /QUICKLIB option. These Number LINK Error Message ────────────────────────────────────────────────────────────────────────── You specified overlays and used the /QUICKLIB option. These cannot be used together. L2001 fixup(s) without data A FIXUPP record occurred without a data record immediately preceding it. This is probably a compiler error. (See the Microsoft MS-DOS Programmer's Reference for more information on FIXUPP.) L2002 fixup overflow near number in frame seg segname target seg segname target offset number The following conditions can cause this error: ■ A group is larger than 64K. ■ The program contains an intersegment short jump or intersegment short call. Number LINK Error Message ────────────────────────────────────────────────────────────────────────── ■ The name of a data item in the program conflicts with the name of a library subroutine included in the link. ■ An EXTRN declaration in an assembly-language source file appeared inside the body of a segment, as in the following example: code SEGMENT public 'CODE' EXTRN main:far start PROC far call main ret start ENDP code ENDS The following construction is preferred: EXTRN main:far Number LINK Error Message ────────────────────────────────────────────────────────────────────────── EXTRN main:far code SEGMENT public 'CODE' start PROC far call main ret start ENDP code ENDS Revise the source file and recreate the object file. (See the Microsoft MS-DOS Programmer's Reference for information about frame and target segments. L2003 intersegment self-relative fixup at offset in segment segname You tried to make a near call or jump to a far entry in segment segname at offset. Change the call or jump to far or make the entry near. L2004 LOBYTE-type fixup overflow Number LINK Error Message ────────────────────────────────────────────────────────────────────────── L2004 LOBYTE-type fixup overflow A LOBYTE fixup generated an address overflow. (See the Microsoft MS-DOS Programmer's Reference for more information.) L2005 fixup type unsupported A fixup type occurred that is not supported by the Microsoft linker. This is probably a compiler error. Note the circumstances of the failure and contact Microsoft Corporation using the Product Assistance Request form included with the documentation. L2011 name : NEAR/HUGE conflict Conflicting NEAR and HUGE attributes were given for a communal variable. This error can occur only with programs produced by compilers that support communal variables. Number LINK Error Message ────────────────────────────────────────────────────────────────────────── L2012 name : array-element size mismatch A far communal array was declared with two or more different array-element sizes (for instance, an array was declared once as an array of characters and once as an array of real numbers). This error occurs only with compilers that support far communal arrays. L2013 LIDATA record too large A LIDATA record contains more than 512 bytes. This error is usually caused by a compiler error. L2024 name : symbol already defined LINK has found a public-symbol redefinition. Remove extra definition(s). Number LINK Error Message ────────────────────────────────────────────────────────────────────────── L2025 name : symbol defined more than once Remove the extra symbol definition from the object file. L2029 unresolved externals One or more symbols were declared to be external in one or more modules, but they were not publicly defined in any of the modules or libraries. A list of the unresolved external references appears after the message, as shown in the following example: unresolved externals EXIT in file(s): MAIN.OBJ (main.for) OPEN in file(s): MAIN.OBJ (main.for) The name that comes before in file(s) is the unresolved external symbol. On the next line is a list of object modules that have made references to this symbol. This message and the list are also written to the map file, if one exists. Number LINK Error Message ────────────────────────────────────────────────────────────────────────── list are also written to the map file, if one exists. L2041 stack plus data exceed 64K The total size of near data and the stack exceeds 64K. Reduce the stack size to control the error. LINK tests for this condition only if the /DOSSEG option is enabled. This option is automatically enabled by the library startup module. L2043 Quick library support module missing You did not specify, or LINK could not find, the object module or library required for creating a Quick library. In the case of QuickBASIC, the library provided is BQLB45.LIB. L2044 name : symbol multiply defined, use /NOE LINK has found a possible public-symbol redefinition. This error is often caused by redefining a symbol defined in a Number LINK Error Message ────────────────────────────────────────────────────────────────────────── error is often caused by redefining a symbol defined in a library. Relink using the /NOEXTDICTIONARY option. This error in combination with error L2025 for the same symbol indicates a real redefinition error. L4011 PACKCODE value exceeding 65500 unreliable Packcode segment sizes that exceed 65,500 bytes may be unreliable on the Intel(R) 80286 processor. L4012 load-high disables EXEPACK The /HIGH and /EXEPACK options cannot be used at the same time. L4015 /CODEVIEW disables /DSALLOCATE The /CODEVIEW and /DSALLOCATE options cannot be used at the same time. Number LINK Error Message ────────────────────────────────────────────────────────────────────────── same time. L4016 /CODEVIEW disables /EXEPACK The /CODEVIEW and /EXEPACK options cannot be used at the same time. L4020 name : code-segment size exceeds 65500 Code segments of 65,501-65,536 bytes in length may be unreliable on the Intel 80286 processor. L4021 no stack segment The program did not contain a stack segment defined with STACK combine type. This message should not appear for modules compiled with Microsoft QuickBASIC, but it could appear for an assembly-language module. Normally, every program should have a stack segment with the combine type specified as STACK. You Number LINK Error Message ────────────────────────────────────────────────────────────────────────── a stack segment with the combine type specified as STACK. You can ignore this message if you have a specific reason for not defining a stack or for defining one without the STACK combine type. Linking with versions of LINK earlier than Version 2.40 might cause this message, since these linkers search libraries only once. L4031 name : segment declared in more than one group A segment was declared to be a member of two different groups. Correct the source file and recreate the object files. L4034 more than 239 overlay segments; extra put in root The program designates more than 239 segments to go in overlays. When this error occurs, segments beginning with number 234 are placed in the root, the permanently resident portion. Number LINK Error Message ────────────────────────────────────────────────────────────────────────── L4045 name of output file is name The prompt for the run-file field gave an inaccurate default because the /QUICKLIB option was not used early enough. The output will be a Quick library with the name given in the error message. L4050 too many public symbols for sorting The number of public symbols exceeds the space available for sorting the symbols as requested by the /MAP option. The symbols are left unsorted. L4051 filename : cannot find library LINK could not find the specified file. Enter a new file name, a new path specification, or both. Number LINK Error Message ────────────────────────────────────────────────────────────────────────── L4053 VM.TMP : illegal file name; ignored VM.TMP appeared as an object-file name. Rename the file and rerun LINK. L4054 filename : cannot find file LINK could not find the specified file. Enter a new file name, a new path specification, or both. ────────────────────────────────────────────────────────────────────────── B.4 LIB Error Messages Error messages generated by the Microsoft Library Manager, LIB, have one of the following formats: {filename | LIB} : fatal error U1xxx: messagetext {filename | LIB} : error U2xxx: messagetext {filename | LIB} : warning U4xxx: messagetext The message begins with the input-file name (filename), if one exists, or with the name of the utility. If possible, LIB prints a warning and continues operation. In some cases errors are fatal, and LIB terminates processing. LIB may display the following error messages: Number LIB Error Message< ────────────────────────────────────────────────────────────────────────── U1150 page size too small The page size of an input library was too small, which indicates an invalid input .LIB file. U1151 syntax error : illegal file specification A command operator such as a minus sign (-) was given without a following module name. U1152 syntax error : option name missing A forward slash (/) was given without an option after it. U1153 syntax error : option value missing The /PAGESIZE option was given without a value following it. U1154 option unknown An unknown option was given. Currently, LIB recognizes only the /PAGESIZE option. U1155 syntax error : illegal input The given command did not follow correct LIB syntax as specified in Appendix G, "Compiling and Linking from DOS." U1156 syntax error The given command did not follow correct LIB syntax as specified in Appendix G, "Compiling and Linking from DOS." U1157 comma or new line missing A comma or carriage return was expected in the command line but did not appear. This may indicate an inappropriately placed comma, as in the line that follows: LIB math.lib,-mod1+mod2; The line should have been entered as follows: LIB math.lib -mod1+mod2; U1158 terminator missing Either the response to the "Output library" prompt or the last line of the response file used to start LIB did not end with a carriage return. U1161 cannot rename old library LIB could not rename the old library to have a .BAK extension because the .BAK version already existed with read-only protection. Change the protection on the old .BAK version. U1162 cannot reopen library The old library could not be reopened after it was renamed to have a .BAK extension. U1163 error writing to cross-reference file The disk or root directory was full. Delete or move files to make space. U1170 too many symbols More than 4609 symbols appeared in the library file. U1171 insufficient memory LIB did not have enough memory to run. Remove any shells or resident programs and try again, or add more memory. U1172 no more virtual memory Note the circumstances of the failure and notify Microsoft Corporation using the Product Assistance Request form included with the documentation. U1173 internal failure Note the circumstances of the failure and notify Microsoft Corporation using the Product Assistance Request form included with the documentation. U1174 mark: not allocated Note the circumstances of the failure and notify Microsoft Corporation using the Product Assistance Request form included with the documentation. U1175 free: not allocated Note the circumstances of the failure and notify Microsoft Corporation using the Product Assistance Request form included with the documentation. U1180 write to extract file failed The disk or root directory was full. Delete or move files to make space. U1181 write to library file failed The disk or root directory was full. Delete or move files to make space. U1182 filename : cannot create extract file The disk or root directory was full, or the specified extract file already existed with read-only protection. Make space on the disk or change the protection of the extract file. U1183 cannot open response file The response file was not found. U1184 unexpected end-of-file on command input An end-of-file character was received prematurely in response to a prompt. U1185 cannot create new library The disk or root directory was full, or the library file already existed with read-only protection. Make space on the disk or change the protection of the library file. U1186 error writing to new library The disk or root directory was full. Delete or move files to make space. U1187 cannot open VM.TMP The disk or root directory was full. Delete or move files to make space. U1188 cannot write to VM Note the circumstances of the failure and notify Microsoft Corporation using the Product Assistance Request form. U1189 cannot read from VM Note the circumstances of the failure and notify Microsoft Corporation using the Product Assistance Request form. U1190 interrupted by user The user pressed CTRL+C or CTRL+BREAK. U1200 name : invalid library header The input library file had an invalid format. It was either not a library file, or it had been corrupted. U1203 name : invalid object module near location The module specified by name was not a valid object module. U2152 filename : cannot create listing The directory or disk was full, or the cross-reference-listing file already existed with read-only protection. Either make space on the disk or change the protection of the cross-reference-listing file. U2155 modulename : module not in library; ignored The specified module was not found in the input library. U2157 filename : cannot access file LIB was unable to open the specified file. U2158 libraryname : invalid library header; file ignored The input library had an incorrect format. U2159 filename : invalid format hexnumber; file ignored The signature byte or word hexnumber of the given file was not one of the following recognized types: Microsoft library, Intel library, Microsoft object, or XENIX(R) archive. U4150 modulename : module redefinition ignored A module was specified to be added to a library but a module with the same name was already in the library. Or, a module with the same name was found more than once in the library. U4151 symbol : symbol redefined in module modulename, redefinition ignored The specified symbol was defined in more than one module. U4153 number : page size too small; ignored The value specified in the /PAGESIZE option was less than 16. U4155 modulename : module not in library A module to be replaced is not in the library. LIB adds the module to the library. U4156 libraryname : output-library specification ignored An output library was specified in addition to a new library name. For example, specifying LIB new.lib+one.obj,new.lst,new.lib where new.lib does not already exist causes this error. U4157 Insufficient memory, extended dictionary not created. LIB was unable to create the extended dictionary. The library is still valid, but LINK cannot take advantage of extended dictionaries to link faster. U4158 Internal error, extended dictionary not created. LIB was unable to create the extended dictionary. The library is still valid, but LINK cannot take advantage of extended dictionaries to link faster. ──────────────────────────────────────────────────────────────────────────── Index Symbols ' (apostrophe) entering + (concatenation operator) A ABS function ALIAS, use in DECLARE statement Alphanumeric line labelsLine labels Angle measurement degrees to radians, converting from radians to degrees, converting from Animation Apostrophe (') entering Arctangent, ATN function Argument passing Arithmetic operators Arithmetic overflow Arrays dimensioning dynamic ERASE statement REDIM statement elements INT86OLD statements LBOUND function location in memory of records static, ERASE statement subscripts, specifying changing lower bound for described maximum value for number of UBOUND function variables AS clause ASC function ASCII character codes special character string expression (table) Assembly language subroutines calling name, PUBLIC symbol string descriptor length Assignment statements ATN function AT&T displays Automatic variables B Background music .BAS files BASIC error codes run-time errors BASICA, differences from BLOAD statement BSAVE statement CALL ABSOLUTE statement CALL statement CLEAR statement COM statement DEF SEG statement DEF type statements DIM statement DRAW statement ERL function FIELD statement RESUME statement STRIG function SYSTEM statement TAN function VARPTR$ function basica, Differences From Chain Statement For...Next Statement BEEP statement Binary mode functions FILEATTR LOC statements GET (File I/O) LOCK OPEN PUT (File I/O) SEEK BLOAD statement Block IF...THEN...ELSE statement Bold text, indicating keywords Boolean operations BSAVE statement Built-in functions BYVAL, use in DECLARE statement C CALL ABSOLUTE statement CALL INT86OLD statement CALL INT86XOLD statement CALL INTERRUPT statement CALL INTERRUPTX statement CALL statement (BASIC procedures) CALL statement (non-BASIC procedures) described location of arguments Calling conventions CALLS statement described location of arguments Cardioid Carriage return CASE clause Case, line labels CDBL function CDECL, use in DECLARE statement CGA adapter CHAIN statement Chaining programs, statements for CHAIN COMMON RUN Chainingprograms, statements for COMMON Characters recognized by BASIC CHDIR statement CHR$ function CINT function CIRCLE statement CLEAR statement CLNG function CLOSE statement CLS statement /CMD option Color Graphics AdapterCGA adapter COLOR statement COM devices COM statements COMMAND$ function COMMAND.COM Commandline, passing to BASIC program Comments introducing REM statement COMMON statement blank chaining programs declaring variables named order of variables SHARED attribute Compile-time error messages Concatenation operator(+) CONST statement Constants global local scope rules symbolic Control-flow statements CALL CALL ABSOLUTE CALLS CHAIN DEF FN DO...LOOP FOR...NEXT FUNCTION GOSUB...RETURN GOTO IF...THEN...ELSE ON GOSUB ON GOTO RETURN SELECT CASE WHILE...WEND COS function Cosine, COS function CSNG function CSRLIN function CVD function CVDMBF function CVI function CVL function CVS function CVSMBF function D DATA statement Data types double-precision floating-point numeric fixed-length string four-byte integer numeric integer numeric long-integer numeric single-precision floating-point numeric specifying two-byte integer numeric TYPE statement variable-length string Date and time functions DATE$ TIME$ statements DATE$ TIME$ DATE$ function DATE$ statement Debugging statements Declarations CONST statement DECLARE statement (BASIC procedures) DECLARE statement (non-BASIC procedures) DEF type statements DIM statement fixed-length strings simple variables variable types DECLARE statements described location of arguments DEF FN functions BASIC, used in exit from, alternative variable scope DEF FN statement DEF SEG statement DEF type statements Default data segments DEFDBL statement DEFINT statement DEFLNG statement DEFSNG statement DEFSTR statement Device errors Devices, handling functions IOCTL$ LPOS PEN statements IOCTL OPEN COM OUT WAIT Device-status information DGROUP, defined DIM statement description SHARED attribute variable types Directory statements CHDIR FILES MKDIR NAME RMDIR Display memory, PCOPY statement Division by zero DO UNTIL statement DO WHILE statement Document conventions DO...LOOP statement exit from, alternative flow control DOS environment variables interrupts DOS-level commands Double precision numbers converting to description PRINT, displayed by variables DRAW statement description DRAWstatement VARPTR$ function, using ¢DYNAMIC arrays described location in memory Dynamic arrays ERASE statement REDIM statement E EGA adapter COLOR statement PALETTE statement SCREEN statement EGAadapter COLOR statement END CASE clause END DEF statement END FUNCTION statement END IF statement END SELECT statement END statement END SUB statement END TYPE statement Enhanced Graphics AdapterEGA adapter ENVIRON$ function ENVIRON statement Environment variables Environment-string table EOF function ERASE statement ERDEV function ERDEV$ function ERL function described line labels with ERR code ERR function Error codes Error handling error line number statements ERDEV ERR, ERL ERROR ON ERROR RESUME Error messages compile-time described invocation LIB LINK run-time ERROR statement Error trapping ERROR statement line 0, using Event-trapping statements COM KEY(n) ON event ON UEVENT PEN ON, OFF, and STOP PLAY ON, OFF, and STOP TIMER ON, OFF, and STOP UEVENT .EXE files EXIT DEF statement EXIT DO statement EXIT FOR statement EXIT FUNCTION statement EXIT statement description multiline functions, use in subprograms, use in EXIT SUB statement EXP function Expressions conversion of operands definition F Far addresses FIELD statement File access LOCK statement UNLOCK statement File conversion File handling functions EOF FILEATTR FREEFILE LOC LOF SEEK statements CHDIR CLOSE FIELD GET INPUT # KILL LOCK NAME OPEN RESET SEEK UNLOCK File names, described FILEATTR function Files attributes binary mode, statements and functions FILEATTR GET LOC LOCK OPEN PUT SEEK function SEEK statement random access, statements and functions EOF FIELD GETIO KILL LOC LOCK LSET MKI$, MKS$, MKD$, MKL$ OPEN PUT RSET SEEK function SEEK statement sequential, statements and functions EOF INPUT # KILL LINE INPUT # LOC LOF OPEN PRINT # WRITE # FILES statement FIX function Fixed-point constants Floating point double precision constants range numbers single precision, range Formatting output FOR...NEXT statements description exit from, alternative FRE function FREEFILE function FUNCTION procedures DECLARE statements exit from, alternative module organization STATIC keyword FUNCTION statements Functional operators Functions built-in intrinsic user-defined variables, declaring as local G GET statements FIELD statement File I/O Graphics Global constants Global variables GOSUB statement GOTO statement description line labels, using subroutines, use with Graphics functions PMAP POINT macro language statements BLOAD BSAVE CIRCLE COLOR DRAW GET LINE PAINT PALETTE PALETTE USING PRESET PSET PUT VIEW WINDOW H Hercules adapters HEX$ function Hexadecimal numbers Hierarchy, of operators I IEEE-format numbers IF...THEN...ELSE statements description GOTO statement, when required line labels INKEY$ function INP function INPUT$ function Input functions COMMAND$ INP INPUT$ INPUT # statement INPUT statement description FIELD statement line editor commands Input statements DATA INPUT INPUT # LINE INPUT LINE INPUT # READ RESTORE WAIT INSTR function INT function INT86, INT86X replacements CALL INT86OLD statements CALL INTERRUPT statements Integers constants decimal hexadecimal octal converting to division FIX function Intrinsic functions Invocation error messages I/O ports IOCTL$ function IOCTL statement Italic text, showing placeholders J Joysticks K KEY OFF statement Keyboard scan codes KEY(n) statements KILL statement L LBOUND function LCASE$ function LEFT$ function LEN function LET statement LIB error messages Line 0, effect on error trapping Line feed LINE INPUT # statement LINE INPUT statement Line labels alphanumeric case, significance of GOTO statement, use with RESUME statement use of Line numbers example of restrictions RESUME statement use of Line printer LINE statement Line styling Line-editor commands LINK error messages LOC function Local constants Local variables LOCATE statement LOCK statement LOF function LOG function Logical operators description type conversion Long integers constants converting to Loops LPOS function LPRINT statement description SPC function LPRINT USING statement LSET statement LTRIM$ function M Main module Math functions ABS ATN COS CVSMBF EXP LOG MKSMBF$, MKDMBF$ SIN SQR TAN MCGA adapter COLOR statement PALETTE statement SCREEN statement MDPA adapter, PALETTE statement Memory management functions FRE SETMEM statements CLEAR DEF SEG ERASE PCOPY Microsoft Binary format numbers MID$ function MID$ statement Mixed-language programming ALIAS, use of BYVAL, use of CALL, CALLS statement (non-BASIC) CDECL, use of DECLARE statement (non-BASIC) SADD function SEG, use of variable storage allocation VARPTR function MKD$ function MKDIR statement MKI$ function MKL$ function MKS$ function MKSMBF$ function MOD, module arithmetic operator Module-level code Modules Modulo arithmetic Modulus operator MulticolorGraphics Array adapterMCGA Multiline functions, run-time features, nesting Music background macro language N NAME statement Near addresses NEXT statement Notational conventions Numeric constants Numeric conversions CVD function CVI function CVL function CVS function double precision integer single precision Numeric functions CDBL CINT CLNG CSNG CVD CVI CVL CVS FIX INT RND SGN O OCT$ function Octal conversion Olivetti displays OS/2 warning ON COM statement ON ERROR statement description line 0, effect of line labels ON event statements ON KEY statement ON PEN statement ON PLAY statement ON STRIG statement ON TIMER statement ON UEVENT statement ON...GOSUB statement ON...GOTO statement OPEN COM statement OPEN statement Operators arithmetic concatenation definition functional logical precedence relational string OPTION BASE statement OUT statement Output functions LPOS POS TAB line width statements BEEP CLS LPRINT OUT PRINT PRINT # PRINT # USING PRINT USING PUT WRITE WRITE # Overflow P PAINT statement PALETTE statement PALETTE USING statement Passing arguments PCOPY statement PEEK function PEN function PEN OFF statement PEN ON statement PEN STOP statement Physical coordinates mapping to logical coordinates view Physicalviewport PLAY function PLAY OFF statement PLAY ON statement PLAY statement description VARPTR$ function,using PLAY STOP statement PMAP function POINT function POKE statement POS function Precedence of operators PRESET statement PRINT # statement PRINT statement description SPC function PRINT # USING statement PRINT USING statement Procedures Program suspension Program termination PSET statement PUBLIC symbol PUT statements FIELD statement File I/O Graphics R Random numbers Random-access files, statements and functions EOF FIELD GET KILL LOC LOCK MKD$, MKI$, MKL$, MKS$ OPEN PUT SEEK function SEEK statement storing data in buffer RANDOMIZE statement READ statement Real numbers Record elements, reference Record variables Records arrays of variable length Recursion REDIM statement description SHARED attribute variables, declaring Referencing record elements Register values, INT86OLD, INT86XOLD Relational operators REM statement RESET statement RESTORE statement RESUME NEXT statement RESUME statement alphanumeric line labels BASICA, differences from description RESUME 0, effect of RETURN statement description EXIT statement, not equivalent to GOSUB statement RIGHT$ function RMDIR statement RND function RSET statement RTRIM$ function RUN statement Run-time error messages S SADD function described movement of variables Scan codes, keyboard Scope SCREEN 10, using Screen functions CSRLIN POS SCREEN Screen statements CLS COLOR LOCATE PCOPY SCREEN VIEW PRINT Screenstatements WIDTH SEEK function statement SEG, use in DECLARE statement SELECT CASE statement Sequential files, statements and functions EOF INPUT # KILL LINE INPUT # LOC LOF OPEN PRINT # WRITE # SETMEM function described movement of variables SetUEvent routine SGN function SHARED statement described variables declaring local sharing Shared variables among modules within a module Shell escape SHELL statement Simple variables declaring location in memory SIN function Sine, SIN function Single-precision numbers converting to PRINT, displayed by types of constants SLEEP statement SOUND statement Source files SPACE$ function SPC function Special characters Spiral of Archimedes SQR function Statements ¢STATIC arrays described location in memory Static arrays, ERASE statement STATIC keyword STATIC statement description variables declaring local STATIC, creating STICK function STOP statement Storage requirements, variables STR$ function STRIG function STRIG OFF statement STRIG ON statement STRIG(n) statements String concatenation constants descriptor length functions ASC CHR$ DATE$ HEX$ INPUT$ INSTR LCASE$ LEFT$ LEN LTRIM$ MID$ RIGHT$ RTRIM$ SADD SPACE$ STR$ STRING$ UCASE$ VAL operators processing statements LSET MID$ RSET variables STRING$ function String-space compaction SUB procedures DECLARE statements exit from, alternative STATIC keyword using SUB statement Subprograms CALL statement CALLS statement CHAIN statement SUB statement user library, example variables Subroutines Subscripts, specifying lower bound for maximum value for number of SWAP statement Symbolic constants CONST use of Syntax notation choices optional items placeholders System calls SYSTEM statement T TAB function TAN function Tangent, TAN function Tiling TIME$ function TIME$ statement TIMER function TIMER OFF statement TIMER ON statement TIMER STOP statement Timing function Trigonometric functions ATN COS SIN TAN TROFF statement TRON statement Type conversion logical operators rules for TYPE statements Typeface key names keywords placeholders program Type-mismatch error message Typographic conventions U UBOUND function UCASE$ function UEVENT statement UNLOCK statement User-defined data types User-defined events User-defined functions V VAL function Variable-length records Variable-length strings, location in memory Variables array automatic data type definition global function definitions subprograms using local function definitions subprograms using names length rules record scope shared variables STATIC variables storage allocation storage requirements string type-declaration suffixes VARPTR function described movement of variables VARPTR$ function described movement of variables VARSEG function described movement of variables VGA adapter COLOR statement PALETTE statement SCREEN statement VGAadapter COLOR statement Video GraphicsArray adapterVGA adapter Video memory View coordinates mapping to physical coordinates WINDOW statement VIEW PRINT statement VIEW statement W WAIT statement WEND statement WHILE statement WIDTH statement WINDOW statement WRITE # statement WRITE statement