Basic

4680 Basic

Language ReferenceV ersion 1 Release 2

SC30-3356-09

4680 Basic

Language ReferenceV ersion 1 Release 2

SC30-3356-09

Note Before using this information and the product it supports, be sure to read the general information under Notices on page ix.

Tenth Edition (October 2003) This edition applies to Version 1 Release 2 of the IBM 4680 BASIC Licensed Program, program number 5669-034. Order publications through your IBM representative or the IBM branch office serving your locality. Publications are not stocked at the address below. A form for comments is provided at the back of this publication. If the form has been removed, address your comments to: IBM Corporation Retail Store Solutions Information Development P. O. Box 12195 RESEARCH TRIANGLE PARK NC 27709-9990 When you send information to IBM, you grant IBM a nonexclusive right to use or distribute whatever information you supply in anyway it believes appropriate without incurring any obligation to you. Copyright International Business Machines Corporation 1985, 2003. All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

ContentsFigures . . . . . . . . . . . . . . vii Notices . . . . . . . . . . . . . . . ixTrademarks . . . . . . . . . . . . . . ix Scope of Data. . . . . . . . . . . . . . 31

Chapter 7. Statements and Language-Defined Functions . . . . . 33Statements . . . . . . . . . . . . . . . Language-Defined Functions . . . . . . . . Syntax Diagrams . . . . . . . . . . . . Name Specification . . . . . . . . . . . . Restricted Use of Functions and Statements. . . . Statements and Functions. . . . . . . . . . ABS Function . . . . . . . . . . . . . ACCESS Statement . . . . . . . . . . . ASC Function . . . . . . . . . . . . ASSIGNKEY Statement . . . . . . . . . CALL Statement . . . . . . . . . . . . CHAIN Statement . . . . . . . . . . . CHDIR Statement . . . . . . . . . . . CHR$ Function . . . . . . . . . . . . CLEARS Statement . . . . . . . . . . . CLOSE Statement . . . . . . . . . . . COMMAND$ Function . . . . . . . . . COMMON Statement . . . . . . . . . . CONCHAR% Function . . . . . . . . . CONSOLE Statement . . . . . . . . . . CONSTAT% Function . . . . . . . . . . CREATE Statement . . . . . . . . . . . CREATE POSFILE Statement . . . . . . . CREATE POSFILE KEYED Statement . . . . . CREATE POSFILE RANDOM/DIRECT Statement DATA Statement . . . . . . . . . . . . DATE$ Function . . . . . . . . . . . . DEF Statement . . . . . . . . . . . . DELETE Statement . . . . . . . . . . . DELREC Statement . . . . . . . . . . . DIM Statement . . . . . . . . . . . . DISABLE Function . . . . . . . . . . . ENABLE Function . . . . . . . . . . . END Statement . . . . . . . . . . . . END FUNCTION Statement . . . . . . . . END SUB Statement . . . . . . . . . . ERR Function . . . . . . . . . . . . . ERRF% Function . . . . . . . . . . . ERRL Function . . . . . . . . . . . . ERRN Function . . . . . . . . . . . . EVENT% Function . . . . . . . . . . . EXIT FUNCTION Statement . . . . . . . . EXIT SUB Statement . . . . . . . . . . FEND Statement . . . . . . . . . . . . FLOAT Function . . . . . . . . . . . . FOR Statement . . . . . . . . . . . . FRE Function . . . . . . . . . . . . . FUNCTION Statement . . . . . . . . . . FUNCTIONKEY Statement . . . . . . . . GET Function. . . . . . . . . . . . . GETLONG Function . . . . . . . . . . 33 33 33 34 35 36 37 38 39 40 40 41 43 44 45 46 47 48 49 50 51 52 54 56 58 59 61 61 63 64 65 66 66 67 67 68 69 69 70 71 72 73 74 75 75 76 77 78 80 80 81

Preface . . . . . . . . . . . . . . . xiHow This Book is Organized. . . . . . . . Where to Find More Information . . . . . . Store System Related Publications Software . Store System Related Publications Hardware General Publications . . . . . . . . . . . xi . xi . xi xii xiv

Chapter 1. Introduction . . . . . . . . 1Runtime Subroutine Libraries . . . An IBM 4680 BASIC Demonstration . . . . . . . . . . . 1 . 2

Chapter 2. Elements of IBM 4680 BASICThe Character Set . . Identifiers . . . . Statements and Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5. 5 . 6 . 7

Chapter 3. Data Types . . . . . . . . . 9Constants . . . . . . . . . . . . . . . 9 Integer Data Type. . . . . . . . . . . . . 9 Real Data Type . . . . . . . . . . . . . 10 String Data Type . . . . . . . . . . . . 10 Data Type Declarations . . . . . . . . . . 11

Chapter 4. Variables and Arrays . . . . 13Variables . Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 . 14

Chapter 5. ExpressionsArithmetic Expressions . . Mixed Arithmetic Expressions Character Expressions . . . Relational Expressions . . . Logical Expressions . . . . Operator Precedence . . . . . . . . .

. . . . . . . 15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 17 18 19 20 22

Chapter 6. Subroutines, Subprograms, and User-Defined Functions . . . . . 23Parameters to Subprograms and Functions . . Subroutines . . . . . . . . . . . . Subprograms . . . . . . . . . . . . Passing Parameters by Reference . . . . How to Use a Subprogram . . . . . . User-Defined Functions . . . . . . . . Passing Parameters by Value . . . . . Single-Line User-Defined Functions . . . Multiline User-Defined Functions . . . . Separate Subprogram and Function Compilation Recursive Subprograms or Functions . . . . Copyright IBM Corp. 1985, 2003

. . . . . . . . . . .

. . . . . . . . . . .

23 23 25 25 25 26 27 27 28 30 31

iii

GOSUB Statement . . . . . . . GOTO Statement . . . . . . . IF Statement . . . . . . . . . IF END # Statement . . . . . . INKEY Function . . . . . . . . INPUT Statement . . . . . . . INPUT LINE Statement . . . . . INT Function . . . . . . . . . INT% Function . . . . . . . . INTEGER Statement . . . . . . LEFT$ Function . . . . . . . . LEN Function . . . . . . . . LET Statement . . . . . . . . LOAD Statement . . . . . . . LOCATE # Statement . . . . . . LOCK Function . . . . . . . . LOCKDEV Statement . . . . . . LPRINTER Statement . . . . . . MATCH Function . . . . . . . MFRE Function . . . . . . . . MID$ Function . . . . . . . . MKDIR Statement . . . . . . . MOD Function . . . . . . . . NEXT Statement . . . . . . . ON Statement . . . . . . . . ON ASYNC ERROR CALL Statement ON ERROR Statement . . . . . OPEN Statement . . . . . . . OPEN LINK Statement . . . . . OPEN SERIAL Statement . . . . OPEN SESSION Statement . . . . OPTION Statement . . . . . . PACK$ Function . . . . . . . PEEK Function . . . . . . . . POINT Statement . . . . . . . POKE Statement . . . . . . . POS Function . . . . . . . . PRINT Statement . . . . . . . PRINT USING Statement . . . . PRINT # Statement . . . . . . PTRRTN Function . . . . . . . PUT Statement . . . . . . . . PUTLONG Statement. . . . . . RANDOMIZE Statement . . . . READ Statement . . . . . . . READ # Statement . . . . . . READ # LINE Statement . . . . READ FORM # Statement . . . . READ MATRIX Statement . . . . REAL Statement . . . . . . . REMARK Statement . . . . . . RENAME Function . . . . . . RESTORE Statement . . . . . . RESUME Statement . . . . . . RETURN Statement . . . . . . RIGHT$ Function . . . . . . . RMDIR Statement . . . . . . . RND Function . . . . . . . . ROUND Function . . . . . . . SADD Function . . . . . . . SGN Function . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. 82 . 83 . 84 . 87 . 88 . 89 . 90 . 91 . 91 . 92 . 93 . 94 . 95 . 96 . 97 . 98 . 99 . 99 . 100 . 102 . 103 . 104 . 104 . 105 . 106 . 107 . 110 . 112 . 115 . 116 . 117 . 118 . 119 . 120 . 120 . 122 . 122 . 123 . 124 . 126 . 127 . 128 . 129 . 130 . 130 . 131 . 133 . 134 . 136 . 137 . 138 . 139 . 140 . 141 . 142 . 143 . 143 . 144 . 145 . 146 . 146

SHIFT Function . . . . SIZE Function . . . . . STOP Statement . . . . STR$ Function . . . . . STRING Statement . . . STRING$ Function . . . SUB Statement . . . . . TAB Function . . . . . TCLOSE Statement . . . TIME$ Function . . . . TRANSLATE$ Function . . UCASE$ Function . . . . UNLOCK Function . . . UNLOCKDEV Statement . UNPACK$ Function . . . USE Statement . . . . . VAL Function . . . . . VARPTR Function . . . . WAIT Statement . . . . WEND Statement . . . . WHILE Statement . . . . WRITE # Statement . . . WRITE LOGO # Statement . WRITE MATRIX Statement .

. . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . .

147 148 148 149 150 151 151 153 154 154 155 156 156 157 158 159 160 161 161 162 163 164 167 169

Chapter 8. Using Input and Output Devices and Pipes . . . . . . . . . 171Pipes . . . . . . . . . . . . . . . Reading a File Record . . . . . . . . . Writing a File Record . . . . . . . . . . Formatted Input/Output . . . . . . . . Formatted Output . . . . . . . . . . Examples . . . . . . . . . . . . . Formatted Input . . . . . . . . . . Examples . . . . . . . . . . . . . Formatted Printing . . . . . . . . . . String Character Fields . . . . . . . . Fixed-Length String Fields . . . . . . . Variable-Length String Fields . . . . . . Numeric Data Fields . . . . . . . . . Escape Character . . . . . . . . . . Store Controller Input/Output Device Drivers . Store Controller Keyboard . . . . . . . Store Controller Display . . . . . . . . Store Controller Printer . . . . . . . . Store Controller/Host Communications . . . System Network Architecture Communications Binary Synchronous Communications . . . Asynchronous Communication . . . . . Terminal Input/Output Device Drivers . . . . 2x20 Display Driver . . . . . . . . . . Example . . . . . . . . . . . . . Cash Drawer Driver . . . . . . . . . . Example . . . . . . . . . . . . . Coin Dispenser . . . . . . . . . . . . Example . . . . . . . . . . . . . Input/Output Processor . . . . . . . . . Example . . . . . . . . . . . . . Magnetic Stripe Reader (Dual-Track and Single-Track) . . . . . . . . . . . . Single-Track MSR Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 172 173 175 175 177 178 179 179 180 181 181 182 183 184 184 184 185 185 186 192 195 198 198 201 202 203 204 205 207 212

. 213 . 216

iv

IBM 4680 BASIC: Language Reference

Dual-Track MSR Example . . Printer Stations for Printer Models Printer Stations for Printer Models Example . . . . . . . . IBM 4689 Printer . . . . . . Fiscal Printers . . . . . . . Scale Driver . . . . . . . . Example . . . . . . . . Shopper Display Driver . . . . Example . . . . . . . . Serial I/O Communications . . Example . . . . . . . . Tone Driver . . . . . . . . Example . . . . . . . . Totals Retention Driver . . . . Example . . . . . . . . Video Display Driver . . . . . Example . . . . . . . .

. . . . 1 and 2 . 3 and 4/4A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

217 219 223 230 232 236 236 237 238 241 242 250 251 253 253 256 258 269

Return Values . . . . Register Usage . . . . Program Example . . . BASIC Routine . . . Assembler Subroutine Results of Example .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

302 303 303 303 304 306

Appendix A. Compiler Error Messages 307File System, Memory Space, and Compilation Errors . . . . . . . . . . . . . . Internal Failures . . . . . . . . . . . . . 307 . 328

Appendix B. Runtime Error MessagesSynchronous Error Recovery . . RESUME only . . . . . . RESUME label . . . . . . RESUME RETRY . . . . . Asynchronous Error Recovery . . Additional Information . . . . Storage Considerations . . . I/O Operations . . . . . . Multiple ON ERROR Routines No ON ERROR Routine Specified . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

329. . . . . . . . . . 329 329 330 330 330 330 330 330 331 331

Chapter 9. IBM 4680 BASIC Compiler Operation . . . . . . . . . . . . . 275Compiler Versions . . . . . . . . . . . How the Compiler Operates . . . . . . . Setting Paths for Source, Include, and Object Files Source Files . . . . . . . . . . . . Include Files . . . . . . . . . . . . Object Files . . . . . . . . . . . . Compiler Directives . . . . . . . . . . Command-Line Options . . . . . . . . . Source-Code Compiler Directives . . . . . Compiler Errors . . . . . . . . . . . Compilation Errors . . . . . . . . . File System and Memory Space Errors . . . Internal Compiler Failures . . . . . . . . 275 . 275 276 . 276 . 276 . 277 . 277 . 277 . 281 . 282 . 282 . 284 . 284

Appendix C. IBM 4680 BASIC Reserved Words . . . . . . . . . . 371 Appendix D. Statement and Language-Defined Function Summary . 373Statements . . . . . . . . . Input/Output Statements . . . Non-Input/Output Statements . Language-Defined Functions . . . String-Related Numeric Functions Input/Output Numeric Functions Miscellaneous Numeric Functions String Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 373 375 377 378 378 379 379

Chapter 10. Memory Allocation . . . . 285Memory Models . . . . . . . . Controller Large Memory Model . . Terminal Medium Memory Model . Terminal Big Memory Model (Version . . . . . . . . . 3 only) . 285 . 285 . 287 289

Appendix E. Data I/O Device Statement Figures . . . . . . . . . 381 Appendix F. Character Sets For Terminal Printers, Displays, and Controller Video Display . . . . . . 383Escape Sequence for Store Controller Display . . . 436 Extended Codes for Personal Computer Keyboard Input . . . . . . . . . . . . . . . . 437

Chapter 11. Data Representation in Memory . . . . . . . . . . . . . . 293Integer Storage In Memory . . . Real Number Storage in Memory . String Storage in Memory . . . Array Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 294 295 296

Chapter 12. Interfacing IBM 4680 BASIC with Assembly Language . . . 299Calling an Assembly Routine from an IBM 4680 BASIC Module . . . . . . . . . . . . Passing Arguments . . . . . . . . . . . 299 . 299

Glossary . . . . . . . . . . . . . 439 Index . . . . . . . . . . . . . . . 457

Contents

v

vi


Figures1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. Flow Diagram of a Subroutine . . . . . . 24 Flow Diagram of a Subprogram . . . . . . 26 Flow Diagram of the Multiline Function 29 Sample Syntax Diagram . . . . . . . . 34 File Specification Syntax Diagram . . . . . 34 Pipe Specification Syntax Diagram . . . . . 35 CREATE POSFILE KEYED Statement . . . . 56 Pipe With Delimited Data . . . . . . . 172 Pipe . . . . . . . . . . . . . . 172 Large Memory Model . . . . . . . . . 286 Large Memory Model Runtime Organization 286 Terminal Medium Memory Model . . . . 288 Terminal Medium Model Runtime Organization . . . . . . . . . . . . 288 Terminal Big Memory Model . . . . . . 290 Terminal Big Memory Model Runtime Organization . . . . . . . . . . . . 290 1-byte Integer Memory Format . . . . . . 293 2-byte Integer Memory Format and Example 293 4-byte Integer Memory Format and Example 294 Real Number Storage in Memory . . . . . 294 String Storage in Memory in Controller or Big Memory Model Terminal. . . . . . . . 295 String Storage in Memory in Medium Memory Model Terminal. . . . . . . . 296 Memory Usage of String Arrays . . . . . 297 Function Stack for Medium Memory Model 300 Function Stack for Large or Big Memory Model . . . . . . . . . . . . . . 301 Medium Memory Model Subprogram Stack 301 Large or Big Memory Model Subprogram Stack . . . . . . . . . . . . . . 302 Returning a String From a Function . . . . 303 File Type to IBM 4680 BASIC Statement Match . . . . . . . . . . . . . . 382 Alphanumeric Display Character Set Canadian French (Based on Code Page 863) . 384 LCD Character Set - Canadian French (Based on Code Page 863) . . . . . . . . . . 385 Operator Display Character Set - Canadian French (Based on Code Page 863) . . . . . 386 Printer Models 1 and 2 Character Set Canadian French (Based on Code Page 863) . 387 Printer Models 3 and 4 Character Set Canadian French (Based on Code Page 863) . 388 VFD II Character Set - Canadian French (Based on Code Page 863) . . . . . . . 389 Video Display (Feature A) Character Set Canadian French (Based on Code Page 863) . 390 Video Display (VGA) Character Set Canadian French (Based on Code Page 863) . 391 4680 Controller Video Display Character Set Canadian French (Based on Code Page 863) . 392 4690 Controller Video Display Character Set Canadian French (Based on Code Page 863) . 393 39. 40. 41. 42. 43. 44. 45. 46. 47. 48. 49. 50. 51. 52. 53. 54. 55. 56. 57. 58. 59. 60. 61. 62. 63. 64. 65. 66. LCD Character Set - Greece (Based on Code Page 869) . . . . . . . . . . . . . VFD II Character Set - Greece (Based on Code Page 869) . . . . . . . . . . . . . Video Display (VGA) Character Set - Greece (Based on Code Page 869) . . . . . . . 4680 Controller Video Display Character Set Greece (Based on Code Page 869) . . . . . 4690 Controller Video Display Character Set Greece (Based on Code Page 869) . . . . . Alphanumeric Display Character Set Multilingual (Based on Code Page 850) . . . LCD and VFD II Character Set - Multilingual (Based on Code Page 850) . . . . . . . Operator Display Character Set - Multilingual (Based on Code Page 850) . . . . . . . Printer Models 1 and 2 Character Set Multilingual (Based on Code Page 850) . . . Printer Models 3 and 4 Character Set Multilingual (Based on Code Page 850) . . . Video Display (Feature A) Character Set Multilingual (Based on Code Page 850) . . . Video Display (VGA) Character Set Multilingual (Based on Code Page 850) . . . 4680 Controller Video Display Character Set Multilingual (Based on Code Page 850) . . . 4690 Controller Video Display Character Set Multilingual (Based on Code Page 850) . . . Alphanumeric Display Character Set - Nordic (Based on Code Page 865) . . . . . . . LCD Character Set - Nordic (Based on Code Page 865) . . . . . . . . . . . . . Operator Display Character Set - Nordic (Based on Code Page 865) . . . . . . . Printer Models 1 and 2 Character Set - Nordic (Based on Code Page 865) . . . . . . . Printers Model 3 and Model 4 Character Set Nordic (Based on Code Page 865) . . . . . VFD II Character Set - Nordic (Based on Code Page 865) . . . . . . . . . . . Video Display (Feature A) Character Set Nordic (Based on Code Page 865) . . . . . Video Display (VGA) Character Set - Nordic (Based on Code Page 865) . . . . . . . 4680 Controller Video Display Character Set Nordic (Based on Code Page 865) . . . . . 4690 Controller Video Display Character Set Nordic (Based on Code Page 865) . . . . . LCD Character Set - Turkey (Based on Code Page 857) . . . . . . . . . . . . . Operator Display Character Set - Turkey (Based on Code Page 857) . . . . . . . VFD II Character Set - Turkey (Based on Code Page 857) . . . . . . . . . . . Video Display (Feature A) Character Set Turkey (Based on Code Page 857) . . . . . 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421

Copyright IBM Corp. 1985, 2003

vii

67. 68. 69. 70. 71. 72. 73. 74.

Video Display (VGA) Character Set - Turkey (Based on Code Page 857) . . . . . . . 4680 Controller Video Display Character Set Turkey (Based on Code Page 857) . . . . . 4690 Controller Video Display Character Set Turkey (Based on Code Page 857) . . . . . Alphanumeric Display Character Set - USA (Based on Code Page 437) . . . . . . . LCD Character Set - USA (Based on Code Page 437) . . . . . . . . . . . . . Operator Display Character Set - USA (Based on Code Page 437) . . . . . . . . . . Printer Models 1 and 2 Character Set - USA (Based on Code Page 437) . . . . . . . Printers Model 3 and Model 4 Character Set USA (Based on Code Page 437) . . . . .

75. 422 76. 423 77. 424 78. 425 79. 426 427 428 429 80. 81.

VFD II Character Set - USA (Based on Code Page 437) . . . . . . . . . . . . Video Display (Feature A) Character Set USA (Based on Code Page 437) . . . . Video Display (VGA) Character Set - USA (Based on Code Page 437) . . . . . . 4680 Controller Video Display Character Set USA (Based on Code Page 437) . . . . 4690 Controller Video Display Character Set USA (Based on Code Page 437) . . . . Shopper Display Character Set . . . . . Extended Codes for Store Controller Keyboard Input . . . . . . . . . .

. 430 . 431 . 432 . 433 . 434 . 435 . 439

viii


NoticesReferences in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only IBMs product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any of IBMs intellectual property rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, is the users responsibility. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785 USA.

TrademarksThe following terms are trademarks of the IBM Corporation in the United States or other countries or both:AIX AS/400 C/2 COBOL/2 Display Manager IBM Micro Channel NetView Operating System/2 OS/2 Personal System/2 PS/2 RS/6000 SAA System/370 Systems Application Architecture XT

Other company, product, and service names may be trademarks or service marks of others. Microsoft, Windows, Windows NT, and the Windows logo are trademarks or registered trademarks of Microsoft Corporation. Java, HotJava, JavaOS, and JavaOS for Business are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries and are used under license. The JavaOS for Business technology is the result of a collaboration of Sun and IBM. Java and HotJava are trademarks of Sun Microsystems, Inc.


ix

x


PrefaceThis manual explains how to write programs using IBM 4680 BASIC Licensed Program. IBM 4680 BASIC is based on CB86, a product of Digital Research.

How This Book is OrganizedThe manual is organized as follows: v Chapters 1 through 6 cover general IBM 4680 BASIC concepts such as data types, expressions, and user-defined functions. Read through these chapters for a general overview of IBM 4680 BASIC. v Chapter 7 presents the IBM 4680 BASIC statements and language-defined functions in alphabetical order for easy reference. v Chapter 8 explains how to use input and output (I/O) devices attached to the IBM 4680 or 4690 Store System. Explanations include files, file security, directories, host communications, and the I/O devices. v Chapters 9 through 12 contain all the operating instructions and information specific to the IBM 4680 BASIC compiler and utility software programs. v Chapter 13 explains how to interface IBM 4680 BASIC with Intel 80286 microprocessor assembly language. v The appendixes contain reference information, such as lists of error messages, ASCII codes, and character sets for display devices.

Where to Find More InformationA CD-ROM is available that contains the online manuals that are a part of the IBM Store Systems Library Collection, SK2T-0331.

Store System Related Publications SoftwareIBM 4690 V4 LibraryIBM IBM IBM IBM IBM IBM IBM IBM IBM IBM IBM IBM IBM IBM IBM IBM IBM Copyright IBM Corp. 1985, 2003

4690 4690 4690 4690 4690 4690 4690 4690 4690 4690 4680 4690 4690 4690 4690 4690 4680

OS OS OS OS OS

Version Version Version Version Version

4: 4: 4: 4: 4:

Planning, Installation, and Configuration Guide, GC30-4051 Programming Guide, SC30-4054 Users Guide, SC30-4050 Communications Programming Reference, SC30-4053 Messages Guide, SC30-4052

IBM 4690 OS V3 LibraryOS Version 3: Planning, Installation, and Configuration Guide, GC30-4045 OS Version 3: Users Guide, SC30-4044 OS Version 3: Programming Guide, SC30-4048 OS Version 3: Communications Programming Reference, SC30-4047 OS Version 3: Messages Guide, SC30-4046 BASIC: Language Reference, SC30-3356 OS Version 2: Planning, Installation, and Configuration Guide, GC30-3984 OS Version 2: Users Guide, SC30-3983 OS Version 2: Programming Guide, SC30-3987 OS Version 2: Communications Programming Reference, SC30-3986 OS Version 2: Messages Guide, SC30-3985 Store System: Preparing Your Site, GA27-3692

IBM 4690 OS V2 Library

xi

IBM 4680 BASIC: Language Reference, SC30-3356 IBM 4680 Store System: Display Manager Users Guide, SC30-3404 IBM 4690 Store System: 4690 Terminal Services for DOS Users Guide, SC30-3688

IBM 4680 and 4680-90 General Sales ApplicationIBM 4680-90 General Sales Application: Planning and Installation Guide, GC30-3630 IBM 4680-90 General Sales Application: Guide to Operations, SC30-3632 IBM 4680-90 General Sales Application: Programming Guide, SC30-3631 IBM 4680 General Sales Application Price Management Feature: Users Guide, SC30-3461 IBM 4680 General Sales Application Terminal Offline Feature: Users Guide, SC30-3499 IBM 4680-90 General Sales Application: Full Screen Guide to Operations, SC30-3664 IBM 4680-90 General Sales Application: Master Index, GX27-3958

IBM 4680 and 4680-90 Supermarket ApplicationIBM 4680-90 Supermarket Application: Planning and Installation Guide, GC30-3633 IBM 4680-90 Supermarket Application: Guide to Operations, SC30-3635 IBM 4680-90 Supermarket Application: Programming Guide, SC30-3634 IBM 4680 Supermarket Application Terminal Offline Feature: Users Guide, SC30-3512 IBM 4680 Supermarket Application Electronic Funds Transfer Feature: Users Guide, SC30-3513 IBM 4680-4690 Supermarket Application Electronic Funds Transfer Feature Enhancement: Users Guide, SC30-3718 IBM 4680-90 Supermarket Application: Master Index, GX273957

IBM 4680 Chain Drug Sales ApplicationIBM 4680 Chain Drug Sales Application: Planning and Installation Guide, GC30-3412 IBM 4680 Chain Drug Sales Application: Guide to Operations, SC30-3413 IBM 4680 Chain Drug Sales Application: Programming Guide, SC30-3414

IBM Systems Application ArchitectureIBM Systems Application Architecture: Common Programming Interface Communications Reference, SC26-4399

In-Store ProcessingIn-Store Processing: In-Store Processing: In-Store Processing: SC30-3538 In-Store Processing: In-Store Processing: Application Development Guide, SC30-3534 IBM AIX Application Development Guide, SC30-3537 IBM OS/2 Extended Edition Application Development Guide, IBM OS/400 Application Development Guide, SC30-3535 IBM 4680 OS Application Development Guide, SC30-3536

Store System Related Publications HardwareIBM SurePOS 700 Series TerminalsIBM SurePOS 700 Series Point-of-Sale: Installation and Operation Guide, GA274223 IBM SurePOS 700 Series Point-of-Sale: Hardware Service Manual, GY270363 IBM SurePOS 700 Series Point-of Sale: System Reference, SA274224 IBM SurePOS 700 Series Point-of-Sale: Hardware Service Guide for POS USB Devices, SY270392 IBM SurePOS 720, 740 and 780 Series Point-of-Sale: Planning, Installation and Operation Guide, GA274328

xii


IBM SurePOS 720, 740 and 780 Series Point-of-Sale: Hardware Service Guide, SA274329

IBM 4694 Point-of-Sale TerminalsIBM 4694 Point-of-Sale Terminals: Installation and Operation Guide, SA27-4005 IBM Store Systems: Installation and Operation for Point-of-Sale Input/Output Devices, GA27-4028 IBM 4693, 4694, and 4695 Point-of-Sale Terminals: Hardware Service Manual, SY27-0337 IBM Store Systems: Hardware Service Manual for Point-of-Sale Input/Output Devices, SY27-0339 IBM Store Systems: Parts Catalog, S131-0097

IBM 4693 Point-of-Sale TerminalsIBM 4693 Point-of-Sale Terminals: Installation and Operation Guide, SA273978 IBM Store Systems: Installation and Operation for Point-of-Sale Input/Output Devices, GA27-4028 IBM 4693 Point-of-Sale Terminals: Setup Instructions, P/N 73G1012 IBM 4693 Point-of-Sale Terminals: Quick Reference Card, P/N 73G1022 IBM 4693, 4694, and 4695 Point-of-Sale Terminals: Maintenance and Test Summary, SX27-3919 IBM 4693, 4694, and 4695 Point-of-Sale Terminals: Hardware Service Manual, SY27-0337 IBM Store Systems: Hardware Service Manual for Point-of-Sale Input/Output Devices, SY27-0339 IBM Store Systems: Parts Catalog, S131-0097 IBM 4693 Point-of-Sale Terminals: Reference Diskette, SX27-3918 IBM 4693 Point-of-Sale Terminals: Diagnostic Diskette, SX27-3928 IBM 4693 Point-of-Sale Terminals: Support Diskette for Medialess Terminals, SX27-3929

IBM 4683 Point-of-Sale TerminalsIBM 4683 Point-of-Sale Terminal: Installation Guide, SA27-3783 IBM 4683/4684 Point-of-Sale Terminal: Operations Guide, SA27-3704 IBM 4680 Store System and IBM 4683/4684 Point-of-Sale Terminal: Problem Determination Guide, SY27-0330 IBM 4680 Store System: Terminal Test Procedures Reference Summary, GX27-3779 IBM 4683/4684 Point-of-Sale Terminal: Maintenance Manual, SY27-0295 IBM Store Systems: Hardware Service Manual for Point-of-Sale Input/Output Devices, SY27-0339 IBM Store Systems: Hardware Technical Reference, SY27-0336 IBM Store Systems: Parts Catalog, S131-0097

ScannersIBM 1520 Hand-Held Scanner Users Guide, GA27-3685 IBM 4686 Retail Point-of-Sale Scanner: Physical Planning, Installation, and Operation Guide, SA27-3854 IBM 4686 Retail Point-of-Sale Scanner: Maintenance Manual, SY27-0319 IBM 4687 Point-of-Sale Scanner Model 1: Physical Planning, Installation, and Operation Guide, SA27-3855 IBM 4687 Point-of-Sale Scanner Model 1: Maintenance Manual, SY27-0317 IBM 4687 Point-of-Sale Scanner Model 2: Physical Planning Guide, SA27-3882 IBM 4687 Point-of-Sale Scanner Model 2: Operators Guide, SA27-3884 IBM 4687 Point-of-Sale Scanner Model 2: Maintenance Manual, SY27-0324 IBM 4696 Point-of-Sale Scanner Scale: Physical Planning, Installation, and Operation Guide, GA27-3965 IBM 4696 Point-of-Sale Scanner Scale: Maintenance Manual, SY27-0333Preface

xiii

IBM 4696 Point-of-Sale Scanner Scale: Specification Sheet, G221-3361 IBM 4697 Point-of-Sale Scanner Model 001: Maintenance Manual, SY27-0338 IBM 4697 Point-of-Sale Scanner Model 001: Physical Planning, Installation, and Operations Guide, SY27-3990

CablingA Building Planning Guide for Communication Wiring, G320-8059 IBM Cabling System Planning and Installation Guide, GA27-3361 IBM Cabling System Catalog, G570-2040 Using the IBM Cabling System with Communication Products, GA27-3620

NetworksIBM Local Area Network Support Program, IBM P/N 83X7873 IBM Token-Ring Network Introduction and Planning Guide, GA27-3677 IBM Personal System/2 Store Loop Adapter/A: Installation and Setup Instructions, SK2T-0318

General PublicationsAdvanced Data Communications for Stores General Information, GH20-2188 Distributed Systems Executive General Information, GH19-6394 Communications Manager X.25 Programming Guide, SC31-6167 IBM Proprinters, SC31-3793 IBM 4680 Support for COBOL Version 2 (Softcopy provided with the product) IBM 4680 Store System Regression Tester (Softcopy provided with the product) IBM 4680 X.25 Application Programming Interface, GG24-3952 NetView Distribution Manager: General Information, GH19-6587 Systems Network Architecture: General Overview, GC30-3073 IBM Local Area Network Administrators Guide, GA27-6367 DSX Preparing and Tracking Transmission Plans, SH19-6399 IBM Dictionary of Computing (New York; McGraw-Hill, Inc., 1993) DSX Preparing and Tracking Transmission Plans, SH19-6399 IBM Local Area Network Support Program, IBM P/N 83X7873 The Ethernet Management Guide Keeping the Link, Second Edition (McGraw-Hill, Inc., ISBN 0-07-046320-4)

xiv


Chapter 1. IntroductionIBM 4680 BASIC is a high-level language and compiler that allows you to develop application programs and user exits for your IBM 4680 or 4690 Store System. (The linker utility, the library utility, the postprocessor utility, and the BASIC runtime subroutine libraries are shipped with the IBM 4680 or 4690 Operating System.) The first thing to do after you unpack your IBM 4680 BASIC program diskette is to copy all the files onto your systems fixed disk. Then make a backup copy of the diskette. Store the diskette and its backup copy in a safe place. Table 1 is a brief description of all the files on the diskette.Table 1. IBM 4680 BASIC Licensed Program Subcomponent Information Files Compiler * for Version 3 only File Name README.DOC BASIC.EXE Description File containing information on this product BASIC Compiler (DOS or OS2)*

Runtime Subroutine LibrariesThe runtime subroutine libraries are packaged with the IBM 4680 or 4690 Operating System. To create an IBM 4680 BASIC application program, use the LINK86 utility program to link the object modules generated by the compiler with a runtime subroutine library. The runtime subroutine library used must correspond to the appropriate memory model. See the IBM 4680 Store System: Programming Guide or the IBM 4690 OS Version 3: Programming Guide for information on the linker utility. See Memory Models on page 285 for information on memory models. The runtime subroutine libraries contain object modules that support functions required by the IBM 4680 BASIC statements and functions. These functions include data initialization, memory management, type conversion, integer and floating point arithmetic, character string manipulation, input/output, and overlay management. There are three types of BASIC runtime libraries delivered with the IBM 4680 or 4690 Operating System. The runtime libraries called SB286M.L86 (Medium Memory Model Terminal), SB286LT.L86 (Big Memory Model Terminal), and SB286L.L86 (controller) are the libraries the linker uses to link with your application object modules. Two other library files are also linked with your object files. These are SB286TVM.L86 (Medium Memory Model Terminal) and SB286TVL.L86 (controller). You do not have to specify any of these libraries because the linker automatically includes them. For terminal applications and controller applications that are linked with the NOSHARED option (default for terminals), both the runtime code and data are included in the generated load module. For controller applications that are linked with the SHARED option (default for controllers), only the runtime data is included in the load module. This is because the controller runtime library used during execution is shared by all active BASIC applications. This library is called ADXACRBW.SRL.


1

An IBM 4680 BASIC DemonstrationThe following demonstration begins with an IBM 4680 BASIC source program you can try on your system. Then, it shows you the standard procedures used to create an IBM 4680 BASIC application program. You must already know how to use your operating system and text editor program. 1. Write the source program. Note: For this demonstration, the fixed disk is drive C and contains the files copied from your IBM 4680 BASIC program diskette. Using your text editor, create a file named TEST.BAS. Enter the following program into TEST.BAS exactly as it appears below.%ENVIRON C PRINT FOR I% = 1 TO 10 PRINT I%; "TESTING BASIC COMPILER!" NEXT I% PRINT PRINT "FINISHED" END

TEST.BAS uses a simple FOR/NEXT loop to print a short series of messages on your screen. 2. Compile the program. To start the IBM 4680 BASIC compiler program, enter the following on the command line:C>BASIC TEST

IBM 4680 BASIC assumes a .BAS filetype for any source file named in the command line, unless you specify another filetype. Source files that serve as input for IBM 4680 BASIC can be any filetype. IBM 4680 BASIC displays a heading banner, a listing of the source program, and several messages that pertain to the internal functions of the compiler. Version and serial numbers in the heading banner vary for different versions of the compiler. Code segment size and data segment size may vary.BASIC TEST -------------------------------------------------IBM 4680 BASIC Compiler mm/dd/yy Version x.x XXXX-XXX (c) Copyright IBM Corp 1986-1991. Licensed Material - Program Property Of IBM. (c) Copyright Digital Research, Inc. 1985. -------------------------------------------------end of pass 1 end of pass 2 End of Compilation Large Memory Model controller Code Generation --------------------------------------------Code segment size: 005AH (90 bytes) Data segment size: 0027H (39 bytes) ---------------------------------------------

The absence of error messages indicates a successful compilation. See Chapter 9, IBM 4680 BASIC Compiler Operation for more information on how the compiler operates. IBM 4680 BASIC creates an object file for the TEST.BAS program. The directory for drive C should now contain the object file TEST.OBJ. 3. Link the program.

2


Note: LINK86 assumes an .OBJ filetype for any object file names in the command line. LINK86 displays a heading banner and several messages that give the size of the load module created by the linker. Version and serial numbers in the heading banner vary for different versions of the linker. Code and data size may vary for different system configurations. See the IBM 4680 Store System: Programming Guide or the IBM 4690 OS Version 3: Programming Guide for additional information about the linker program. To start the LINK86 linker program, enter the following command line:C>LINK86 TEST -------------------------------------------------LINK86 Linkage Editor mmm dd 19yy vers.x.xx Copyright (C) 1982, 1989 Digital Research, Inc. --------------------------------------------------

.................................................. ..................................................CODE DATA STACK 0096D 00ABA 00A00

If you receive no error messages, the program has been linked successfully. LINK86 creates a directly executable program. The directory for drive C should now contain the program file, TEST.286. 4. Postprocess the load module (see the IBM 4680 Store System: Programming Guide or the IBM 4690 OS Version 3: Programming Guide for additional information). The POSTLINK utility is a postprocessor program that converts a LINK86 load module (ealts001.286, for example) into a module that can be loaded more quickly and use memory more efficiently in an iAPX 286(1) protected mode environment. Use of the POSTLINK utility is mandatory for all load modules that have been linked with the LINK86 CODESHARED option. This means that 4683 terminal programs must be POSTLINKED. To start the POSTLINK postprocessor, enter the following command line:C>POSTLINK TEST.286

POSTLINK displays a heading banner and at least one message. The version in the heading banner varies for different versions of the postprocessor. The message File successfully post linked generated by POSTLINK indicates it successfully executed.-------------------------------------------------IBM 4680 Linkage Postprocessor Version 1.00 5669-034 (c) Copyright IBM Corp 1986 All Rights Reserved. Licensed Materials Property of IBM. -------------------------------------------------File successfully post linked

The directory for drive C now contains a new version of the file, TEST.286. 5. Run the program. To run the TEST.286 program, enter the following command line:C>TEST

The following output should appear on your terminal:1 2 3 4 5 6 7 8 TESTING TESTING TESTING TESTING TESTING TESTING TESTING TESTING BASIC BASIC BASIC BASIC BASIC BASIC BASIC BASIC COMPILER! COMPILER! COMPILER! COMPILER! COMPILER! COMPILER! COMPILER! COMPILER!Chapter 1. Introduction

3

9 TESTING BASIC COMPILER! 10 TESTING BASIC COMPILER! FINISHED C>

4


Chapter 2. Elements of IBM 4680 BASICThe primary elements of IBM 4680 BASIC are: v Characters v Identifiers v Statements v Lines.

The Character SetIBM 4680 BASIC uses an American Standard Code for Information Interchange (ASCII) character set consisting of 256 characters (see Appendix F, Character Sets For Terminal Printers, Displays, and Controller Video Display). Most of the characters can be printed. An IBM 4680 BASIC program can contain uppercase and lowercase letters (A through Z), digits (0 through 9), and a group of special characters (such as the comma and dollar sign) that have predefined meanings in an IBM 4680 BASIC program. Table 2 on page 6 shows the IBM 4680 BASIC special characters.


5

Table 2. IBM 4680 BASIC Special Characters Character & * \ ^ : , . " $ = ! > ( < % + # ) / Purpose variable length string field for formatted printing multiplication operator continuation symbol exponentiation operator separates statements on the same logical line or designates a label identifier separates variables in an input or output statement decimal fraction delimiter or period string delimiter string type declaration character assignment or comparison operator comment delimiter comparison operator used to delimit function parameters and control the evaluation order in expressions comparison operator subtraction operator or unary negative symbol integer type declaration character addition or concatenation operator, unary positive symbol I/O session indicator used to delimit function parameters and control the evaluation order in expressions division operator

All characters have a corresponding numeric value that defines a hierarchy among the characters. This hierarchy defines a collating order for sorting strings of characters. You can use most of the 256 ASCII characters in a string (see Appendix F, Character Sets For Terminal Printers, Displays, and Controller Video Display). You cannot use a carriage return (0D hex) or an end-of-file marker (1A hex) in a string. IBM 4680 BASIC compares two character strings, one character at a time, according to the collating order. Using the collating order, you can write programs that alphabetize.

IdentifiersAn identifier is a series of characters treated as a single unit. Identifiers serve as statement labels, variable names, array names, names for subprograms, and names for user-defined functions. Identifiers can be of any length. However, only the first 50 characters are meaningful for distinguishing one identifier from another. The data type is always determined by the last character, even if the identifier is longer than 50 characters. The IBM 4680 BASIC compiler does not distinguish between uppercase and lowercase characters, except for string variable data.

6


The first character of an identifier must be a letter or a question mark. The remaining characters can be letters, numerals, or periods. The last character of an identifier is significant. In the absence of a data-type declaration, using an INTEGER, REAL, or STRING statement, the last character determines the type of data the identifier can represent. v Identifiers ending with a $ represent string data. v Identifiers ending with a % represent 2-byte integer numbers. v Identifiers ending with a : represent statement labels. v Identifiers that do not end with a $, :, or % represent real numbers. In an identifier, you can use the special characters $, :, and % only as the last character. Note: A data-type declaration using an INTEGER, REAL, or STRING statement overrides the data type indicated by the last character. You must use the INTEGER statement to declare both 1 and 4-byte integer identifiers. See INTEGER Statement on page 92 for additional information. The following examples are valid IBM 4680 BASIC identifiers:A NEW.SUM file.name$ Payroll.Identification.Number% subroutine1

A reserved word is an identifier that is reserved for a specific purpose. See Appendix C, IBM 4680 BASIC Reserved Words. For example, PRINT and INPUT are reserved words that identify two statements (see Chapter 7, Statements and Language-Defined Functions). VAL and STR$ are reserved words that identify two language-defined functions. You cannot use a reserved word in context other than the context for which it is designed.

Statements and LinesSyntactic items such as labels, keywords, variable names, constants, operators, and special characters form IBM 4680 BASIC statements. The following examples are valid IBM 4680 BASIC statements:PRINT "This is a PRINT statement." 10 PRINT "This is a labeled PRINT statement." GOTO 10 INPUT "Enter a number:"; NUM GOSUB subroutine1

IBM 4680 BASIC allows you to use spaces freely to make programs readable. You do not have to use statement numbers or labels except when you reference an individual statement in a program using a GOTO, GOSUB, IF END, or ON ERROR statement. You can use literal identifiers, integers, decimal fractions, and exponential numbers as statement labels.

Chapter 2. Elements of IBM 4680 BASIC

7

You must place a colon at the end of any literal identifier used as a label. Literal identifiers used as labels cannot be used in any other way within the program. The following examples are valid statement labels:0 100 100.0 21.543 module5: 792E3

The compiler treats numeric labels as strings of characters, not as numeric quantities. Thus, the two labels 100 and 100.0 are distinct IBM 4680 BASIC statement labels. An identifier used as a label can be any length, but only the first 31 characters are used to identify one label from another. You type statements on lines. A line is ended by a carriage return and line-feed. Every time you press the return or enter key on your terminal, you start a new line, delimiting the current line with a carriage return and line-feed. Statements can span more than one line. The backslash character (\) continues a statement on the next line. The compiler does not process any characters that follow a backslash on the same line, thus providing one method of program documentation. The backslash is not a continuation symbol if used within a character string. Note: If you have a continuation symbol (backslash) in a line that is commented out (a line beginning with !) then the next line is also commented out. This occurs even if the next line does not begin with an exclamation point. The following is an example of a backslash used as a continuation symbol.IF X = 3 THEN \ compiler ignores characters after backslash PRINT "THE VALUES ARE EQUAL" \ ELSE \ GOSUB 1000

In most cases, you can write multiple statements on the same line. Use a colon (:) to separate statements that appear on one line. Note: Declaration statements cannot appear on the same line with other statements. The IF and END statements can follow other statements on the same line. The following is an example of the colon used to indicate multiple statements on one line.PRINT TAB(10);"X": READ #1;NAME$: GOTO 1000

The REMARK statement (or the ! character) allows unlimited program remarks. See REMARK Statement on page 138 for an explanation of the REMARK statement. Use the REMARK statement and spaces to improve the readability of your programs. Note: Extra remarks, long variable names, and blank spaces do not affect the size of your compiled programs.

8


Chapter 3. Data TypesThe three data types of IBM 4680 BASIC are: v Integer v Real v String. Integer and real are numeric data types. String is the data type for text. The various numeric data types may be mixed in arithmetic expressions. See Mixed Arithmetic Expressions on page 17 for a description of mixed arithmetic expressions.

ConstantsA constant is a literal representation of numeric or text data in a program. Constants remain unchanged during program execution. You can use integer, real, and string constants in a program. This chapter shows examples of constants of the three data types.

Integer Data TypeAn integer is any positive or negative whole number or zero. Zero is neither positive nor negative. Integers have no fractional component. Therefore, they cannot contain decimal points. You can write integers with a leading sign. If you omit the sign, the integer is assumed to be positive. The integers 721 and +721 represent the same value. The following examples are valid integer constants.1 642 +25 9287 -41 -32768 0

Using the INTEGER statement, described in INTEGER Statement on page 92, you can specify integers that occupy 1, 2, or 4 bytes of memory depending on your requirements. If the size is not specified, the default of 2 bytes is used. Integers of 1 and 2 bytes use less memory than 4-byte integers, but do not cause an error when an overflow condition occurs; however, the value is erroneous. The following table shows the integer sizes and the range of values each can hold.Table 3. Integer Sizes and Range of Values Declaration INTEGER*1 INTEGER*2 INTEGER*4 Memory Required 1 byte 2 bytes 4 bytes Range of Values -128 to +127 -32768 to +32767 -2147483648 to +2147483647

You can express integers in IBM 4680 BASIC as hexadecimal or binary constants. The first character in a hexadecimal constant must be numeric. For example, the decimal number 255 is represented in hexadecimal as 0FFH, not FFH. The compiler interprets the letters FFH as an identifier. The last character of a hexadecimal constant must be the letter H. Binary constants use only the digits 0 and 1. The last character of a binary constant must be the letter B. Neither hexadecimal nor binary constants can contain a decimal point. Copyright IBM Corp. 1985, 2003

9

The following examples are hexadecimal and binary integer constants.2ab0H 01011B 0FFFFH 10111110B 8BC2H

Real Data TypeA real number is any number that can express a fractional component, an exponent, or both. Real numbers can be either positive or negative. You can write real numbers in either fixed-format or exponential notation. The fixed-format real number consists of an optional sign, an integer component, a decimal point, and a fractional component. The following examples are fixed-format real number constants.1.5 +82.7 .007 375. -794.0 -.299999

Exponential notation consists of a real number or integer constant followed by the letter E and an optionally signed integer. The value of a number expressed in exponential notation is the product of the real or integer constant (the mantissa) that precedes the E and the power of 10 indicated by the integer (the exponent) that follows the E. Exponential notation implies the existence of a decimal point. Therefore, numbers in exponential notation that represent integers are still interpreted as real data. The following examples are real numbers expressed in exponential notation.5.82E2 314159.00E-5 -.229E-3 11E5 -5E-2 -100E+8 = = = = = = 582.0 3.14159 -.000229 1100000 -.05 -10000000000

Real numbers can represent positive or negative values that range from 1.0E-64 to 9.99999999999999999E62. IBM 4680 BASIC rounds (half adjusts) all real constants to 18 digits of precision and maintains only 18 digits of precision internally.

String Data TypeThe string data type enables a program to process text information. A string is a series of characters enclosed in quotation marks. You can use any 8-bit ASCII character within a string, including blanks and quotation marks, except for a carriage return line feed (0D0A hex) and an end-of-file marker (1A hex). A null string contains no characters and consists of two adjacent quotation marks. The following examples are string constants."Houston, TX "July 4, 2000" "Please enter your password:" " " 72433"

10


To place a quotation mark within a string, use two consecutive quotation marks for each one you want to represent within the string, as shown in the following example:"The report indicated that ""profits were substantial""."

The length of a string constant is the number of characters, including blanks, that appear between the delimiting quotation marks. The delimiting quotation marks do not count in the length of the string. Two consecutive quotation marks within a string count as one character. The maximum length that a string can be is 65,520. The maximum usable string length depends on the size of your stack, because the stack is used to hold temporary strings. See Character Expressions on page 18. In the following examples, the length of the first string is 27 and the length of the second string is 17."Please enter your password." """Cash or Charge."""

String constants must fit on one physical line and cannot exceed 255 characters in length. String constants cannot contain a carriage return. To build strings longer than 255 characters, concatenate shorter string variables together. Note: The backslash character (\) has no special significance in a string constant.

Data Type DeclarationsYou can declare the data type for an identifier in a program by using one of the type statements, string, integer, or real. Make all data type declarations at the beginning of a function, subprogram, or main program, before any executable statements. See Chapter 7, Statements and Language-Defined Functions, on page 33 for an explanation of each statement.

Chapter 3. Data Types

11

12


Chapter 4. Variables and ArraysTo develop efficient IBM 4680 BASIC programs, you must understand the correct use of variables and arrays. This chapter explains variables and arrays and how to use them in developing your programs.

VariablesA variable is an identifier that can represent different values during the execution of a program. When a variable is referenced during program execution, the program uses the value assigned to the variable at that point in the execution of the program. IBM 4680 BASIC automatically initializes all numeric variables to 0 and all string variables to null. One way to assign a value to a variable is with an assignment statement. An assignment statement evaluates an expression to the right of an equal sign and assigns the resulting value to an identifier to the left of the equal sign. For example, a simple integer variable named intvar% assumes the value 14 in the following IBM 4680 BASIC assignment statement.intvar% = 12 + 2

IBM 4680 BASIC evaluates the expression 12 + 2 and assigns the resulting value to intvar%. The variable intvar% can assume values other than 14 during execution of the program. The following is another example of an assignment statement.intvar% = intvar% + 1

After the second assignment statement executes, the value of the variable intvar% changes from 14 to 15. See Chapter 5, Expressions for more information on assignment statements and expressions. Another way to assign a value to a variable is with an INPUT statement. The INPUT statement assigns the value the user enters to a variable during execution of the program. The following INPUT statement example requests you to enter a name.INPUT "Please enter your first name"; name$

All subsequent references to the variable name$ in the program use the value assigned to name$ with the INPUT statement. The program continues to use that value until another value is assigned to name$. A string variable does not have a fixed length associated with it. Instead, as different strings are assigned to the variable, the program allocates storage space as required (dynamically) for strings of different lengths. The maximum length a string variable can represent is 65,520 characters. All variables that you declare in a subprogram or function are local to that subprogram or function. This means that they are unknown or undefined outside of the subprogram or function. See Scope of Data on page 31 for more information on the scope of variables in an IBM 4680 BASIC program. Copyright IBM Corp. 1985, 2003

13

ArraysAn array is a group of variables (values) that are assigned a single identifier. Each variable in an array is called an element. An array can be of type integer (1, 2, or 4 bytes), real, or string and can only represent values of the assigned data type. The elements of an array are organized into dimensions. Dimensions enable you to organize data defined in your program. Each element in an array is a variable and can take on different values during program execution. The program can reference each array element just like an ordinary variable. However, with an array you can reference all the elements by changing the array index. To specify an array in a program, you must use the DIM statement. You specify an identifier in the statement that serves as the array name, a subscript list that determines the number of dimensions in the array and the number of elements in each dimension. An array in IBM 4680 BASIC can have a maximum of 15 dimensions. The value of a subscript plus 1 determines the number of elements in that dimension. You add 1 to the value of the subscript to determine the number of elements because all subscripts in IBM 4680 BASIC have an implied lower bound of 0. The first element in an array dimension is always 0. To simplify array element referencing, programmers frequently ignore the 0 element in an array or use it as a special indexing feature. In this way, the first element used in the array is number 1, the second element used is number 2 and so on. When you use the 0 element as the first element, the referencing procedure becomes confusing, because the second element is the number 1 element, the third element is number 2 and so on.

14


Chapter 5. ExpressionsAn expression is a sequence of characters that evaluates to a single value. IBM 4680 BASIC supports both numeric and character expressions. You can specify calculations in an expression using special characters called operators. Operators specify the calculations to perform using the values you enter in the expression. The expression values are called operands. An expression can be a single constant or variable with no operators, or it can be a complex combination of constants, variables, function references, and operators. The four expressions used in IBM 4680 BASIC are: v Arithmetic v Character v Relational v Logical.

Arithmetic ExpressionsArithmetic expressions represent numeric values. An arithmetic expression uses arithmetic operands, a special set of arithmetic operators, and parentheses to control the evaluation order of the operations specified in the expression. The five IBM 4680 BASIC arithmetic operators are shown in Table 4.Table 4. Arithmetic Operators Operator + * / ^ Purpose Addition (unary positive) Subtraction (unary negative) Multiplication Division Exponentiation

The operators *, /, and ^ are binary. This means the operators work with two operands, one on either side of the operator. The operators + and - can work as binary operators, or unary operators that work on a single operand to the right of the operator. The following examples show how to interpret expressions that use arithmetic operators: +OP1 Identifies OP1 as positive.

OP1 + OP2 Adds OP1 to OP2. - OP2 Identifies OP2 as negative. OP1 - OP2 Subtracts OP2 from OP1. OP1 * OP2 Multiplies OP1 by OP2.


15

OP1 / OP2 Divides OP1 by OP2. OP1^OP2 Raises OP1 to the power OP2. Precedence among the arithmetic operators follows the standard rules of algebra and is shown in Table 5.Table 5. Precedence Among Arithmetic Operators Operator ^ * and / + and Precedence 1 2 3

When an expression contains two or more operators of equal precedence, such as * and /, the operations are evaluated algebraically from left to right. You can use parentheses to control the evaluation order of the operations specified in an arithmetic expression. The portions of an expression that you enclose in parentheses are evaluated first. The use of parentheses supersedes the precedence among operators. The following examples demonstrate the evaluation order of operations within arithmetic expressions, according to operator precedence and the use of parentheses:Without parentheses 25 + 15 - 10 +12 = 42 | | | 1st 2nd 3rd 3 + 4 * 3 - 5 = 10 | | | 2nd 1st 3rd 100 - 10 ^ 2 * 3 = -200 | | | 3rd 1st 2nd 11 + 3 * 2 - 10 / 2 = 12 | | | | 3rd 1st 4th 2nd With parentheses (25 + 15) - (10 + 12) = 18 | | | 1st 3rd 2nd 3 + 4 * (3 - 5) = -5 | | | 3rd 2nd 1st (100 - 10 ^ 2) * 3 = 0 | | | 2nd 1st 3rd ((11 + 3) * 2 - 10) / 2 = 9 | | | | 1st 2nd 3rd 4th

In the preceding examples, all the operands are unsigned integer constants. However, you can use operands in a variety of forms within an arithmetic expression. An arithmetic operand can be any one of the following: v An integer constant v A real number constant v A numeric variable v A numeric array element reference v An arithmetic function reference.

16


The data type of an arithmetic expression is determined by the data types of the operands specified in the expression. An arithmetic expression that contains only integer operands will have an integer data type.

Mixed Arithmetic ExpressionsMixed arithmetic expressions have operands of different numeric data types. When evaluating mixed arithmetic expressions, the runtime library considers only one operator at a time and its two operands. See the example at the end of this section. The following rules apply to the conversion of numeric data types in a mixed arithmetic expression: v In an arithmetic expression that contains real numbers and integers, the integers are converted to real numbers. The resulting expression has a real data type. v In an arithmetic expression that contains integers of different sizes, the smaller sized integers are converted to the size of the larger integers. For example, in an expression that contains 2-byte and 4-byte integers, the 2-byte integers are converted to 4-byte integers. The resulting expression has a 4-byte integer data type. Note: In an arithmetic expression, if an operation on the right side of the equal sign overflows, the overflow data is lost even though the variable on the left side of the equal sign is of a larger integer type or real data type. When a 1-byte integer or 2-byte integer variable overflows, no error indication is given. When a 4-byte integer variable overflows, an OI error is returned to the application. Following are examples of overflow losses:INTEGER*1 A,B INTEGER*2 C,D INTEGER*4 E,F,G

Example 1A = 100 B = A * 3 B is 44

The data overflow of 1-byte integer capacity is lost.

Example 2B = 3 C = A * B C is 44

The right side completes its operations in 1-byte integer mode and therefore overflows. The overflow is lost even though C is a 2-byte integer.

Example 3C = 3 D = A * C D is 300

There is no overflow because C is a 2-byte integer variable and A is converted to 2-byte integer before the operation is done and the results do not overflow the 2-byte integer capacity.

Example 4A D E E = 100 = 60000 = A * D is -29312 There is an overflow. A is converted to a 2-byte integer to match D, but the operation overflows the 2-byte integer capacity. The high order bit of the 2-byte result is on so the bit is propagated through the two high bytes of E (a 4-byte integer variable) making the number negative.

Example 5

Chapter 5. Expressions

17

E = 60000 F = 600000 G = E * F

This operation results in a 4-byte integer overflow causing an OI error to be returned to the application.

v The result of an arithmetic expression assigned to a variable is automatically converted to the data type of the variable regardless of the operand data types. An example of a mixed arithmetic assignment statement follows:REAL R INTEGER*2 I2 I2 = 1000 R = 4.1 * (10/I2) + 10.1 PRINT R

This program example prints the value of 10.1, because the expression 10/I2 is equal to zero. Zero times 4.1 is zero.

Character ExpressionsCharacter expressions enable you to manipulate character strings. A character expression uses character string operands and a character operator. All character expressions evaluate to a single character string value. The character operator is the plus sign (+). In character expressions, the plus sign is called the concatenation operator. The concatenation operator simply joins two character strings together. The following character expressions evaluate to the string values IBM 4680 BASIC and IBM 4680 BASIC COMPILER:"IBM 4680 " + "BASIC" "IBM 4680 BASIC " + "COMPILER"

In the previous examples, the operands are string constants. However, you can use string variables and string array elements as operands in character expressions. The use of parentheses does not affect the value of a character expression. The length of a character expression equals the sum of the lengths of the individual character string operands. The sum of the lengths includes any spaces that are part of an operand. For example, the following expression has a length of 19."ENTER " + "YOUR PASSWORD"

Quotation marks are not considered part of an operand and are not included in the length of a string. Notes: 1. Many items concatenated in a single statement may cause the compiler to abnormally end with the message Stack has overflowed into the heap. 2. The string operations such as functions returning a string or concatenation take place in the stack. Since the stack size in the terminal is limited to 2k bytes, the size of the string is limited. If the string is too large, a Stack Fault exception or General Protection exception occurs and you get either an Application dump with W051 PROGRAM PROBLEM or W103 PROGRAM PROBLEM DEFAULT LOADING.

18


Relational ExpressionsA relational expression compares the values of two operands, using a special set of relational operators. Relational expressions evaluate to a logical value, either true or false. In IBM 4680 BASIC, 0 indicates false and -1 indicates true. A single relational expression can only compare two arithmetic expressions or two character expressions. A relational expression cannot compare an arithmetic expression to a character expression. The six relational operators are shown in Table 6.Table 6. Relational Operators Operator < >= = Mnemonic LT LE GT GE EQ NE Meaning Less than Less than or equal to Greater than Greater than or equal to Equal to Not equal to

You can use either the operator symbol or a mnemonic representation in an expression. In an arithmetic relational expression, IBM 4680 BASIC first evaluates the arithmetic operands, then compares the resulting values to determine if the relationship specified by the relational operator exists. See the following example.100 - 50 > 100 / 50 50 2

IBM 4680 BASIC first evaluates the arithmetic expressions on either side of the > operator. Following this first evaluation, the relational expression states that 50 is greater than 2. IBM 4680 BASIC then evaluates the validity of the expression. Since 50 is greater than 2, the value of this relational expression is true. A relational operator can compare two arithmetic expressions of different data types. IBM 4680 BASIC converts the expression containing the lower ranked data type to the data type of the other expression before making a comparison. Real numbers are ranked highest, followed by 4-byte integers, 2-byte integers, and 1-byte integers. In a character relational expression, IBM 4680 BASIC first evaluates the character operands, then compares the resultant values to determine if the relationship specified by the relational operator exists. See the following example:"APP" + "LE" < AP + RICOT

IBM 4680 BASIC evaluates the character expressions on either side of the < operator. Following the evaluation, the relational expression states that the string APPLE is less than the string APRICOT. In character relational expressions, operands are evaluated according to the ASCII collating sequence. The length of the character operands is not significant forChapter 5. Expressions

19

comparison. If the two character operands have different lengths, the shorter operand is padded on the right with blank characters until the two strings are equal. In the Apple/Apricot example, the string APPLE has a length of 5 and the string APRICOT has a length of 7. Therefore, IBM 4680 BASIC pads APPLE on the right with two blank characters to make the strings equal in length. Then, IBM 4680 BASIC compares the two strings one character at a time. The first two letters in both strings, AP, are equal. However, the third letters are different. APPLE has a P and APRICOT has an R. According to the collating order, P is less than R. Therefore, the string APPLE is less than the string APRICOT and the relational expression is true. All IBM 4680 BASIC relational operators have equal precedence. The arithmetic and character operators have a higher precedence than the relational operators. Therefore, IBM 4680 BASIC evaluates arithmetic and character operations before relational operations.

Logical ExpressionsLogical expressions compare operands using a special set of logical operators. All logical expressions evaluate to a single logical value. You can use parentheses to control the evaluation order of the operations specified in a logical expression. All logical expressions in a statement are evaluated before a final value is reached. Table 7 shows the four logical operators in IBM 4680 BASIC. NOT is a unary operator. The others are binary operators.Table 7. Logical Operators Operator NOT AND OR XOR Meaning logical negation logical conjunction logical inclusive disjunction logical exclusive disjunction

The interpretation of expressions formed using each of the logical operators is shown in the following examples: OP1 AND OP2 The expression is true only if both OP1 and OP2 are true. OP1 OR OP2 The expression is true if either OP1 or OP2 is true, or if both are true. OP1 XOR OP2 The expression is true if either OP1 or OP2 is true, but false if both OP1 and OP2 are true or if both OP1 and OP2 are false. NOT OP1 The expression is true only if OP1 is false.

20


Table 8 shows the precedence among the logical operators.Table 8. Precedence Among Logical Operators Operator NOT AND OR XOR Precedence 1 2 3 4

You can use parentheses to control evaluation order. The following examples demonstrate the evaluation order of operations within logical expressions according to operator precedence and the use of parentheses:6*3+4 < 25 AND 4 VAL2% THEN \ LARGEST% = VAL1% \ ELSE \ LARGEST% = VAL2% FEND I% = LARGEST%(10,20) J% = LARGEST%(100,25) PRINT "the larger of 10 and 20 is ";I% PRINT "the larger of 100 and 25 is ";J% PRINT "the larger of 5 and 7 is ";LARGEST%(5,7) END

Output Output for the sample program is:the larger of 10 and 20 is 20 the larger of 100 and 25 is 100 the larger of 5 and 7 is 7

DELETE StatementSyntaxDELETEI/O session number ........ , .........

Use

store controller and terminal

Explanation DELETE erases the file, releases the I/O session number, and then reallocates all buffer space that the file used. An IF END statement assigned to the I/O session number has no further effect, unless you reassign the I/O session number with a CREATE or OPEN statement. If the file associated with the I/O session is still open somewhere else within the same program or by another program, the DELETE fails and a runtime error occurs. Do not issue a CLOSE statement after a file is deleted or a runtime error occurs. I/O session number is the number assigned to a file in the CREATE or OPEN statement. Example Sample ProgramChapter 7. Statements and Language-Defined Functions

63

DELETE Statement! ! ! ! The following example uses the DELETE statement to delete a new file created with the CREATE statement. See the CREATE statement in this chapter.

CREATE "TESTFILE.TMP" RECL 25 AS 10 PRINT "creating new file called TESTFILE.TMP" PRINT DELETE 10 PRINT "deleting the new file" PRINT "thats all folks" END

Output Output for the sample program is:creating new file called TESTFILE.TMP deleting the new file thats all folks

DELREC StatementSyntaxDELRECI/O session number;key value

Use


Explanation The DELREC statement deletes the record specified by the key value string from the KEYED file that was opened using the specified I/O session number. The length of the key value must equal that specified for the key length parameter in the CREATE POSFILE KEYED statement used to create the file. When you delete a keyed record, the system automatically adjusts the forward and backward chain pointers (if necessary) associated with that record. The vacated space is available for records you may add. v I/O session number is the number assigned to a file in the CREATE or OPEN statement. v Key value is a string that must be equal in length to the key value specified in the CREATE POSFILE KEYED statement used to create the file. If the key is not found, the current ON ERROR routine gets control with ERR=EF and ERRN=80F306C8 unless an IF END statement is in effect. Example Sample Program! The following example uses the DELREC statement ! to delete the record identified by the key value ! variable KEY$. INTEGER*4 A%,B% STRING C$,D$,DATA$,KEY$ PRINT "OPEN KEYED FILE AND WRITE/DELETE" CREATE POSFILE "A:KEYEDTST" KEYED 4 ,,, 10 RECL 14 AS 6 KEY$ = "3456" A% = 32123 DATA$ = "KEYED" PRINT "WRITE KEYED FILE" WRITE FORM "C4,I4,C6" ; #6 ; KEY$,A%, DATA$

64


DELREC StatementPRINT "KEYED FILE WRITTEN" READ FORM "C4,I4,C6" ; #6 KEY KEY$ ; C$,B%,D$ DELREC 6; KEY$ PRINT "DELETING THE FILE RECORD" PRINT "THATS ALL FOLKS" CLOSE 6 END

Output Output for the sample program is:OPEN KEYED FILE AND WRITE/DELETE WRITE KEYED FILE KEYED FILE WRITTEN DELETING THE FILE RECORD THATS ALL FOLKS

DIM StatementSyntaxDIMidentifier (subscript) .....,.....

Use


Explanation The DIM statement dynamically allocates storage space for both numeric and string arrays, and specifies the upper bound of each subscript in the subscript list. The maximum number of elements in an array is limited to 65,520 bytes of storage. The amount of available memory in the heap may constrain the actual number of elements for which you can define dimensions. Initially, IBM 4680 BASIC sets the individual elements to zero in numeric arrays, and to null in string arrays. Each execution of a DIM statement allocates a new array. You can redimension an existing array in a program with a second DIM statement. If you dimension an array, all data in the original array is lost. The once-used space is only recovered IF the array is redimensioned with zero elements. v Identifier is an array name. v Subscript list contains the number of subscripts that determine the number of dimensions in the array. The number of subscripts is limited to 15. The value of each subscript plus one equals the number of elements in each dimension. All subscripts have an implied lower bound of zero. Arrays which will not be used again should be redefined to zero to recover data space. See Array Storage on page 296 for more information on the internal representation of arrays. Example Sample Program! ! ! ! In the following example, the DIM statement dynamically locates storage space for a string array. We declare COLOR$ as a twodimensional string array with three elements in each dimension.Chapter 7. Statements and Language-Defined Functions

65

DIM StatementINTEGER I%,J% STRING COLORS$(2) DATA "ORANGE", "RED", "VIOLET", "GREEN", "BLUE" DATA "BLACK", "YELLOW", "BROWN", "MAGENTA" DIM COLORS$(2,2) FOR I% = 0 TO 2 FOR J% = 0 TO 2 READ COLORS$(I%,J%) NEXT J% NEXT I% PRINT "PRIMARY COLORS ARE ";COLORS$(0,1);\ ", ";COLORS$(1,1);", AND ";COLORS$(2,0) END

Output Output for the sample program is:THE PRIMARY COLORS ARE RED, BLUE, AND YELLOW

DISABLE FunctionSyntaxi4 = DISABLE

Use


Explanation Use the DISABLE function to protect a portion of your program from software interrupts. DISABLE prevents asynchronous operations in your program from interrupting critical regions of your code. This function is provided to allow your mainline application program to change data shared with your asynchronous I/O error handling routine. i4 is a four-byte integer returned by the DISABLE function. The value is always zero. DISABLE and ENABLE must always be used in pairs. Disabling software interrupts without restoring them could cause a deadlock situation to occur, and your application is suspended indefinitely. See the ENABLE function and the ON ASYNC ERROR CALL statement for more information. Example See the ON ASYNC ERROR CALL Statement on page 107 for additional information.

ENABLE FunctionSyntaxi4 = ENABLE

Use


Explanation Use the ENABLE function to allow software interrupts from the operating system. This enables asynchronous operations in the system to interrupt your program. For example, if your program tries to write a line to the terminal printer and the printer cover is open, your Asynchronous I/O Error handling subprogram would be called by the runtime subroutine library (as long as software interrupts were enabled).

66


ENABLE Functioni4 is a four-byte integer returned by the ENABLE function. The value is always zero. ENABLE and DISABLE must always be used in pairs. See the DISABLE function and the ON ASYNC ERROR CALL statement for more information. Example See the ON ASYNC ERROR CALL Statement on page 107.

END StatementSyntaxEND

Use


Explanation The END statement terminates an IBM 4680 BASIC program. The END statement is a directive to the compiler indicating an end to the source program. The compiler reports an error if any statements follow the END statement. An END statement must be the last line of a program or must be the last statement on the last line of the program. The compiler adds an END statement to a program automatically if you omit it in the source code file. Example Sample Program! The following example uses END statement ! to mark the physical end of the program. PRINT "this program does nothing" END

Output Output for the sample program is:this program does nothing

END FUNCTION StatementSyntaxEND FUNCTION

Use


Explanation The END FUNCTION statement indicates the end of a user-defined multiline function. Use an END FUNCTION statement as the last statement in each multiline function definition. END FUNCTION sends program control from the multiline function to the statement in the main program, following the function call or reference. Example Sample Program

Chapter 7. Statements and Language-Defined Functions

67

END FUNCTION Statement! ! ! ! The following example uses the END FUNCTION statement to mark the end of a multiline FUNCTION. See the FUNCTION or DEF statement in this chapter.

INTEGER*2 I%,J% FUNCTION LARGEST%(VAL1%,VAL2%) INTEGER*2 VAL1%,VAL2%,LARGEST% IF VAL1% > VAL2% THEN \ LARGEST% = VAL1% \ ELSE \ LARGEST% = VAL2% END FUNCTION I% = LARGEST%(10,20) J% = LARGEST%(100,25) PRINT "the larger of 10 and 20 is ";I% PRINT "the larger of 100 and 25 is ";J% PRINT "the larger of 5 and 7 is ";LARGEST%(5,7) END

Output Output for the sample program is:the larger of 10 and 20 is 20 the larger of 100 and 25 is 100 the larger of 5 and 7 is 7

END SUB StatementSyntaxEND SUB

Use


Explanation The END SUB statement terminates a subprogram definition. See the SUB Statement on page 151. Example Sample Program! The following example uses the END SUB statement ! to mark the end of a SUBPROGRAM. ! See the SUB statement in this chapter. STRING AVESTRING$ SUB AVERAGE(INVAL1,INVAL2,OUTVAL$) REAL INVAL1,INVAL2,TEMP STRING OUTVAL$ TEMP = (INVAL1 + INVAL2) / 2 OUTVAL$ = "$" + STR$(TEMP) END SUB CALL AVERAGE(3.7,8.4,AVESTRING$) PRINT "the average in dollars is ";AVESTRING$ CALL AVERAGE(123.77,392.55,AVESTRING$) PRINT "the average in dollars is ";AVESTRING$ CALL AVERAGE(99.99,25.75,AVESTRING$) PRINT "the average in dollars is ";AVESTRING$ END

68


END SUB StatementOutput Output for the sample program is:the average in dollars is $6.05 the average in dollars is $258.16 the average in dollars is $62.87

ERR FunctionSyntaxa$ = ERR

Use


Explanation The ERR function returns a two-character string signifying the last runtime error to occur in a program. a$ is a string value returned by the ERR function. Use the ERR function with the ON ERROR statement and ERRL function. The two-character string contains the runtime error message listed in Appendix B, Runtime Error Messages. The ERR function returns a null string if referenced outside an ON ERROR routine. The ERR function resets when the RESUME statement executes. See the ERRL, ERRN, ERRF%, ON ERROR, and RESUME functions in this chapter for additional information on error handling. Example Sample Program! The following example uses the ERR function to ! check for a division by zero error INTEGER VAL1%,VAL2%,VAL3% STRING ERRORCODE$ ON ERROR GOTO ERRORTRAP VAL1% = 5 VAL2% = 0 VAL3% = VAL1% / VAL2% STOP ERRORTRAP: ERRORCODE$ = ERR PRINT "ERR = ";ERRORCODE$ IF ERRORCODE$ = "DZ" THEN \ PRINT "ERROR - divide by zero attempted" END

Output Output for the sample program is:ERR = DZ ERROR - divide by zero attempted

ERRF% FunctionSyntaxi% = ERRF%

Chapter 7. Statements and Language-Defined Functions

69

ERRF% FunctionUse store controller and terminal

Explanation The ERRF% function returns the I/O session number if it is associated with an I/O error. If the error is not an I/O error, ERRF% returns zero. The ERRF% function returns a zero if referenced outside an ON ERROR routine. i% is an integer returned by the ERRF% function. Example Sample Program! The following example uses the ERRF% function ! to write the I/O session number that caused ! a runtime error STRING A$,B$,C$ ON ERROR GOTO ERRORTRAP CREATE "TEST.TMP" RECL 10 AS 12 A$ = "FIELD ONE" B$ = "FIELD TWO" C$ = "FIELD THREE" WRITE #12,1;A$ WRITE #12,2;B$,C$ STOP ERRORTRAP: PRINT "ERRORCODE = ";ERR PRINT "associated I/O session number is ";ERRF% PRINT "see appendix B in 4680 BASIC Language Reference" END

Output Output for the sample program is:ERRORCODE = ER associated I/O session is 12 see appendix B in 4680 BASIC Language Reference

ERRL FunctionSyntaxi% = ERRL

Use


Explanation The ERRL function returns the actual physical line number in which the last runtime error occurred. i% is a 2-byte integer that the ERRL function returns. You must compile the source program using the N toggle, or ERRL returns a zero. The ERRL function returns a zero if referenced outside an ON ERROR routine. Using the N toggle generates seven to nine bytes of additional code per statement. See 279 for more information on the N toggle. Example Sample Program

70


ERRL Function! The following example uses the ERRL function ! to determine the line number of a divide by ! zero error ! NOTE: must be compiled with the N toggle INTEGER*2 I%,J%,LINENUM% ON ERROR GOTO ERRORTRAP I% = 0 J% = 100 / I% STOP ERRORTRAP: LINENUM% = ERRL PRINT "runtime error occurred on line ";LINENUM% END

Output Output for the sample program is:runtime error occurred on line 11

ERRN FunctionSyntaxi4 = ERRN

Use


Explanation The ERRN function returns a 4-byte error code. The error code helps isolate the exact cause of an error when multiple conditions exist that could generate a specific ERR error code. See Appendix B, Runtime Error Messages for the Basic Runtime errors. Refer to the 4680 Store Systems: Messages Guide or the 4690 Store System: Messages Guide for any return codes not found in Appendix B, Runtime Error Messages. The ERRN function returns a zero if referenced outside an ON ERROR routine. Example Sample Program! ! ! ! The following example uses all of the error functions to obtain a complete picture an I/O error. Notice the conversion routine used to obtain the hex digits from the ERRN function.

INTEGER*4 HX%,SX%,THE.SUM%,S% STRING ERRFX$,Z$ INTEGER*4 ERRNCODE% ON ERROR GOTO ERRORTRAP OPEN "NOFILE.TST" AS 10 STOP ERRORTRAP: !* ERROR ASSEMBLY ROUTINE *! HX% = ERRNChapter 7. Statements and Language-Defined Functions

71

ERRN FunctionERRFX$ = "" FOR S% = 28 TO 0 STEP -4 SX% = SHIFT(HX%,S%) THE.SUM% = SX% AND 000FH IF THE.SUM% > 9 THEN \ THE.SUM%=THE.SUM%+55 \ ELSE \ THE.SUM%=THE.SUM%+48 Z$=CHR$(THE.SUM%) ERRFX$ = ERRFX$ + Z$ NEXT S% PRINT PRINT "a runtime error has occurred" PRINT PRINT " ERR = ";ERR," ERRL = ";ERRL PRINT " ERRF = ";ERRF%," ERRN = ";ERRFX$ PRINT STOP END

Output Output for the sample program is:a runtime error has occurred ERR = OE ERRF = 10 ERRL = 0 ERRN = 80204010

EVENT% FunctionSyntaxi% = EVENT%

Use


Explanation The EVENT% function returns a 2-byte integer, indicating the I/O session number associated with the completion of the input operation that satisfied the most recently executed WAIT statement. EVENT% returns the value zero if the most recent WAIT timed-out. See WAIT Statement on page 161 for more information. i% is an integer that the EVENT% function returns. Example Sample Program! ! ! ! ! ! ! ! ! The following example uses an EVENT% function to determine if a preceding WAIT statement times out a full 2500 milliseconds specified by the variable interval. If the WAIT is satisfied by one of the sessions, IOSN% is assigned the session number value. The function RDRTN is called to read data from an associated pipe or input driver. If the WAIT times out, the function TMOUTRTN is called.

INTEGER*2 IOSN% INTEGER*4 INTERVAL% INTERVAL% = 2500 . . WAIT 1, 2, 3; INTERVAL%

72


EVENT% FunctionIOSN% = EVENT% IF IOSN% 0 THEN CALL RDRTN(IOSN%) \ ELSE CALL TMOUTRTN CLOSE IOSN% . END

EXIT FUNCTION StatementSyntaxEXIT FUNCTION

Use


Explanation The EXIT FUNCTION statement returns control from the multiline function to the statement in the main program following the function call or reference. Use an EXIT FUNCTION statement to leave a function before getting to the END FUNCTION statement. DO NOT use the RETURN statement to return from a function. You can have multiple EXIT FUNCTION statements in a function. Example Sample Program! ! ! ! ! ! The following example uses the EXIT FUNCTION statement to leave a FUNCTION before the END FUNCTION statement is reached if the two parameters passed to it are equal. In this case the FUNCTION is coded to return a 0 so that the largest of the two equal values will not be part of the sum.

INTEGER*2 I% FUNCTION FINDLARGE%(VAL1%,VAL2%) INTEGER*2 VAL1%,VAL2%,LARGEST%,FINDLARGE% IF VAL1% = VAL2% THEN \ BEGIN PRINT "values are equal - abort FUNCTION" FINDLARGE% = 0 EXIT FUNCTION ENDIF PRINT "values are not equal - continue FUNCTION" IF VAL1% > VAL2% THEN \ LARGEST% = VAL1% \ ELSE \ LARGEST% = VAL2% FINDLARGE% = LARGEST% END FUNCTION PRINT "we are going to find the sum of the" PRINT "larger numbers in 4 pairs of values" PRINT I% = 0 I% = I% + FINDLARGE%(10,20) I% = I% + FINDLARGE%(33,33) I% = I% + FINDLARGE%(100,25) PRINT PRINT "the sum of the larger numbers is";I% ENDChapter 7. Statements and Language-Defined Functions

73

EXIT FUNCTION StatementOutput Output for the sample program is:we are going to find the sum of the larger numbers in 4 pairs of values values are not equal - continue FUNCTION values are equal - abort FUNCTION values are not equal - conti

Documents

Basic