Вы находитесь на странице: 1из 484

4680 Basic

Language Reference
V ersion 1 Release 2

SC30-3356-09

4680 Basic

Language Reference
V 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.

Contents
Figures . . . . . . . . . . . . . . vii Notices . . . . . . . . . . . . . . . ix
Trademarks . . . . . . . . . . . . . . ix Scope of Data. . . . . . . . . . . . . . 31

Chapter 7. Statements and Language-Defined Functions . . . . . 33


Statements . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . xi
How 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 . . . . . . . . 1
Runtime Subroutine Libraries . . . An IBM 4680 BASIC Demonstration . . . . . . . . . . . 1 . 2

Chapter 2. Elements of IBM 4680 BASIC


The Character Set . . Identifiers . . . . Statements and Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5
. 5 . 6 . 7

Chapter 3. Data Types . . . . . . . . . 9


Constants . . . . . . . . . . . . . . . 9 Integer Data Type. . . . . . . . . . . . . 9 Real Data Type . . . . . . . . . . . . . 10 String Data Type . . . . . . . . . . . . 10 Data Type Declarations . . . . . . . . . . 11

Chapter 4. Variables and Arrays . . . . 13


Variables . Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 . 14

Chapter 5. Expressions
Arithmetic 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 . . . . . 23


Parameters 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 . . . . . . . . . 171


Pipes . . . . . . . . . . . . . . . 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 307


File System, Memory Space, and Compilation Errors . . . . . . . . . . . . . . Internal Failures . . . . . . . . . . . . . 307 . 328

Appendix B. Runtime Error Messages


Synchronous 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 . . . . . . . . . . . . . 275


Compiler 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 . 373
Statements . . . . . . . . . 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 . . . . 285


Memory 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 . . . . . . 383
Escape Sequence for Store Controller Display . . . 436 Extended Codes for Personal Computer Keyboard Input . . . . . . . . . . . . . . . . 437

Chapter 11. Data Representation in Memory . . . . . . . . . . . . . . 293


Integer 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 . . . 299
Calling an Assembly Routine from an IBM 4680 BASIC Module . . . . . . . . . . . . Passing Arguments . . . . . . . . . . . 299 . 299

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

Contents

vi

IBM 4680 BASIC: Language Reference

Figures
1. 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

IBM 4680 BASIC: Language Reference

Notices
References 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.

Trademarks
The 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.

Copyright IBM Corp. 1985, 2003

ix

IBM 4680 BASIC: Language Reference

Preface
This 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 Organized


The 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 Information


A 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 Software


IBM 4690 V4 Library
IBM 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 Library


OS 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 Application


IBM 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 Application


IBM 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 Application


IBM 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 Architecture


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

In-Store Processing
In-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 Hardware


IBM SurePOS 700 Series Terminals
IBM 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 4680 BASIC: Language Reference

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

IBM 4694 Point-of-Sale Terminals


IBM 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 Terminals


IBM 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 Terminals


IBM 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

Scanners
IBM 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-0333
Preface

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

Cabling
A 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

Networks
IBM 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 Publications
Advanced 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

IBM 4680 BASIC: Language Reference

Chapter 1. Introduction
IBM 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 Libraries


The 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.

Copyright IBM Corp. 1985, 2003

An IBM 4680 BASIC Demonstration


The 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.

IBM 4680 BASIC: Language Reference

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

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

IBM 4680 BASIC: Language Reference

Chapter 2. Elements of IBM 4680 BASIC


The primary elements of IBM 4680 BASIC are: v Characters v Identifiers v Statements v Lines.

The Character Set


IBM 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.

Copyright IBM Corp. 1985, 2003

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.

Identifiers
An 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.

IBM 4680 BASIC: Language Reference

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 Lines


Syntactic 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

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.

IBM 4680 BASIC: Language Reference

Chapter 3. Data Types


The 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.

Constants
A 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 Type


An 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

The following examples are hexadecimal and binary integer constants.


2ab0H 01011B 0FFFFH 10111110B 8BC2H

Real Data Type


A 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 Type


The 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

IBM 4680 BASIC: Language Reference

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 Declarations


You 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

IBM 4680 BASIC: Language Reference

Chapter 4. Variables and Arrays


To 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.

Variables
A 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

Arrays
An 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

IBM 4680 BASIC: Language Reference

Chapter 5. Expressions
An 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 Expressions
Arithmetic 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.

Copyright IBM Corp. 1985, 2003

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

IBM 4680 BASIC: Language Reference

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 Expressions


Mixed 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 1
A = 100 B = A * 3 B is 44

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

Example 2
B = 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 3
C = 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 4
A 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 Expressions
Character 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

IBM 4680 BASIC: Language Reference

Relational Expressions
A 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 for
Chapter 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 Expressions
Logical 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

IBM 4680 BASIC: Language Reference

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 <= 8/2 6*(3+4) < 25 AND 4 <= 8/2 (evaluates to true) (evaluates to false)

Two logical operators cannot appear consecutively within an expression, unless the second operator is a NOT. The following example is a valid expression:
3.14159 <= 10 AND NOT 10/5 = 3 (evaluates to true)

In the previous examples, all the operands are arithmetic relational expressions. You can also use character relational expressions, logical variables, logical array elements, and logical function references as operands in a logical expression. Logical operations in IBM 4680 BASIC may involve the examination of single bytes in 4 and 2-byte integers. In the following example, the GETLONG function returns a 4-byte integer representing the status for an I/O device identified by the I/O session number 21. In the example, we number the four bytes from the left starting with byte #1. The particular piece of information we want is stored in byte #3.
INTEGER*4 status, A, B

status = GETLONG(21) A = status AND 0FFFFH ! mask off bytes #1, #2 B = SHIFT(A,8) ! shift out byte #4 PRINT "Status in byte #3 is "; B END

The logical operator AND is used to mask off bytes #1 and #2. The SHIFT function shifts the resulting value to the right eight bits (1 byte), effectively removing the value in byte #4. The result in variable B is the status information contained in the original byte #3. The following example uses literal values and shows the results to help you understand the use of logical operations in IBM 4680 BASIC. The example uses 2-byte integers.
INTEGER C, D, E, F, G, H C = 257 ! Hex 0101 D = 532 ! Hex 0214 E = C AND 0FFH ! mask off high order byte F = D AND 0FFH ! mask off high order byte G = SHIFT(C,8) ! shift out low order byte H = SHIFT(D,8) ! shift out low order byte

Chapter 5. Expressions

21

PRINT "Original numbers are "; C; " and "; D; decimal PRINT "Low order bytes are "; E; " and "; F; decimal PRINT "High order bytes are "; G; " and "; H; decimal END

The following results are produced by running the previous program example.
Original numbers are 257 and 532 decimal Low order bytes are 1 and 20 decimal High order bytes are 1 and 2 decimal

Operator Precedence
Table 9 shows the precedence among all the operators. You can use parentheses to control the evaluation order of the operations specified in an expression. The use of parentheses supersedes operator precedence.
Table 9. IBM 4680 BASIC Operator Precedence Precedence 1 2 3 4 5 6 7 8 9 Operator () ^ *, / +, < >, NE NOT AND OR XOR Definition balanced parentheses exponentiation multiplication, division addition, subtraction not equal logical not logical and logical or logical exclusive or

22

IBM 4680 BASIC: Language Reference

Chapter 6. Subroutines, Subprograms, and User-Defined Functions


Subroutines, subprograms, and user-defined functions are portions of a program that perform specific tasks or computing operations. User-defined functions are classified into single-line and multiline functions. Subroutines, subprograms, and user-defined functions can execute as many times as required in a single program. Subprograms and user-defined functions are logically separate from the main body of the program. They can execute as part of another program that requires their services, or with minor modifications, they can execute independently. Subroutines which are started with the GOSUB statement often use the same variables used in the main program and cannot, therefore, execute independently. Subroutines, subprograms, and functions differ primarily in the way they are invoked and the results they produce. Both functions and subprograms can share values through the use of parameters. Functions pass parameters by value and subprograms pass parameters by reference. Subroutines cannot pass values through parameters.

Parameters to Subprograms and Functions


Two types of parameters must be distinguished: formal (dummy) parameters and actual (calling) parameters. Formal parameters are used within a procedure to reserve a place and declare a data type for the actual parameters to be supplied when the procedure is invoked. Actual parameters are the true values supplied in the procedure call or reference. The actual parameters are substituted for the formal parameters in the procedure when the procedure executes. The formal parameters used within a procedure must correspond in number, order, and data type with the actual parameters in a corresponding procedure call or reference. Each call in an IBM 4680 BASIC program can pass up to 15 parameters. IBM 4680 BASIC cannot pass an entire array as one parameter. (You can declare the array as GLOBAL, so you do not need to pass the array elements from one procedure to another). A formal parameter is either a string variable or numeric variable; it is never a constant or an expression. In IBM 4680 BASIC, formal parameters are local to a procedure. Subprograms pass parameters by reference. Functions pass parameters by value.

Subroutines
A subroutine is a sequence of statements that constitutes a specific task or computing operation. A subroutine cannot be passed variables and cannot be compiled separately from the main program body. The first statement in a subroutine must be labeled. The last statement must be a RETURN statement. Upon execution, a GOSUB statement in the main program body passes control to the first statement in the subroutine, the one identified by

Copyright IBM Corp. 1985, 2003

23

the label. Execution of the subroutine continues until the RETURN statement is encountered. The RETURN statement returns control to the main program following the first GOSUB statement. A subroutine should be located in a program where it executes only when control is transferred to it by a GOSUB statement. Otherwise, unpredictable results can occur. A good place to use subroutines in a program is after a STOP statement. Figure 1 shows the execution of a subroutine in a program. The statement label, srout:, indicates the beginning of the subroutine and serves as the transfer specification in the GOSUB statements. All the statements between srout: and the RETURN statement make up the subroutine.
. . . 1 . . . 2 . . . GOSUB srout: . . . 5 . . . 6 . . . 4 GOSUB srout: 9 . . . 2/6 . . . 8 STOP srout: . . . . . . 3/7 . . . . . . RETURN END 4/8

Main Program

Subroutine

Figure 1. Flow Diagram of a Subroutine

The following steps explain the execution flow of the program in Figure 1. Each step number matches a part in the execution of the program. 1. The statements before the first GOSUB statement execute in sequence. 2. The first GOSUB statement transfers execution control to srout:. 3. The statements in the srout: subroutine execute in sequence, up to the RETURN statement. 4. The RETURN statement transfers control to the first statement following the first GOSUB statement. 5. The statements preceding the second GOSUB statement execute in sequence. 6. The second GOSUB statement again transfers execution control to srout:. 7. The statements in the srout: subroutine execute in sequence a second time, up to the RETURN statement. 8. The RETURN statement transfers control to the first statement following the second GOSUB statement. 9. The statements following the second GOSUB statement execute in sequence, up to the STOP statement and the program ends. To write the same program without a subroutine, you have to list all the statements between srout: and the RETURN statement twice, thus making the program larger. In a situation where you want to use a procedure 10 or 100 times, you can understand the advantage in using subroutines.

24

IBM 4680 BASIC: Language Reference

Subprograms
A subprogram is a sequence of statements that make up a specific task or computing operation, separate from the main program body. A subprogram can use and modify variables that are passed to it as parameters and can be compiled separately from the main program body. If you use the PUBLIC reserved word, you can compile a subprogram separately from the main program. You must use the EXTERNAL reserved word to reference a separately compiled subprogram. For an explanation of the reserved word PUBLIC and EXTERNAL, see Separate Subprogram and Function Compilation on page 30.

Passing Parameters by Reference


Subprograms in IBM 4680 BASIC pass parameters by reference. When parameters pass by reference, the calling program passes the address of the true parameter value to the subprogram. The address is called a pointer because it points to the place in memory where the true value is located. The true parameter value remains at the same location in memory throughout program execution. Therefore, if the subprogram changes the value of the parameters, the value is changed for the entire program. If you call the subprogram a second time with the same parameter, the address of the parameter is the same but the value will have changed. A subprogram does not return a value to the calling program. However, parameters passed by reference are shared values between a subprogram and the calling program. When a subprogram changes parameter values, the calling program can use the changed values for additional processing when the subprogram finishes executing.

How to Use a Subprogram


You must define a subprogram before you can call it. The SUB statement must be the first statement in the definition. The SUB statement enables you to specify a symbolic name and formal parameters the subprogram needs for execution. Place all parameter data declaration statements and local data the subroutine requires immediately after the SUB statement. You must use a CALL statement to invoke a subprogram. In the CALL statement, you specify the subprogram name and the actual parameters that correspond to the formal parameters in the SUB statement. The CALL statement passes control to the subprogram. Execution continues through the subprogram until an EXIT SUB or END SUB statement is encountered. The EXIT SUB or END SUB statement returns control to the calling program at the first statement following a CALL statement. You can use more than one EXIT SUB statement in a subprogram. The last statement in a subprogram must be an END SUB statement. Figure 2 shows the execution of a subprogram and a calling program. A subprogram can be compiled separately from the main body of your program. Note: The SUB statement specifies the name sprog and two formal parameters for the subprogram. The name sprog is the transfer specification in the CALL statements.

Chapter 6. Subroutines, Subprograms, and User-Defined Functions

25

. . . 1 . . . . . . 2 2/6 CALL sprog (actual 1, actual 2) SUB sprog (formal 1,formal 2) . . . 6 3/7 5 . . . . . . . . . . . . 4 . . . CALL sprog (actual 1, actual 2) EXIT SUB 8 . . . . . . 7 . . . 9 . . . 8 END SUB END 4/8 Main Program Subprogram

Figure 2. Flow Diagram of a Subprogram

The following steps explain the execution flow of the program shown in Figure 2. Each step number matches a part in the execution of the program. 1. The statements before the first CALL statement execute in sequence. 2. The first CALL statement transfers execution control to sprog and substitutes the actual parameters in the CALL statement for the formal parameters in the SUB statement. 3. The statements in the sprog subprogram execute in sequence, up to the EXIT SUB statement. 4. The EXIT SUB statement transfers control to the first statement following the first CALL. 5. The statements preceding the second CALL statement execute in sequence. 6. The second CALL statement again transfers execution control to sprog. 7. The statements in sprog execute in sequence a second time. This time assume that the statements before the EXIT SUB statement contain instructions to skip over the EXIT SUB under certain conditions. Execution continues with the statements after the EXIT SUB, which execute in sequence up to the END SUB. 8. The END SUB statement transfers control to the first statement following the second CALL statement. 9. The statements following the second CALL statement execute in sequence up to the END statement and the program ends. A subprogram isolates a program task in a unit the program can invoke whenever the task is required. However, unlike a subroutine, a subprogram has the advantages of separate compilation and passing parameters by reference. You can call a subprogram any number of times.

User-Defined Functions
A user-defined function, like a subprogram, is a sequence of statements that make up a specific task or computing operation separate from the main program body. However, unlike a subprogram, a user-defined function can return a single value to the calling program. The function name is like a variable. If the function is to return a value, it should contain an assignment statement which assigns the value to the function name. The data type of the function name must match the data type of the return value.

26

IBM 4680 BASIC: Language Reference

You can invoke a function in either of two ways, with a CALL statement or by reference within an expression. User-defined functions are classified as single-line and multiline functions. You must define a function in a program before you can call or reference it. Use the FUNCTION statement to define both single-line and multiline functions. The FUNCTION statement enables you to specify a function name and any formal parameters the function needs for execution. (The DEF statement is interchangeable with the FUNCTION statement.) See FUNCTION Statement on page 78 for more information on the FUNCTION statement.

Passing Parameters by Value


Functions pass parameters by value. This means the calling program passes to the function a copy of the true parameter value, not the address. The copy of the parameter value occupies a different memory location from that of the original. Therefore, if the function changes the parameter value, the original variable is unchanged in the calling program. When a function changes a parameter passed by value, the calling program cannot use the changed value. There is no method for a calling program to access the parameter values in a function. Functions can return only one value to the calling program.

Single-Line User-Defined Functions


A single-line user-defined function performs computations that do not span more than one line in the program source file. Note: You cannot compile single-line user-defined functions separately. The form of the FUNCTION statement for single-line functions uses an equal sign followed by an expression. The expression contains the actual process that the single-line function is to perform. The data type of the expression and the data type of the function name must match. You cannot specify the data types of the function name or formal parameters in a single-line function. Use the following FUNCTION statement format to define a single-line function:
FUNCTION function.name (formal parameters) = expression

Formal parameters used within a single-line function definition must correspond in number, order, and data type to the actual parameters in the corresponding function call or reference. The following example shows a single-line user-defined function that calculates the area of a circle. The function has the symbolic name CALC.AREA and one formal parameter RADIUS.VAL.
FUNCTION CALC.AREA(RADIUS.VAL)= 3.14159*RADIUS.VAL ^2

The following example is a reference to the CALC.AREA function within an expression. The reference to CALC.AREA passes the actual parameter RVALUE by value:
PRINT CALC.AREA(RVALUE)

All functions evaluate to a single value that can be returned to the calling program. When a function finishes executing, the value of the function is assigned to the function name. The function name is a variable used to return the function value
Chapter 6. Subroutines, Subprograms, and User-Defined Functions

27

to the calling program. In the preceding examples, the name CALC.AREA is a variable used to return the function value.

Multiline User-Defined Functions


A multiline function, like a single-line function, returns only one value. Like a single-line function, multiline functions pass parameters by value. You can reference a function within an expression. A multiline function is a sequence of statements that performs a specific task or computing operation, separate from the main program body. Multiline functions can be compiled separately from the main program by using the EXTERNAL and PUBLIC reserved words. See Separate Subprogram and Function Compilation on page 30. The first statement in a multiline function must be a FUNCTION statement. This form of the FUNCTION statement enables you to specify a symbolic name and any formal parameters that the function needs for execution. Place data type declaration statements for all parameters, local data, and the function name immediately after the FUNCTION statement. You can invoke a multiline function with a CALL statement or by reference within an expression. In the CALL statement or reference, you specify the function name and actual parameters to be passed. The data type of a function name follows the same data type rules for all identifiers. Note: When you call a function with the CALL statement, the function does not return a value. The last statement in a multiline function must be the END FUNCTION statement. (The END FUNCTION statement and the FEND statement are interchangeable.) When executed, the CALL statement passes control to the function. Execution continues through the function until an EXIT FUNCTION or the END FUNCTION statement is encountered. The EXIT FUNCTION and END FUNCTION statements return control to the calling program at the first statement following the CALL statement or referencing expression. You can use more than one EXIT FUNCTION statement in a multiline user-defined function. Figure 3 shows the execution of a multiline function in a program. Note: In this example, the FUNCTION statement specifies the name multifunc and two formal parameters for the function. The name multifunc is the transfer specification in the CALL statement and referencing expression.

28

IBM 4680 BASIC: Language Reference

. . . 1 . . . . . . 2 2/6 CALL multifunc (actual 1, actual 2) 3 . . . . . . 6 . . . 7 retval = multifunc (actual 1, actual 2) FUNCTION multifunc (formal 1, formal 2) . . . 4 EXIT FUNCTION multifunc = formal 1 * formal 2 . . . 8 END FUNCTION 4/8

5 4 8 . . . 9 . . . END 4/8 Main Program Multiline Function

Figure 3. Flow Diagram of the Multiline Function

The following steps explain the flow of execution for the program shown in Figure 3. Each step number matches a part in the execution flow (arrows) shown in the figure. 1. The statements before the first CALL statement execute in sequence. 2. The CALL statement transfers execution control to multifunc and substitutes the actual parameters in the CALL statement for the formal parameters in the FUNCTION statement. 3. The statements in multifunc execute in sequence, up to the EXIT FUNCTION statement. 4. The EXIT FUNCTION statement transfers control back to the main program body at the first statement following the CALL statement. The function does not return a value when called with the CALL statement. 5. The statements preceding the referencing expression, execute in sequence. 6. The expression again transfers execution control to multifunc. 7. The statements in multifunc execute in sequence a second time. This time, assume that the statements before the EXIT FUNCTION statement contain instructions to skip over the EXIT FUNCTION statement under certain conditions. In this case, execution continues with the statements after the EXIT FUNCTION, which execute in sequence up to the END FUNCTION statement. 8. The END FUNCTION statement transfers control back to the main program body when the statement that made the reference to the function is reached. The function name multifunc serves as a variable to return the real value of the function. 9. The statements following the expression execute in sequence up to the END of the program. A function enables you to isolate a frequently needed program task in a unit that the program can invoke whenever that task is required. Remember, you can reference a function within an expression, and functions can return a single value to the main program. You can transfer control from the main program body to a function any number of times.

Chapter 6. Subroutines, Subprograms, and User-Defined Functions

29

Separate Subprogram and Function Compilation


You can compile multiline functions and subprograms separately to form individual program modules. The FUNCTION and SUB statements both have the EXTERNAL and PUBLIC reserved words that provide a method of accessing these procedures from separate modules in your program. To access a multiline function or subprogram from a separate module, you must declare the procedure definition public using the PUBLIC reserved word in the FUNCTION or SUB statement. Any other module that accesses the PUBLIC procedure must contain an abbreviated definition of the procedure declared as EXTERNAL. The abbreviated definition consists of the FUNCTION or SUB statement with formal parameters and EXTERNAL reserved word, data type declarations, and an END FUNCTION or END SUB statement. Use a CALL statement to reference the procedure. You can also reference a function in an expression. IBM 4680 BASIC does not check the parameter data types between modules. Corresponding parameter data types must match. The parameter names between modules do not have to match. The function and subprogram names used between modules in the definitions must match, otherwise a linker error will occur. The following example shows two program modules. Module 1 contains a call to the function in module 2.
! Module 1 - calls the function defined in Module 2 ! INTEGER*4 estimate REAL actual ! ! FUNCTION sales.quota.factor(num1, num2) EXTERNAL INTEGER*4 num1 REAL num2, sales.quota.factor END FUNCTION ! INPUT "Enter estimated sales in dollars "; estimate INPUT "Enter actual sales in dollars and cents "; actual ! CALL sales.quota.factor(estimate,actual) ! END ! Module 2 - contains public function definition ! FUNCTION sales.quota.factor(val1, val2) PUBLIC INTEGER*4 val1 REAL val2 REAL factor ! factor = val2 / val1 IF factor > 1.0 THEN \ PRINT "Sales exceeded estimate by ";factor \ ELSE IF factor < 1.0 THEN \ PRINT "Sales amounted to ";factor;" of estimate." \ ELSE PRINT "Sales matched the estimate." ! END FUNCTION END

In the previous example, module 1 requests two values from the store controller using INPUT statements. Then, module 1 calls the function named sales.quota.factor.

30

IBM 4680 BASIC: Language Reference

Module 2 contains the actual function definition with the PUBLIC reserved word. The function determines a sales quota factor based on the two dollar values entered in module 1 and prints out the results. The parameter names between modules do not need to match, but the order and data types must match. Any module in the program can call or reference the PUBLIC function defined in module 2. Modules that call or reference the PUBLIC function must contain the abbreviated function definition with the EXTERNAL reserved word and pass the appropriate parameters.

Recursive Subprograms or Functions


A recursive subprogram or function is one that can reference itself. You can declare subprograms and multiline functions as recursive by using the RECURSIVE reserved word in the FUNCTION or SUB statement. All local variables declared in a recursive subprogram or function are allocated on the stack. Therefore, the variables can represent different values for each call of the procedure. Values are pushed onto or taken off of the stack, one at a time, at one end of the stack. Recursive subprograms or functions are less efficient than nonrecursive ones because of the storage overhead associated with managing stack variables. The following example shows a recursive function named factorial and is formatted to calculate n!, the arithmetic factorial.
REM Recursive function to calculate n! FUNCTION factorial(n) RECURSIVE INTEGER n, factorial IF n<2 \ THEN factorial=1 \ ELSE factorial=n*factorial(n-1) EXIT FUNCTION END FUNCTION

The value n is supplied to the function as a parameter and checked to see if it is less than 2. If n is less than 2, the function returns the value 1, because 1! and 0! are both equal to 1. If n is greater than 2, execution moves to the factorial algorithm in the ELSE clause. The algorithm uses a recursive call to the factorial function passing the parameter n, reduced by 1 for each call. When n becomes less than 2, the value of the factorial variable returns through each recursive level of the function ending in the factorial calculation. The final calculated value returns to the original function call via the factorial function name.

Scope of Data
All variables, formal parameters, and labels declared within a program source file are local to that source file. This means that they are unknown or undefined outside of the source file, unless the global keyword is used. In the following example, the function named add.divide has three local variables. Variable A and B are formal parameters, and variable C is locally defined as an integer. The function name add.divide is also declared as an integer.
! INTEGER A,B,C,D .
Chapter 6. Subroutines, Subprograms, and User-Defined Functions

31

. FUNCTION add.divide(A,B) INTEGER add.divide, A,B,C C = A + B D = A / B END FUNCTION . . END

Note: Variables A, B, and C declared in the INTEGER statement before the function definition are different variables from the three local function variables. The variable D is not local to the add.divide function. However, the function does use and change the value of D in the program. The variable D is a module-local variable. This means that any functions or subprograms defined in this module, and the main program in this module (if any), have access to variable D. The INTEGER, REAL, and STRING statements provide the GLOBAL reserved word that enables you to declare global variables. Global variables are accessible from all modules in a program. Global variables do not need to be passed to subprograms or functions, internal or external. They only occur once in storage and all subprograms and functions may reference them. To reference global variables from separately compiled external functions and subprograms, the global variable declarations must precede the function or subprogram. Statement labels are local to the subprogram or function in which they are defined.

32

IBM 4680 BASIC: Language Reference

Chapter 7. Statements and Language-Defined Functions


This chapter explains each statement and language-defined function used by IBM 4680 BASIC. Each description includes an example of how to use the statement or function and the results produced by the example. For a description of the specific statements used by I/O device drivers, files, pipes, and communication drivers, see Chapter 8, Using Input and Output Devices and Pipes. For additional information on the operation of these input and output functions, and additional application services, refer to the IBM 4680 Store System: Programming Guide or the IBM 4690 Store System: Programming Guide.

Statements
In the 4680 BASIC language, a statement is a single instruction which gives specific directions to the computer using reserved words and user-defined identifiers. For example, with ASSIGNKEY, you can assign a string to a specific programmable function key. You must use the following format to make the function key assignment:
ASSIGNKEY function key number,function key string WHILE NOT CONSTAT% WAIT ; 200 ! suspend execution to service lower priority tasks WEND

Language-Defined Functions
Language-defined functions work in the same way as user-defined functions. They pass parameters by value and return a single value to the calling or referencing program. Language-defined functions are predefined. The STR$ function is an example of a language-defined function. STR$ returns the character representation of a number. You use the STR$ function according to the following format:
a$ = STR$(numeric expression)

STR$ is the symbolic name for the function. The numeric expression you specify is an actual parameter. You never see the formal parameters for STR$ or statements that comprise a language-defined function. Those parts of the function are contained in the runtime subroutine libraries.

Syntax Diagrams
This manual uses syntax diagrams (see the example in Figure 4) to highlight the various elements that make up each statement and function. Read the diagrams from left to right. Reserved words and syntactic items are specified along the arrow in the precise order in which they must be used in a program. The diagrams use the following conventions: v A branching of the diagram indicates options in the syntax. You can follow the diagram along any of the branches.
Copyright IBM Corp. 1985, 2003

33

v Dotted branches indicate places in the syntax where you can specify more than one option or syntactic item. You can follow a dotted branch any number of times when no maximum number is specified. v All reserved words are in uppercase letters. v Lowercase letters specify syntactic items, such as variables and expressions. v Default reserved words and values are in bold-faced type, and default paths are shown with bold double lines. Default reserved words and values, although shown in the diagrams, need not be coded. If the default path contains no reserved words or values, the default for that item is none. As shown in Figure 4, Reserved Word is a word that has a special purpose and may be used in no other way. Syntactic item stands for a variable, expression, or other general specification that must be used with a Reserved Word. The three-way branch indicates you have three choices to follow after specifying Reserved Word and syntactic item: v The default, indicated by the bold double line in the top branch, is to specify no option. v Alternatively, you can specify 1st OPTION Reserved Word or 2nd OPTION Reserved Word. The dotted line leading from the right branch back to the left branch indicates that, having specified one or the other of the options, you can specify either of them again. v 2 max. indicates that you can specify a maximum of two option reserved words.
======default value======= RESERVED WORDsyntactic item1st OPTION RESERVED WORD 2nd OPTION RESERVED WORD ..........2max............

Figure 4. Sample Syntax Diagram

Name Specification
The word name (when used in the syntax diagrams in this chapter) can be a literal string or a string variable to which a literal string has been assigned. name refers to device names such as MSR: (Magnetic Stripe Reader), ANDISPLAY: (Alphanumeric Display), file specifications (see syntax diagram below), and pipe specifications. See Terminal Input/Output Device Drivers on page 198 for a complete list of device drivers. Also refer to the IBM 4680 Store System: Programming Guide or the IBM 4690 Store System: Programming Guide for information on naming files and subdirectories in the terminal and the store controller, and using logical names. This information is essential to correctly use file names.
======== ======== ============ filename node:: drive: .extension

Figure 5. File Specification Syntax Diagram

34

IBM 4680 BASIC: Language Reference

======== ============ pipename node:: .extension

Figure 6. Pipe Specification Syntax Diagram

node:: denotes a remote node in your local area network. For example, to access a file on the store controller from a terminal on its loop, specify R:: for the node name. Use R:: in terminal applications only. See the IBM 4680 Store System: Programming Guide or the IBM 4690 Store System: Programming Guide for more information on nodes and logical names. drive: specifies the drive that contains the file you want to refer to. To specify the drive, type the drive letter followed by a colon. For example, A: represents drive A. If you omit the drive specifier, the operating system assumes the file is located on the default drive. filename denotes the file name or logical name. The file name consists of one to eight characters. A logical name can represent as much of the first part of a file name as you want. .extension denotes the file name extension. The file name extension consists of a period followed by one to three characters. pipename denotes the pipe name. The pipe name consists of pi: plus one to eight characters. The following characters are invalid in a file name, file name extension, or pipe name:
. | " < / > \ + [ = ] : ; , ? $ * _ & !

The following characters can be used in a file name, but not in the first, fourth, fifth, or eighth position of a file name:
@ # ( ) { }

The @ should be used in the fifth position only for an I/O Processor table file name. You should not use ADX as the first three characters for any pipe, file name, logical name, or any other name. Any other characters are valid.

Restricted Use of Functions and Statements


IBM 4680 BASIC is designed to program both the store controller and the terminal. Some of the statements and functions can only be used to program the terminal and others can only be used to program the store controller. The compiler directive, %ENVIRON, specifies the machine in which the application program will execute. Depending on the setting of the directive, some statements and functions are invalid for that environment. See Compiler Directives on page 277 for more information on compiler directives.

Chapter 7. Statements and Language-Defined Functions

35

The IBM 4680 BASIC statements and language-defined functions are listed on the following pages. The statements and functions you can use to program the store controller and/or terminal are specified.

Statements and Functions


The following statements and functions apply to both the store controller and the point of sale terminal:
v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v ABS Function ACCESS Statement ASC Function CALL Statement CHAIN Statement CHR$ Function CLEARS Statement CLOSE Statement COMMON Statement CREATE 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 GETLONG Function GOSUB Statement GOTO Statement IF Statement IF END # Statement INT Function INT% Function INTEGER Statement LEFT$ Function LEN Function LET Statement LOCATE # Statement MATCH Function MFRE Function v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v v MID$ Function MOD Function NEXT Statement ON Statement ON ASYNC ERROR CALL Statement ON ERROR Statement OPEN Statement OPTION Statement PACK$ Function POINT Statement PTRRTN Function PUTLONG Statement READ Statement READ # Statement READ # LINE Statement READ FORM # Statement REAL Statement REMARK Statement RENAME Function RESTORE Statement RESUME Statement RETURN Statement RIGHT$ Function ROUND Function SADD Function SGN Function SHIFT Function SIZE Function STOP Statement STR$ Function STRING Statement STRING$ Function SUB Statement TCLOSE Statement TIME$ Function TRANSLATE$ Function UCASE$ Function UNPACK$ Function USE Statement VAL Function VARPTR Function WAIT Statement WEND Statement WHILE Statement WRITE # Statement WRITE MATRIX Statement

36

IBM 4680 BASIC: Language Reference

The following statements and functions apply to the store controller only:
v v v v v v v v v v v v v v v v ASSIGNKEY Statement CHDIR Statement COMMAND$ Function CONCHAR% Function CONSOLE Statement CONSTAT% Function CREATE POSFILE Statement CREATE POSFILE KEYED Statement CREATE POSFILE RANDOM Statement FUNCTIONKEY Statement GET Function INKEY Function INPUT Statement INPUT LINE Statement LOCK Function LPRINTER Statement v v v v v v v v v v v v v v v v MKDIR Statement OPEN LINK Statement OPEN SESSION Statement PEEK Function POKE Statement POS Function PRINT Statement PRINT USING Statement PRINT # Statement PUT Statement RANDOMIZE Statement READ MATRIX Statement RMDIR Statement RND Function TAB Function UNLOCK Function

The following statements apply to the terminal only:


v LOAD Statement v LOCKDEV Statement v OPEN SERIAL Statement v UNLOCKDEV Statement v WRITE LOGO # Statement

Descriptions of each statement and function are alphabetically arranged in the remainder of this chapter. Syntax, use, explanation, and examples with sample programs and output are provided.

ABS Function
Syntax
x = ABS(numeric expression)

Use

store controller and terminal

Explanation The ABS function returns a real number that is the absolute value of numeric expression. Integer expressions automatically convert to real numbers. v x is a real number returned by the ABS function. v Numeric expression is any real number or integer expression. Example Sample Program
! The following example calculates the absolute value ! of three numeric expressions using the ABS function INTEGER*2 VAL1 REAL VAL2,X,Y,Z VAL1 = -10 VAL2 = 10.55 X = ABS(VAL1) Y = ABS(VAL1 * VAL2) Z = ABS(0) PRINT X,Y,Z END

Chapter 7. Statements and Language-Defined Functions

37

ABS Function
Output Output for the above sample program is:
10 105.5 0

ACCESS Statement
Syntax
======== ========= ======= ACCESS , NOREAD NOWRITE NODEL ======== ========= ======= , NOREAD NOWRITE NODEL ======== ========= ======= NOREAD NOWRITE NODEL

Use

store controller and terminal

Explanation The ACCESS statement defines access rights for all new disk files and pipes that the program creates until the next ACCESS statement is executed. v NOREAD means read access by this user is not allowed. v NOWRITE means write access by this user is not allowed. v NODEL means the file cannot be deleted by this user. The reserved words preceding the first comma define the world access rights. The reserved words between the first and second comma define the group access rights. The reserved words following the second comma define the owner access rights. Process access rights are requested in the OPEN statement. The protection specifications are positional. If group reserved words are present, you must code the first comma even if no world reserved words are present. If you code only owner reserved words, you must precede them with two commas. If you specify only world reserved words, no commas are necessary. By default, no access restrictions apply to any files or pipes the program creates. This is the case if no ACCESS statement is executed, or if no reserved words or commas appear in the statement. For information on protecting files, see the IBM 4680 Store System: Programming Guide or the IBM 4690 Store System: Programming Guide. Example Sample Program
! ! ! ! ! ! ! ! ! ! ! In the following example, the ACCESS statement is used to define the access rights for FILE.1 and FILE.2. Both "world" and "group" processes are restricted from writing to or deleting the files. Processes with "owner" status can read and write to the files, but cannot delete them. The second ACCESS statement defines access rights for FILE.3 and FILE.4. World processes cannot read, write, or delete the files. Processes with "group" or "owner" status can read, write,

38

IBM 4680 BASIC: Language Reference

ACCESS Statement
! and delete the files. ! Create files with different access rights. ACCESS CREATE CREATE . . ACCESS CREATE . CREATE . . END NOWRITE NODEL, NOWRITE NODEL, NODEL "FILE.1" AS 39 LOCKED "FILE.2" AS 40 LOCKED NOREAD NOWRITE NODEL, "FILE.3" AS 41 BUFFSIZE 256 UNLOCKED "FILE.4" AS 42 LOCKED

ASC Function
Syntax
i% = ASC(string expression)

Use

store controller and terminal

Explanation The ASC function returns an integer between 0 and 255 that represents the position in the ASCII collating sequence of the first character in the string expression. The string expression must contain at least one character. A runtime error occurs if the string expression evaluates to a null string. Note: The inverse function of ASC is CHR$. v i% is an integer returned by the ASC function. v String expression is any combination of string operands concatenated with the character operator. Example Sample Program
! The following example prints the ASCII equivalent of the ! first character in three string expressions using the ASC ! function INTEGER*2 VAL1,VAL2,VAL3 STRING A,B A = "FIRST" B = "SECOND" VAL1 = ASC(A) VAL2 = ASC(B) VAL3 = ASC("HELLO" + "GOODBYE") PRINT "F is the ASCII equivalent of ";VAL1 PRINT "S is the ASCII equivalent of ";VAL2 PRINT "H is the ASCII equivalent of ";VAL3 END

Output Output for the above sample program is:


F is the ASCII equivalent of S is the ASCII equivalent of H is the ASCII equivalent of 70 83 72

Chapter 7. Statements and Language-Defined Functions

39

ASSIGNKEY Statement

ASSIGNKEY Statement
Syntax
ASSIGNKEYfunction keynumber,function key str

Use

store controller only

Explanation The ASSIGNKEY statement assigns the function key string as the new value of the programmable function key identified by the function key number. v Function key number is numeric and must be in the range 1 to 10. v Function key string is a string of fewer than 14 characters. See the FUNCTIONKEY statement in this chapter for more information on programmable function keys. Example Sample Program
! ! ! ! The following example uses the ASSIGNKEY statement to assign a STRING value to several function keys. See the FUNCTIONKEY statement in this chapter for more information.

ASSIGNKEY 1,"HELP" ASSIGNKEY 3,"QUIT" ASSIGNKEY 5,"THIS" ASSIGNKEY 7,"THAT" ASSIGNKEY 10,"TEST" FUNCTIONKEY ON PRINT "press any key to quit" WHILE NOT CONSTAT% WAIT ; 200 ! suspend execution to service lower priority tasks WEND FUNCTIONKEY OFF END

Output The first six (6) characters of the function key definitions should appear at the bottom of the screen when this example is executed.

CALL Statement
Syntax
function name ==================== CALL ( parameter ) subprogram name .... , .... maximum 15

Use

store controller and terminal

Explanation The CALL statement transfers program control to a multiline function or subprogram. The CALL statement passes parameters to and starts execution of the specified function or subprogram. The address of the statement following the CALL statement is placed on a stack. The EXIT FUNCTION or END FUNCTION statement in a function, or the EXIT SUB or END SUB statement in a subprogram sends control back to the statement following the CALL statement.

40

IBM 4680 BASIC: Language Reference

CALL Statement
v Function name is an identifier. v Subprogram name is an identifier. v Parameter is a variable or expression that is passed to a subprogram or function, and substituted for the formal parameter in the function or subprogram. You must separate each parameter with a comma. The number of parameters specified must match the number of formal parameters in the function or subprogram. Parameter data types in the CALL statement and function or subprogram definition must also match. If the parameter data types do not match, unpredictable results will occur, including the possibility of a protection exception. You can specify a maximum of 15 parameters. There is no difference between a subprogram and a user-defined multiline function if they pass no parameters. See Passing Parameters by Reference on page 25 for more information on parameter passing. The CALL statement cannot reference a single-line function or a program label. Subprograms and multiline functions can be written in RASM86 (assembler). Care must be taken with assembly programs to ensure they perform parameter passing properly. Example Sample Program
! The following example uses the CALL statement to ! execute a subprogram several times. ! 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

Output Output for the above sample program is:


the average in dollars is $6.05 the average in dollars is $258.16 the average in dollars is $62.87

CHAIN Statement
Syntax
======== ============= CHAIN NAME ,parameter ...........

Use

store controller and terminal


Chapter 7. Statements and Language-Defined Functions

41

CHAIN Statement
Explanation The CHAIN statement loads another program into memory and starts execution. The CHAIN statement can load two types of programs: overlay programs generated by the linker, and directly executable files (files with the extension .286). If a filetype is not specified in the name, then the file is assumed to be an overlay. A filetype must be included to chain to a new program. However, before you chain to an overlay file, the linker must create that overlay and the root program at the same time. You must link your program with the NOSHARED LINK86 option in order to make use of overlays. For more information on overlays, see the IBM 4680 Store System: Programming Guide or the IBM 4690 Store System: Programming Guide. CHAIN can also transfer control to .286 files that were generated by RASM86 source language, but you cannot pass parameters to this program. In terminal applications, this statement is used only to chain to another program. Chaining to overlays is not supported. v Name is any valid file name. See Name Specification on page 34 for a complete description. The extension must be .286 or .OVR (for an overlay). v Parameter is a variable or expression that is passed to a procedure or function and substituted for the dummy argument in the function. The maximum number of bytes for a parameter varies. It is less than the available contiguous free space on the heap. In the store controller, CHAIN is used to execute overlays and to begin a new program. When chaining to a new application, pipes that the program created are deleted when the last application to access the pipe closes it. Pipes and files that were opened by the application using the OPEN or CREATE statements are closed. Also there is no return to the root segment on the store controller. Note: Pipes and files not opened by BASIC (such as Display Manager) are not closed by a CHAIN. These files cause a loss of system resources by reducing the number of files the system can open at any one time if the files are not closed by the Display Manager CLSDIS statement prior to using the CHAIN statement. Parameters can be passed to new programs by listing them after the name. The new program can then acquire them with the USE statement. It is the users responsibility to be sure that the parameters used with the CHAIN statement match the variables in the USE statement. Failure to do so may cause a protection exception to occur, and in all cases will cause unpredictable results. See the USE Statement on page 159. Use COMMON to pass data to overlays. Example Sample Program
! ! ! ! ! ! ! ! In the following example, the CHAIN statement instructs the system to save the application already processing in memory and passes three arguments to U.286. In U.286, the USE statement specifies three variables. These variables receive the three parameters passed by the CHAIN statement. The output results from executing C.286.

! This is program C.286 ! C.286 chains to U.286

42

IBM 4680 BASIC: Language Reference

CHAIN Statement
INTEGER*2 D% REAL E STRING F$ D% = 123 E = 4.567 F$ = "F" PRINT "INVOKING CHAIN STATEMENT IN C.286" CHAIN "U.286", D%,E,F$ END ! This is program U.286 ! U.286 is chained to from C.286 INTEGER*2 A% REAL B STRING C$ PRINT "INVOKING USE IN U.286" USE A%,B,C$ PRINT A% PRINT B PRINT C$ END

Output Output for the above sample program is:


INVOKING CHAIN STATEMENT IN C.286 INVOKING USE IN U.286 123 4.567 F

CHDIR Statement
Syntax
CHDIRpathname

Use

store controller only

Explanation The CHDIR statement temporarily changes the current directory to the directory or subdirectory specified by pathname. CHDIR allows you to change the current directory either on the default drive or on another specified drive. This change remains in effect for the drive only until another CHDIR executes for that drive or until the application terminates. On termination, the current directory settings for all drives are restored to those that were in effect before the application started to execute. Pathname is a string that specifies a valid path consisting of the root directory and subdirectories. It may also contain a drive specification. Note: The directory specified by pathname must already exist before executing the CHDIR command. If you do not specify a drive, the current drive is assumed. Example Sample Program
! In the following example the CHDIR command is executed for ! both the default drive and for drive B. This program writes ! to a diskette in drive B. STRING DIRNAME$, FNAME$
Chapter 7. Statements and Language-Defined Functions

43

CHDIR Statement

DIRNAME$ = "NEWDIR" PRINT "Create a new subdirectory named NEWDIR," MKDIR DIRNAME$ PRINT "make it the current directory," CHDIR DIRNAME$ PRINT "and create a file there named NEWFILE." FNAME$ = "NEWFILE" CREATE FNAME$ AS 5 PRINT DIRNAME$ = "B:\NEWDIR" PRINT "Create a new subdirectory NEWDIR on drive B," MKDIR DIRNAME$ PRINT "make it the current directory on drive B," CHDIR DIRNAME$ PRINT "and create a file there named NEWFILE." FNAME$ = "B:NEWFILE" ! Omitting a slash before the ! file name causes the file to be ! created on drive Bs current ! directory, which is now NEWDIR, ! rather than on the root. CREATE FNAME$ AS 6 PRINT "When program terminates, there should be a file PRINT "NEWFILE in directory NEWDIR on the default drive," PRINT "as well as a file NEWFILE in directory \NEWDIR on" PRINT "the diskette in drive B." END

Output Output for the sample program is:


Create a new subdirectory named NEWDIR, make it the current directory, and create a file there named NEWFILE. Create a new subdirectory NEWDIR on drive B, make it the current directory on drive B, and create a file there named NEWFILE. When program terminates, there should be a file NEWFILE in directory NEWDIR on the default drive, as well as a file NEWFILE in directory \NEWDIR on the diskette in drive B.

CHR$ Function
Syntax
a$ = CHR$(numeric expression)

Use

store controller and terminal

Explanation The CHR$ function returns a one-character string. The string is a single ASCII character having the ASCII decimal value specified by numeric expression. If the expression is real, CHR$ converts it to an integer. v a$ is a string value returned by the CHR$ function. v Numeric expression is any real number or integer expression from 0 to 255. Note: The ASC function is the inverse function of CHR$. Example Sample Program

44

IBM 4680 BASIC: Language Reference

CHR$ Function
! The following example uses the CHR$ function to ! write the equivalent character from a given ! ASCII value STRING VAL1$,VAL2$,VAL3$ VAL1$ VAL2$ VAL3$ PRINT PRINT PRINT END = CHR$(80) = CHR$(79) = CHR$(83) VAL1$;" is the ASCII equivalent of 80" VAL2$;" is the ASCII equivalent of 79" VAL3$;" is the ASCII equivalent of 83"

Output Output for the sample program is:


P is the ASCII equivalent of 80 O is the ASCII equivalent of 79 S is the ASCII equivalent of 83

CLEARS Statement
Syntax
CLEARS I/O session number

Use

store controller and terminal

Explanation The CLEARS statement clears the screen of the device referenced by an Input/Output (I/O) session number. In the store controller, not specifying an I/O session number defaults to the default console. I/O session number is the number assigned to the I/O device in the OPEN Statement. Example Sample Program
! The following example uses the CLEARS statement ! to clear the screen during execution. INTEGER*2 DELAYTIME% DELAYTIME% = 5000 CLEARS PRINT "the screen has just been cleared" PRINT "in about 5 seconds it will be cleared again" WAIT;DELAYTIME% CLEARS PRINT "the screen has just been cleared again" END

Output Output for the sample program is:


(screen is the screen in about 5 (screen is the screen cleared) has just been cleared seconds it will be cleared again cleared) has just been cleared again

Chapter 7. Statements and Language-Defined Functions

45

CLEARS Statement
Note: Text that appears in () is for information and does not appear in the actual output.

CLOSE Statement
Syntax
=========== CLOSE I/O session number QUIESCE ....... , ........

Use

store controller and terminal

Explanation The CLOSE statement closes disk files, pipes, I/O devices or communication links, releases the I/O session number, and frees all buffer space that was allocated by the runtime subroutine libraries. A file must first be activated with a CREATE or OPEN statement before using a CLOSE statement. An IF END statement assigned to a closed file has no further effect. A STOP statement automatically closes all active I/O sessions. v QUIESCE is a reserved word used with communication links and keyed files. When your application closes a link using the QUIESCE keyword, the BASIC runtimes close all active communications sessions which your application has open. When a keyed file is closed with QUIESCE, the file is zeroed. v I/O session number is a unique identification number you assign to a file, a pipe, or a device with the CREATE or OPEN statement. Note: CLOSE causes distribution of a file if you specify the ATCLOSE distribution mode. See CREATE POSFILE Statement on page 54 for more information on file distribution modes. Example Sample Program
! ! ! ! The following example uses the CLOSE statement to close a file after writing two records to it. See the CREATE statement in this chapter for more information.

INTEGER*2 C% REAL D STRING A$,B$ CREATE "TESTFILE.TMP" RECL 25 AS 10 PRINT "creating new file called TESTFILE.TMP" PRINT A$ = "field one" B$ = "field two" C% = 321 D = 4.5 WRITE #10,1;A$,B$ WRITE #10,2;C%,D CLOSE 10 PRINT "TYPE the new file to see the contents" PRINT "thats all folks" END

Output

46

IBM 4680 BASIC: Language Reference

CLOSE Statement
Output for the sample program is written to the screen and to a file.
SCREEN OUTPUT ------------creating new file called TESTFILE.TMP TYPE the new file to see the contents thats all folks FILE OUTPUT ----------(contents of TESTFILE.TMP)

"field one","field two" 321,4.5,

COMMAND$ Function
Syntax
a$ = COMMAND$

Use

store controller only

Explanation The COMMAND$ function returns a string containing the command tail used to execute the program. a$ is a string value returned by the COMMAND$ function. A command line is the line that you enter at the keyboard to tell the operating system to run a program. A command line consists of a file name and an optional command tail. The file name identifies the program to execute. The command tail can provide extra information for the program, such as an option, or parameter. The COMMAND$ function does not return the file name. COMMAND$ eliminates all blanks preceding the first character in the command tail and converts all characters to uppercase. A command tail is any data following an IBM 4680 BASIC file name on the command line. You can use the COMMAND$ function anywhere, any number of times in a program. If you use COMMAND$ in an IBM 4680 BASIC program loaded with a CHAIN statement and the program is not an overlay, COMMAND$ is null unless the program that issued the CHAIN passed parameters, in which case COMMAND$ contains the name of the pipe used by runtime subroutine library to pass these parameters. Example Sample Program
! ! ! ! ! ! ! ! ! ! ! The following example uses the COMMAND$ function to allow the user to specify an optional parameter when executing the program. If no parameter is typed following the name of the program the COMMAND$ function will return a null string. To see how this works try typing a space followed by /1,/2,/3, or /4 after the program name when you execute it. Notice that the option format can be any string that the program has been coded to recognize and is not restricted to /number.

Chapter 7. Statements and Language-Defined Functions

47

COMMAND$ Function

STRING COMMTAIL$ COMMTAIL$ = COMMAND$ IF COMMTAIL$ = "/1" THEN \ PRINT "program will execute with option #1" \ ELSE IF COMMTAIL$ = "/2" THEN \ PRINT "program will execute with option #2" \ ELSE IF COMMTAIL$ = "/3" THEN \ PRINT "program will execute with option #3" \ ELSE IF COMMTAIL$ = "/4" THEN \ PRINT "program will execute with option #4" \ ELSE IF COMMTAIL$ = "" THEN \ PRINT "no option specified" \ ELSE \ PRINT "*** ERROR - unknown option specified" END

Output Output for the sample program will vary depending on what is typed to execute it.
For example, say your program is named COMMAND: if you run the program by typing: COMMAND /2 the output will be: the program will execute with option #2 if you run the program by typing: COMMAND ZZZ the output will be: *** ERROR - unknown option specified

COMMON Statement
Syntax
COMMONvariable .... , ....

Use

store controller and terminal

Explanation The COMMON statement specifies variables to retain in memory for use by an overlay. You can also use the COMMON statement to share variables across multiple modules in a program. This has the same effect as using the GLOBAL reserved word for variable declarations, but using COMMON causes additional runtime processing to occur and your program will execute more slowly. Variable is an integer, string, or real number. The compiler treats all COMMON statements in a program as one consecutive list of variables. Therefore, a program can contain any number of COMMON statements. Only blank lines, REM statements, and data type declaration statements can precede COMMON statements. All COMMON

48

IBM 4680 BASIC: Language Reference

COMMON Statement
statements taken as a group, must have the same number of variables in each chained program. Each COMMON statement in a chained program can contain a different number of variables, if the total number of common variables matches all the chained programs common variables. The position and data type of each variable must match in each chained program. Dimensioned variables must have the same number of subscripts. For array variables, place the number of subscripts in parentheses after the array name. The COMMON statement does not indicate the size of the subscript. Be sure to allocate array space with a DIM statement before referencing an array variable in COMMON. The first program requiring access to the array must contain the DIM statement. Subsequent programs should access the array without issuing a DIM statement. If a DIM statement executes a second time for the same array, the original data is lost. Example Sample Program
! ! ! ! ! In the following example, the COMMON statement declares that three variables are common to the program running in memory and the chained overlay program. The chained overlay program must have the same variables declared as common.

INTEGER*2 A% REAL ARRAY1(2) STRING B$ COMMON A%,ARRAY1(2),B$ DIM ARRAY1(10,10) . . CHAIN "APP11.OVR" . . END

CONCHAR% Function
Syntax
i2% = CONCHAR%

Use

store controller only

Explanation The CONCHAR% function reads one character from the console keyboard and returns the decimal ASCII representation of that character. CONCHAR% waits for a character to be entered at the console keyboard, then displays the character on the screen before returning the ASCII decimal value. However, if the ASCII decimal value is less than 32, CONCHAR% does not display the character. i2% is an integer returned by the CONCHAR% function. The low-order eight bits of the returned value comprise the binary ASCII representation. The high-order eight bits are always zeros. The value returned is a decimal integer. Note: The INKEY function performs the same task that CONCHAR% performs, except that INKEY does not display the character on the screen.
Chapter 7. Statements and Language-Defined Functions

49

CONCHAR% Function
Example Sample Program
! The following example writes the ASCII value ! of a pressed key using the CONCHAR% function INTEGER*2 KEYVALUE PRINT "press the spacebar" KEYVALUE = CONCHAR% PRINT PRINT "the ASCII decimal equivalent is ";KEYVALUE END

Output Output for the sample program is:


press the spacebar the ASCII decimal equivalent is 32

CONSOLE Statement
Syntax
CONSOLE

Use

store controller only

Explanation The CONSOLE statement directs program output to the screen and output will continue to be sent to the screen until a LPRINTER statement is executed. When a program begins execution, output appears on the screen. Neither the LPRINTER nor the CONSOLE statement affect the INPUT or INPUT LINE statement prompts that always appear on the screen. If the current output column is not 1, both the LPRINTER and the CONSOLE statement send a carriage return/line feed before redirecting the output. See the LPRINTER Statement on page 99. Example Sample Program
! The following example uses the CONSOLE statement ! to direct output to the screen. ! NOTE: see also the LPRINTER statement in this ! chapter PRINT "*** WARNING ***" PRINT PRINT "make sure your printer is ready" PRINT "press any key to proceed" PRINT WHILE NOT CONSTAT% WAIT ; 200 ! suspend execution to service lower priority tasks WEND PRINT "this appears on the screen" LPRINTER PRINT "this appears on the printer" CONSOLE PRINT "now we are back to the screen" PRINT PRINT "thats all folks" END

50

IBM 4680 BASIC: Language Reference

CONSOLE Statement
Output Output for the sample program appears on the printer and on the display. The following examples shows the output.
SCREEN OUTPUT ------------*** WARNING *** make sure your printer is ready press any key to proceed this appears on the screen now we are back to the screen thats all folks PRINTER OUTPUT -------------this appears on the printer

CONSTAT% Function
Syntax
i2% = CONSTAT%

Use

store controller only

Explanation The CONSTAT% function returns a logical value signifying status. Use CONSTAT% to determine if the keyboard has a ready status. Ready status means a character has been entered at the keyboard but has not been read by the program. CONSTAT% returns a -1 (logical true) if the keyboard is ready. Otherwise, CONSTAT% returns a zero (logical false). i2% is an integer returned by the CONSTAT% function. Example Sample Program
! ! ! ! ! ! ! ! ! ! The following example uses the CONSTAT% function to determine if a key has been pressed. By using the function to control a WHILE loop, the program will wait for the user to press a key. Note: If you call CONSTAT% in a WHILE loop, you should include a WAIT statement in the loop to temporarily suspend execution of your application. This prevents it from monopolizing the processor and blocking other applications.

PRINT "press any key to continue..." WHILE NOT CONSTAT% WAIT ; 200 ! suspend execution to service lower priority tasks WEND PRINT "a key was pressed - program continues" PRINT "thats all folks" END

Output Output for the sample program is:

Chapter 7. Statements and Language-Defined Functions

51

CONSTAT% Function
press any key to continue... a key was pressed - program continues thats all folks

CREATE Statement
Syntax
================================ CREATEname ========= RECL record length DIRECT ========BUFF 1========== ASI/O session number BUFF number of buffers =====BUFFSIZE 128====== ===UNLOCKED=== locked BUFFSIZE buffersize READONLY ========== =========== ========= NOREAD NOWRITE NODEL ============ PRIORITY

Use

store controller and terminal

Explanation CREATE creates a new disk file or pipe. If you create a file with a name that already exists, CREATE erases the existing file before creating the new one. If you create a pipe with a pipe name that already exists, the create operation fails. For additional information on pipes and pipe routing services, see the IBM 4680 Store System: Programming Guide or the IBM 4690 Store System: Programming Guide. Disk file attributes pertaining to security are defined at CREATE time. The most recently executed ACCESS statement determines the file protection information. See the ACCESS statement in this chapter. v Name is any valid file or pipe name. See Name Specification on page 34 for a complete description. v The DIRECT flag indicates the file is of the DIRECT type of random-access file. DIRECT has meaning only for disk files. v RECL record length is numeric. Specifying RECL without DIRECT creates a standard random-access file. If you specify neither RECL nor DIRECT, a sequential file is created. v I/O session number is the number you assign to the file or pipe. An I/O session number can be any numeric expression that evaluates to a 2-byte integer ranging from 1 to 99. v BUFF is numeric, and BUFF times BUFFSIZE specifies the runtime buffer for a file or the size of a pipe. See Pipes on page 171 for more information on this reserved word as it applies to creating pipes. v BUFFSIZE is numeric and specifies the file buffer size in bytes.

52

IBM 4680 BASIC: Language Reference

CREATE Statement
If you do not specify buffer size, BUFF times 128 is the size in bytes of the buffer allocated by the runtime library for the current I/O session. If you are creating a pipe, the buffer size (or the BUFF parameter times 128) is interpreted as the size of the pipe. LOCKED does not allow access to the file by other processes. LOCKED assures exclusive use of the file by the creating process until the creating process closes the file. At that time, users with open privileges can open the file. UNLOCKED allows other processes to read and write to the file. UNLOCKED allows read and write access only to those users with read and write privileges to the file. UNLOCKED is the default. READONLY allows other processes to read from, but not write to, the file. READONLY prohibits writing to the file even from processes that have write privileges. READONLY does not grant temporary read privileges to processes that usually do not have them. NOREAD specifies that read privileges are not being requested. NOWRITE specifies that write privileges are not being requested. NODEL specifies that delete privileges are not being requested. (This does not prevent your program from deleting the file if it has delete access rights. It does allow your program to open a file if you do not have delete access rights.) The PRIORITY flag has meaning only for disk files. It is valid only in the terminal. If present, PRIORITY indicates that reading from and writing to the file being created has priority over other pending file I/O requests.

v v v

IBM 4680 BASIC does not support the ability to alter the security attributes set with the ACCESS statement, after the file has been created. LOCKED, UNLOCKED, and READONLY apply to files only. They specify how a file is to be shared with other processes while the creating process has access to the file (before the creating process closes the file). These reserved words do not affect the level of protection that ACCESS statements define. In the store controller, every read or write forces the disk to be updated unless the file is opened in LOCKED mode. You must not open files when they are in LOCKED mode if you use the HOLD reserved word on the WRITE # statement. Example Sample Program
! The following example uses the CREATE statement ! to create a new file and then writes two records ! to it. INTEGER*2 C% REAL D STRING A$,B$ CREATE "TESTFILE.TMP" RECL 25 AS 10 PRINT "creating new file called TESTFILE.TMP" PRINT A$ = "field one"
Chapter 7. Statements and Language-Defined Functions

53

CREATE Statement
B$ = "field two" C% = 321 D = 4.5 WRITE #10,1;A$,B$ WRITE #10,2;C%,D CLOSE 10 PRINT "TYPE the new file to see the contents" PRINT "thats all folks" END

Output Output for the sample program is written to the screen and to a file.
SCREEN OUTPUT ------------creating new file called TESTFILE.TMP TYPE the new file to see the contents thats all folks FILE OUTPUT ----------(contents of TESTFILE.TMP)

"field one","field two" 321,4.5,

CREATE POSFILE Statement


Syntax
=========BUFF 1=========== CREATE POSFILEnameASI/O session number BUFF number of buffers ====BUFFSIZE 128===== ==UNLOCKED== LOCKED BUFFSIZE buffersize READONLY ==============LOCAL============= COMPOUND ATCLOSE MIRRORED PERUPDATE

Use

store controller only

Explanation The CREATE POSFILE statement creates a point of sale sequential disk file on a store controller and assigns distribution attributes to the file. If you create a file with a file name that already exists, the CREATE POSFILE statement erases the existing file before creating the new file. v Name is any valid filename. See Name Specification on page 34 for a complete description of reserved word. v I/O session number is a unique identification number you assign to a file. An I/O session number can be any numeric expression that evaluates to a 2-byte integer ranging from 1 to 99.

54

IBM 4680 BASIC: Language Reference

CREATE POSFILE Statement


v BUFF specifies a numeric value used to determine the size of the I/O buffer. The BUFF value multiplied by 128 determines the size of the buffer in number of bytes. If you specify the BUFFSIZE parameter, BUFF is ignored. v BUFFSIZE specifies a numeric value representing the size of the I/O buffer in number of bytes. This is more flexible than the BUFF parameter, which represents only multiples of 128 bytes. If you specify BUFFSIZE, the BUFF parameter is ignored. v LOCKED does not allow access to the file by other processes. LOCKED assures exclusive use of the file by the creating process, until the creating process closes the file. At that time, the file can be opened by users with the privilege to open. v UNLOCKED allows other processes both to read and to write to the file. The default mode for a file is UNLOCKED. UNLOCKED allows read and write access only to those users with read and write privileges to the file. v READONLY allows other processes to read from, but not write to the file. READONLY prohibits writing to the file even from processes that have write privileges. READONLY does not grant temporary read privileges to processes that usually do not have them. v LOCAL designates that this file is not to be distributed. v COMPOUND designates that this file is to be distributed to all store controllers that handle application compound files in this local area network. v MIRRORED designates that this file is to be distributed only to the Alternate Master/File Server store controller. v ATCLOSE designates that this file is to be distributed when the file is closed or when a TCLOSE statement is issued for this file. v PERUPDATE designates that this file is to be distributed whenever the file is modified. Note: See the IBM 4680 Store System: Planning and Configuration Guide or the IBM 4690 Store System: Planning, Installation and Configuration Guide for further information on the Alternate Master and File Server store controllers. Example Sample Program
! The following example uses the CREATE POSFILE ! statement to create a point-of-sale sequential ! disk file for the store controller environment. INTEGER*4 A%,B% PRINT "OPEN POSFILE AND WRITE/READ" CREATE POSFILE "SALE.DAT" AS 6 BUFF 4 UNLOCKED\ MIRRORED ATCLOSE A% = 32123 PRINT "WRITING FILE" WRITE FORM "I4" ; #6 ; A% PRINT "FILE WRITTEN" READ FORM "I4" ; #6 ; B% PRINT "FILE READ" PRINT "THATS ALL FOLKS" CLOSE 6 END
Chapter 7. Statements and Language-Defined Functions

55

CREATE POSFILE Statement


Output Output for the sample program is:
OPEN POSFILE AND WRITE/READ WRITING FILE FILE WRITTEN FILE READ THATS ALL FOLKS

CREATE POSFILE KEYED Statement


Syntax

========================== CREATE POSFILEnameKEYEDkey length , randomizing divisor ===========4============= , , number of recordsRECL record length chaining threshold value. ==UNLOCKED== ASI/O session numberLOCKED READONLY ==============LOCAL============= COMPOUND ATCLOSE MIRRORED PERUPDATE

Figure 7. CREATE POSFILE KEYED Statement

Use

store controller only

Explanation The CREATE POSFILE KEYED statement creates a keyed disk file on a store controller and allocates disk space for the file. The space is filled with hexadecimal (hex) zeros. If you create a file with a file name that already exists, the CREATE POSFILE KEYED statement erases the existing file before creating the new file. v Name is any valid file name. See Name Specification on page 34 for a complete description of this reserved word. v KEYED key length is the number of bytes the key occupies in a record and must be in the range of 1 to the value specified for the record length. v Randomizing divisor is numeric and must be in the range of 1 to the maximum data set size (in 512-byte sectors). This value determines how the keyed records are dispersed in the file. The default value is the largest odd number less than, or equal to, the number of sectors allocated for the file, unless the result is a multiple of 5, in which case 2 is subtracted from the result. v Chaining threshold value is numeric and must be in the range of 1 to 255. It defaults to 4. This value is the number of sectors that are checked to find a keyed record before an error is logged into the error log file.

56

IBM 4680 BASIC: Language Reference

CREATE POSFILE KEYED Statement


The application is not notified that the threshold has been exceeded, and data is still returned to the application. v Number of records is a 4-byte integer that defines the total number of records that will fit in the file. This number should be approximately 20% larger than the actual number of records to account for the way keyed records are arranged in a file. Also, to allow for growth, you may want to add to this 20% factor, based on your expected file size. (A file that is too tightly packed slows down the accessing of data in that file. This adversely affects performance.) v RECL record length is numeric and must be in the range of 1 to 508. v I/O session number is a unique identification number you assign to a file. An I/O session number can be any numeric expression that evaluates to a 2-byte integer ranging from 1 to 99. v LOCKED assures exclusive use of the file by the creating process, until the creating process closes the file. At that time, users with the privilege to open the file can open it. v UNLOCKED allows other processes both to read and write to the file. The default mode for a file is UNLOCKED. UNLOCKED allows read and write access only to those users with read and write privileges to the file. v READONLY allows other processes to read from, but not to write to, the file. READONLY prohibits writing to the file even from processes that have write privileges. READONLY does not grant temporary read privileges to processes that usually do not have them. v LOCAL designates that this file is not to be distributed. v COMPOUND designates that this file is to be distributed to all store controllers that handle application compound files in this local area network. v MIRRORED designates that this file is to be distributed only to the Alternate Master/File Server store controller. v ATCLOSE designates that this file is to be distributed when the file is closed. v PERUPDATE designates that this file is to be distributed whenever the file is modified. Note: See the IBM 4680 Store System: Programming Guide or the IBM 4690 Store System: Programming Guide for more information on keyed files and for further information on Alternate Master and File Server store controllers. Example Sample Program
! ! ! ! ! ! The following example uses the CREATE POSFILE KEYED statement to create a point-of-sale keyed disk file for the store controller environment. The example uses the DELREC statement to delete the record identified by the key value variable KEY$.

INTEGER*4 A%,B% STRING C$,D$,F$,DATA$,KEY$ PRINT "OPEN KEYED FILE AND WRITE/DELETE" CREATE POSFILE "A:KEYEDTST" KEYED 4 ,,, 10 RECL 14 AS 6 KEY$ = "3456" A% = 32123
Chapter 7. Statements and Language-Defined Functions

57

CREATE POSFILE KEYED Statement


DATA$ = "KEYED" PRINT "WRITE KEYED FILE" WRITE FORM "C4,I4,C6" ; #6 ; KEY$,A%, DATA$ PRINT "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

CREATE POSFILE RANDOM/DIRECT Statement


Syntax
RANDOM CREATE POSFILEname number of records DIRECT

==UNLOCKED== RECL record lengthASI/O session numberLOCKED READONLY ==============LOCAL============= COMPOUND ATCLOSE MIRRORED PERUPDATE

Use

store controller only

Explanation The CREATE POSFILE RANDOM/DIRECT statement creates a point of sale random/direct disk file on a store controller and assigns distribution attributes to the file. This CREATE statement allocates the initial disk space for the file. Creating a random or direct file does NOT zero the space allocated for the file. If you create a file with a file name that already exists, the CREATE POSFILE RANDOM/DIRECT statement erases the existing file before creating the new file. v Name is any file name. See Name Specification on page 34 for a complete description of this reserved word. v RANDOM specifies that the file created is a random type of file. v DIRECT specifies that the file created is a direct type of file. v The number of records is a 4-byte integer that specifies the initial number of records in the file. v RECL record length is numeric.

58

IBM 4680 BASIC: Language Reference

CREATE POSFILE RANDOM/DIRECT Statement


v I/O session number is a unique identification number you assign to a file. An I/O session number can be any numeric expression that evaluates to a 2-byte integer ranging from 1 to 99. v LOCKED assures exclusive use of the file by the process that created it until that process unlocks it. v UNLOCKED allows read and write access only to those processes that have permanent read and write privileges assigned in an ACCESS statement. v READONLY restricts write access to the file by all processes. v LOCAL designates that this file is not to be distributed. v COMPOUND designates that this file is to be distributed to all store controllers that handle application compound files in this local area network. v MIRRORED designates that this file is to be distributed only to the Alternate Master/File Server store controller. v ATCLOSE designates that this file is to be distributed when the file is closed. v PERUPDATE designates that this file is to be distributed whenever the file is modified. Note: See the IBM 4680 Store System: Programming Guide or the IBM 4690 Store System: Programming Guide for further information about Alternate Master and File Server store controllers. Example Sample Program
! ! ! ! The following example uses the CREATE POSFILE RANDOM/DIRECT statement creates a point-of-sale random/direct disk file for a store controller environment.

INTEGER*2 A%,B% PRINT "OPEN POSFILE RANDOM FILE AND WRITE/READ" CREATE POSFILE "FILE.DAT" RANDOM 1 RECL 25 AS 6 A% = 321 PRINT "WRITING FILE" WRITE #6,1; A% PRINT "FILE WRITTEN" READ #6,1; B% PRINT "FILE READ -- CONTENTS ="; B% CLOSE 6 END

Output Output for the sample program is:


OPEN POSFILE RANDOM AND WRITE/READ WRITING FILE FILE WRITTEN FILE READ -- CONTENTS = 321

DATA Statement
Syntax

Chapter 7. Statements and Language-Defined Functions

59

DATA Statement
DATA constant ..... , ....

Use

store controller and terminal

Explanation The DATA statement defines a list of constants that a READ statement can assign to variables. The constant list in a DATA statement can be any combination of integer, real, and string constants. Delimit each constant with a comma or a carriage return/line-feed. The last constant specified must be delimited by a carriage return/line feed. Integer constants may only be decimal constants (not binary or hexadecimal). Data types for constants in DATA statements and the corresponding variables in READ statements must match. If data types do not correspond, the READ statement assigns erroneous data to the variables. Real constants assigned to integer variables by a READ statement are truncated to the integer portion of the real number. Use the backslash continuation character to write a long DATA statement on more than one physical line. The backslash can appear within a string constant if you enclose the string in quotation marks. Otherwise, string constants do not require quotation marks. You can only use quotation marks in DATA statements as delimiters for string constants. You cannot use them within a DATA statement string constant. DATA statements are nonexecutable and can appear anywhere in a main program. IBM 4680 BASIC handles all DATA statements in a main program as one consecutive list of constants. Note: Do NOT use DATA statements in a function or subprogram. See the READ and RESTORE statements in this chapter for additional information. Example Sample Program
! ! ! ! The following example uses the DATA statement to define a list of values that are assigned to the corresponding variables with the READ statement.

INTEGER*4 I%,EMPNUM% REAL WAGE STRING EMPNAME$ FOR I% = 1 TO 5 READ EMPNAME$,EMPNUM%,WAGE PRINT EMPNAME$,EMPNUM%,WAGE NEXT I% DATA DATA DATA DATA DATA END MOHR,123976,22.75 MEBANE,144965,4.75 ADKINS,333927,75.88 SMITH,739528,35.27 REAGAN,927653,95.75

Output

60

IBM 4680 BASIC: Language Reference

DATA Statement
Output for the sample program is:
MOHR MEBANE ADKINS SMITH REAGAN 123976 144965 333927 739528 927653 22.75 4.75 75.88 35.27 95.75

DATE$ Function
Syntax
a$ = DATE$

Use

store controller and terminal

Explanation The DATE$ function returns a string indicating the current year, month, and day set through the operating system. a$ is a string value returned by the DATE$ function. DATE$ returns a six-character string in the form YYMMDD. YY is the last two digits of a year reference, such as 91 for 1991. MM is a two-digit number representing the month such as 02 for February or 08 for August. DD is a two-digit number representing the day of the month. Example Sample Program
! The following example writes the system date ! in the form YYMMDD using the DATE$ function STRING CURDATE$ CURDATE$ = DATE$ PRINT "todays date (YYMMDD) is ";CURDATE$ END

Output Output for the sample program is:


todays date (YYMMDD) is 910827

Note: Output is the system date in the store controller.

DEF Statement
Syntax

Chapter 7. Statements and Language-Defined Functions

61

DEF Statement
Singleline: ================= DEFfunction name = expression (parameter) ......,...... maximum 15 Multiple line: ================= =========== DEFfunction name EXTERNAL (parameter) PUBLIC ......,...... maximum 15 ============= RECURSIVE

Use

store controller and terminal

Explanation The DEF statement defines both single-line and multiline functions. A function definition must occur in a program before the function can be used. The DEF statement is the same as the FUNCTION statement. A formal parameter is always a string or numeric variable, never a constant. Arrays are not allowed. If a formal parameter is a string variable, the actual parameter must be a string expression. If the formal parameter is numeric, the actual parameter must be numeric. Real numbers convert to integers, and integers convert to real as required. v Function name is an identifier. v The parameter list contains the formal parameters that hold a place for actual parameters specified in the function reference. You can specify a maximum of 15 parameters. All formal parameters and any variables declared in the declaration group are local to the function. Labels defined in a multiline function are local to that function. See Chapter 6, Subroutines, Subprograms, and User-Defined Functions for complete information on defining and using functions. v EXTERNAL identifies an abbreviated function definition that corresponds to a complete PUBLIC function definition in a separate module. The abbreviated EXTERNAL function definition consists of the FUNCTION statement, parameter declarations, and the END FUNCTION statement. v PUBLIC identifies the complete function definition accessible from separate modules in your program. v RECURSIVE is an optional flag indicating that the function will be called recursively (see Recursive Subprograms or Functions on page 31). The RECURSIVE flag directs the compiler to allocate any local variables declared by the function on the stack. The variables exist only while the function has control, and they do not retain their values between calls to the function.

62

IBM 4680 BASIC: Language Reference

DEF Statement
Note: RECURSIVE functions are less efficient than nonrecursive ones because of the overhead associated with managing stack variables. See Separate Subprogram and Function Compilation on page 30 for information on the PUBLIC and EXTERNAL reserved words. Example Sample Program
! ! ! ! ! The following example uses the DEF statement to define a multiline FUNCTION that returns the largest of two INTEGERS. Notice that the function can be called directly in an expression or as a item in a PRINT list.

INTEGER*2 I%,J% DEF LARGEST%(VAL1%,VAL2%) INTEGER*2 VAL1%,VAL2%,LARGEST% IF VAL1% > 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 Statement
Syntax
DELETEI/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 Program
Chapter 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 Statement
Syntax
DELRECI/O session number;key value

Use

store controller and terminal

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

IBM 4680 BASIC: Language Reference

DELREC Statement
PRINT "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 Statement
Syntax
DIMidentifier (subscript) .....,.....

Use

store controller and terminal

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 Statement
INTEGER 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 Function
Syntax
i4 = DISABLE

Use

store controller and terminal

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 Function
Syntax
i4 = ENABLE

Use

store controller and terminal

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

IBM 4680 BASIC: Language Reference

ENABLE Function
i4 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 Statement
Syntax
END

Use

store controller and terminal

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 Statement


Syntax
END FUNCTION

Use

store controller and terminal

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 Statement


Syntax
END SUB

Use

store controller and terminal

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

IBM 4680 BASIC: Language Reference

END SUB Statement


Output 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 Function
Syntax
a$ = ERR

Use

store controller and terminal

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% Function
Syntax
i% = ERRF%

Chapter 7. Statements and Language-Defined Functions

69

ERRF% Function
Use 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 Function
Syntax
i% = ERRL

Use

store controller and terminal

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

IBM 4680 BASIC: Language Reference

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 Function
Syntax
i4 = ERRN

Use

store controller and terminal

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% = ERRN
Chapter 7. Statements and Language-Defined Functions

71

ERRN Function
ERRFX$ = "" 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% Function
Syntax
i% = EVENT%

Use

store controller and terminal

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

IBM 4680 BASIC: Language Reference

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

EXIT FUNCTION Statement


Syntax
EXIT FUNCTION

Use

store controller and terminal

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% END
Chapter 7. Statements and Language-Defined Functions

73

EXIT FUNCTION Statement


Output 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 - continue FUNCTION the sum of the largest numbers is 120

EXIT SUB Statement


Syntax
EXIT SUB

Use

store controller and terminal

Explanation The EXIT SUB statement returns control from the multiline subprogram to the statement in the main program following the subprogram call or reference. Use an EXIT SUB to leave a subprogram before getting to the END SUB statement. DO NOT use the RETURN statement to return from a subprogram. There can be multiple EXIT SUB statements in a subprogram. Example Sample Program
! ! ! ! The following example uses the EXIT SUB statement to leave a SUBPROGRAM before the END SUB statement is reached if the two parameters passed to it are equal.

SUB FINDLARGE(VAL1%,VAL2%) INTEGER*2 VAL1%,VAL2%,LARGEST% IF VAL1% = VAL2% THEN \ BEGIN PRINT "values are equal - abort SUBPROGRAM" EXIT SUB ENDIF PRINT "values are not equal - continue SUBPROGRAM" IF VAL1% > VAL2% THEN \ LARGEST% = VAL1% \ ELSE \ LARGEST% = VAL2% PRINT "the larger of";VAL1%;"and";VAL2%;"is"; PRINT LARGEST% END SUB CALL FINDLARGE(10,20) CALL FINDLARGE(100,25) CALL FINDLARGE(33,33) END

Output Output for the sample program is:

74

IBM 4680 BASIC: Language Reference

EXIT SUB Statement


values are the larger values are the larger values are not equal - continue SUBPROGRAM of 10 and 20 is 20 not equal - continue SUBPROGRAM of 100 and 25 is 100 equal - abort SUBPROGRAM

FEND Statement
Syntax
FEND

Use

store controller and terminal

Explanation The FEND statement is the same as the END FUNCTION statement. See END FUNCTION Statement on page 67 for an explanation of the statement. Example Sample Program
! The following example uses the FEND 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% 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

FLOAT Function
Syntax
x = FLOAT(numeric expression)

Use

store controller and terminal

Explanation The FLOAT function converts a number to a floating-point real number. The FLOAT function accepts only 4-byte integer values in IBM 4680 BASIC. A conversion of the input argument to a 4-byte integer occurs if necessary. v x is a real number that the FLOAT function returns. v Numeric expression is any real number or integer expression.
Chapter 7. Statements and Language-Defined Functions

75

FLOAT Function
Example Sample Program
! The following example converts an integer into ! a floating-point real number INTEGER*4 I% REAL J,K,L I% = 10 J = I% / 3 K = FLOAT(I% / 3) L = FLOAT(I%) / 3

! ! ! ! !

notice we must use FLOAT before the calculation in order to preserve the decimal places

PRINT "the decimal places are truncated -> ";J PRINT "the decimal places are truncated -> ";K PRINT "all the decimal places -> ";L END

Output Output for the sample program is:


the decimal places are truncated -> 3 the decimal places are truncated -> 3 all the decimal places -> 3.333333333333333

FOR Statement
Syntax
FORindex variable = numeric expressionTOnumeric expression =========STEP 1========== STEP numeric expression

Use

store controller and terminal

Explanation The FOR statement controls the execution of a FOR/NEXT loop. All statements between a FOR statement and a corresponding NEXT statement execute repeatedly, depending on the numeric expressions. v Index variable must be a nonsubscripted numeric variable, either real or integer. Using real (floating point) variables as index variables is not recommended because this causes the FOR/NEXT loop to execute much more slowly than using integer variables. v Numeric expression before the reserved word TO specifies the initial value of the loop index variable. v Numeric expression after the reserved word TO specifies the terminal value of the loop index variable. v Numeric expression specified with the reserved word STEP is optional. Each execution of the statements in the FOR/NEXT loop adds the value in the STEP expression to the index variable. If STEP is not specified, the value defaults to 1. If the STEP expression is positive, the value of the index variable must exceed the expression following the reserved word TO for the loop to terminate. If STEP expression is negative, the value of the index variable must be less than the expression following the reserved word TO for the loop to terminate.

76

IBM 4680 BASIC: Language Reference

FOR Statement
The FOR statement converts all numeric expressions to real numbers if the index variable is real and to integers if the index variable is an integer. FOR/NEXT loops can contain any statement. You can nest FOR/NEXT loops to a maximum nesting level of 13. See NEXT Statement on page 105 for additional information. Example Sample Program
! The following example uses the FOR statement ! to create two nested FOR/NEXT loops INTEGER*2 I%,J% FOR I% = 1 TO 3 FOR J% = 5 TO 1 STEP -1 PRINT "I% = ";I%;"J% = ";J% NEXT J% NEXT I% END

Output Output for the sample program is:


I% I% I% I% I% I% I% I% I% I% I% I% I% I% I% = = = = = = = = = = = = = = = 1 1 1 1 1 2 2 2 2 2 3 3 3 3 3 J% J% J% J% J% J% J% J% J% J% J% J% J% J% J% = = = = = = = = = = = = = = = 5 4 3 2 1 5 4 3 2 1 5 4 3 2 1

FRE Function
Syntax
i4 = FRE

Use

store controller and terminal

Explanation FRE returns a 4-byte integer indicating the number of bytes available in the heap. For information about the heap, see The Heap on page 287. i4 is a 4-byte integer returned by the FRE function. Example Sample Program
! The following example uses the FRE function to ! determine remaining free heap space ! INTEGER*4 SPACE SPACE = FRE PRINT "remaining heap space is ";SPACE;"bytes" IF SPACE < 1000 THEN \
Chapter 7. Statements and Language-Defined Functions

77

FRE Function
PRINT "CAUTION - low heap space" \ ELSE \ PRINT "heap space OK" END

Output Output for the sample program is:


remaining heap space is heap space OK 1475216 bytes

Note: The actual number of bytes available in the heap depends on the current state of the system when the FRE function executed.

FUNCTION Statement
Syntax
Single line: =============== FUNCTIONfunction name = expression (parameter) .... , .... maximum 15 Multiple line: =============== ========== FUNCTIONfunction name EXTERNAL (parameter) PUBLIC .... , .... maximum 15 =========== RECURSIVE

Use

store controller and terminal

Explanation The FUNCTION statement defines both single-line and multiline user-defined functions. You can call a function in a program using the CALL statement, or you can reference a function in an expression. A function definition must occur in a program before any calls or references to the function can be made. The FUNCTION statement and the DEF statement work exactly the same. Single-line function definitions use an equal sign followed by an expression. The expression defines the actual task that the single-line function performs. The data types used in the expression must correspond to the data type used in the function name. Multiline function definitions include optional data declarations and any number of statements. A FUNCTION statement precedes the declaration group, and an END FUNCTION statement terminates the function. Use an EXIT FUNCTION statement to leave a function before the END FUNCTION statement. Do not use the RETURN statement to exit from a function. v Function name is an identifier.

78

IBM 4680 BASIC: Language Reference

FUNCTION Statement
v The parameter list contains the formal parameters that hold a place for actual parameters specified in the function reference. You can specify a maximum of 15 parameters. A formal parameter is either a string variable or numeric variable. A formal parameter cannot be a constant or an array. If a formal parameter is a string variable, the actual parameter must be a string expression. If the formal parameter has a numeric data type, the actual parameter must have the exact same numeric data type. All formal parameters and any variables declared in the declaration group are local to the function. Labels defined in a multiline function are local to that function. See Chapter 6, Subroutines, Subprograms, and User-Defined Functions for complete information on defining and using functions. v EXTERNAL identifies an abbreviated function definition that corresponds to a complete PUBLIC function definition in a separate module. The abbreviated EXTERNAL function definition consists of the FUNCTION statement, parameter declarations, and the END FUNCTION statement. v PUBLIC identifies the complete function definition accessible from separate modules in your program. v RECURSIVE is an optional flag indicating that the function will be called recursively (see Recursive Subprograms or Functions on page 31). The RECURSIVE flag directs the compiler to allocate any local variables declared by the function on the stack. The variables exist only while the function has control, and they do not retain their values between calls to the function. Note: RECURSIVE functions are less efficient than nonrecursive ones because of the overhead associated with managing stack variables. See Separate Subprogram and Function Compilation on page 30 for information on the PUBLIC and EXTERNAL reserved words. Functions can be called or referenced. You reference a function by using the function name in an expression. See the following examples to see how a function is called or referenced. Example Sample Program
! ! ! ! ! The following example uses the FUNCTION statement to define a multiline FUNCTION that returns the larger of two INTEGERS. Notice that the function can be called directly in an expression or as a item in a PRINT list.

INTEGER*2 I%,J% FUNCTION LARGEST%(VAL1%,VAL2%) INTEGER*2 VAL1%,VAL2%,LARGEST% IF VAL1% > VAL2% THEN \ LARGEST% = VAL1% \ ELSE \ LARGEST% = VAL2% FEND I% = LARGEST%(10,20) J% = LARGEST%(100,25)
Chapter 7. Statements and Language-Defined Functions

79

FUNCTION Statement
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

FUNCTIONKEY Statement
Syntax
ON FUNCTIONKEY OFF

Use

store controller only

Explanation The FUNCTIONKEY statement shows or erases a one-line display of the current definitions of the Programmable Function (PF) keys, at the bottom line of the current window. v ON shows the display. v OFF erases the display. See ASSIGNKEY Statement on page 40 for more information. Example Sample Program
! ! ! ! The following example uses the FUNCTIONKEY statement to display the function key definitions on the screen. See the ASSIGNKEY statement in this chapter for more information.

ASSIGNKEY 1,"HELP" ASSIGNKEY 3,"QUIT" ASSIGNKEY 5,"THIS" ASSIGNKEY 7,"THAT" ASSIGNKEY 10,"TEST" FUNCTIONKEY ON PRINT "press any key to quit" WHILE NOT CONSTAT% WAIT ; 200 ! suspend execution to service lower priority tasks WEND FUNCTIONKEY OFF END

Output The first six (6) characters of the function key definitions should appear at the bottom of the screen when this example is executed.

GET Function
Syntax

i% = GET(I/O session number)

Use

store controller only

80

IBM 4680 BASIC: Language Reference

GET Function
Explanation The GET function reads 1 byte of data from the disk file specified by I/O session number. Each execution of GET reads the binary data from one byte in the file and returns an integer value between 0 and 255. v i% is an integer returned by the GET function. See Chapter 8, Using Input and Output Devices and Pipes for details. v I/O session number is a unique identification number you assign to a file in a CREATE or OPEN statement. Example Sample Program
! ! ! ! ! ! ! ! ! The following example uses GET to sequentially retrieve every byte from an existing text file named LOWERCSE.TXT. If the byte corresponds to a lowercase ASCII character, it is replaced by the corresponding uppercase ASCII character. If the byte is not a lowercase ASCII character, it is not changed. The example uses PUT to put the resulting byte into a new file called UPPERCSE.TXT. \

REM Translate a lowercase text file into an uppercase text file INTEGER*2 I% OPEN "LOWERCSE.TXT" AS 1 CREATE "UPPERCSE.TXT" AS 2 IF END # 1 THEN DONE WHILE 1 I% = GET(1) IF I% >= 97 AND I% <=122 THEN I% = I% - 32 PUT 2, I% WEND STOP DONE: PRINT "TRANSLATION IS COMPLETE." CLOSE 1 CLOSE 2 END

Output Output for the sample program is:


TRANSLATION IS COMPLETE.

GETLONG Function
Syntax
i4 = GETLONG(I/O session number)

Use

store controller and terminal

Explanation The GETLONG statement returns information from a specified I/O session. v I/O session number is the number assigned to an I/O device in the OPEN statement. v i4 is a 4-byte integer containing specific information returned from the I/O device. See Terminal Input/Output Device Drivers on page 198 for the definition of i4 for each I/O device.

Chapter 7. Statements and Language-Defined Functions

81

GETLONG Function
Example Sample Program
00100! In the following example, the GETLONG function 00200! returns a 4-byte integer representing status for 00300! asynchronous communication line identified by 00400! the I/O session number 21. The particular piece 00500! of information we want is stored in the third byte 00600! of the returned 4-byte integer. The example uses 00700! the logical AND operator and the shift function 00800! to isolate the third byte in the return value. 00900! See "Logical Expressions" for more information 01000! on logical operations. 01100 01200INTEGER*4 STATUS%, A%, B% 01300INTEGER*2 BSIZE% 01400 01500 BSIZE% = 250 01600 OPEN LINK ASYNC "COMMLINE.POS" AS 21 BUFFSIZE BSIZE% 01700 . 01800 . 01900 STATUS% = GETLONG(21) 02000 A% = STATUS% AND OFFFFH ! MASK OFF BYTE #1,#2 02100 B% = SHIFT(A,8) ! SHIFT OUT BYTE #4 02200 PRINT "STATUS IN BYTE #3 IS "; B% 02400END

GOSUB Statement
Syntax
GOSUBlabel

Use

store controller and terminal

Explanation The GOSUB statement transfers control to a subroutine identified with a label. IBM 4680 BASIC saves the address of the statement that follows the GOSUB statement on the calling programs stack. This allows a RETURN statement to return control to the statement following the GOSUB. Label identifies a statement to which control transfers. The label must be defined somewhere within the program. GOSUB statements inside user-defined multiline functions or subprograms cannot reference a label outside the body of the function or subprogram. GOSUB statements outside of a given function or subprogram cannot reference a label inside the function or subprogram. Example Sample Program
! ! ! ! The following example uses the GOSUB statement to transfer control to a subroutine. Notice the STOP statement in the main program to prevent entering the subroutine directly.

! NOTE: ALWAYS use a RETURN statement to exit ! from a subroutine that was entered with ! a GOSUB. NEVER use a GOTO statement for ! this purpose. PRINT GOSUB PRINT GOSUB "now in main program" PRINT.MESSAGE "back in main program" PRINT.MESSAGE

82

IBM 4680 BASIC: Language Reference

GOSUB Statement
PRINT "thats all" STOP PRINT.MESSAGE: PRINT PRINT "now executing subroutine PRINT.MESSAGE" PRINT "the message is HELLO" PRINT RETURN END

Output Output for the sample program is:


now in main program now executing subroutine PRINT.MESSAGE the message is HELLO back in main program now executing subroutine PRINT.MESSAGE the message is HELLO thats all

GOTO Statement
Syntax
GOTOlabel

Use

store controller and terminal

Explanation The GOTO statement transfers execution to a statement identified with a label. If the specified statement is not executable, execution continues with the next statement encountered. Label identifies a statement to which control transfers. You must define the label somewhere within the program. Labels within user-defined multiline functions (except IF END # and ON ERROR labels) are local to those functions. GOTO statements inside user-defined multiline functions cannot reference a label outside the body of the function. GOTO statements outside of a given function cannot reference a label inside the function. You cannot place a colon after an alphabetic label in a GOTO statement. Note: Use the RESUME statement, not the GOTO statement, to recover from the ON ERROR user code. Example Sample Program
! The following example demonstrates transfer of control ! to a label using the GOTO statement. ! ! ! ! ! Notice that the order of execution has been drastically changed from the order in which the statements are written. This use of GOTO statements is generally not a good programming practice as it makes the
Chapter 7. Statements and Language-Defined Functions

83

GOTO Statement
! flow of execution difficult to follow. PRINT "starting at first executable statement" GOTO PRINT.MESSAGE ENDIT: PRINT PRINT "now I have jumped to ENDIT" PRINT "thats all" STOP ANOTHER.MESSAGE: PRINT PRINT "now I have jumped to ANOTHER.MESSAGE" PRINT "the new message is GOODBYE" GOTO ENDIT PRINT.MESSAGE: PRINT PRINT "now I have jumped to PRINT.MESSAGE" PRINT "the message is HELLO" GOTO ANOTHER.MESSAGE END

Output Output for the sample program is:


starting at first executable statement now I have jumped to PRINT.MESSAGE the message is HELLO now I have jumped to ANOTHER.MESSAGE the new message is GOODBYE now I have jumped to ENDIT thats all

IF Statement
Syntax
IFlogical expressionTHENstatement group1 ========================= ELSEstatement group2

Use

store controller and terminal

Explanation The IF statement is used to: v Evaluate a logical expression v Check a value for zero (0). When 4680 BASIC evaluates the logical expression, for example in the case of IF x = y, when x is equal to y, the expression is true (-1). When x is not equal to y, the expression is false (0).

84

IBM 4680 BASIC: Language Reference

IF Statement
When 4680 BASIC checks for a value, for example in the case of IF x, it checks the value of x and if it is 0, then the expression is false. If the value of x is not 0, the expression is true. Note: If not x is used, x will be complemented before the test. This means only the value -1 will be considered false when the not is used. All other values will result in a true. If the value is false (0) and there is an ELSE clause, control passes to statement group 2. If the value is false (0) and there is no ELSE clause, control passes to the next statement following the IF statement. v Logical expression evaluates to either true or false. v Statement group 1 receives control if the value is true. v Statement group 2 receives control if the value is false. A statement group within an IF statement can contain one or more executable IBM 4680 BASIC statements. There are two methods for including multiple statements in the statement group. With the first method, all the statements between the reserved words BEGIN and ENDIF are treated as one statement. Another IF statement can be one of the statements inside the BEGIN block, and it would be unaffected by the first IF statement. The BEGIN block is allowed only after a THEN or ELSE reserved word. For compatibility reasons, you can use a second method to include multiple statements in the statement group. You can use a colon to separate each statement in a statement group, even those that are placed on consecutive physical lines. You can also use the backslash continuation character to continue a statement group on the next physical line. You can nest IF statements. IF statements that use no ELSE clauses can only be nested downward in nesting level. Control always returns to the top nesting level following the final statement at the deepest level. Nesting of IF statements that have ELSE clauses can be controlled downward and upward in nesting level by the proper pairing of the IF/THEN section with a corresponding ELSE clause. If required, you can use empty or null statements to force the proper pairing of an IF/THEN section with the corresponding ELSE section. An ELSE clause always corresponds to the nearest unpaired IF statement. Example Sample Program
! ! ! ! ! The following example uses the IF statement to determine which of two numbers is the larger and to print that number. Notice the several different methods used for multiple statements in the statement group.

INTEGER*2 VAL1%,VAL2% VAL1% = 10 VAL2% = 20 IF VAL1% > VAL2% THEN \ PRINT "the larger number is";VAL1% \ ELSE \ PRINT "the larger number is";VAL2% VAL1% = 100
Chapter 7. Statements and Language-Defined Functions

85

IF Statement
VAL2% = 73 IF VAL1% > VAL2% THEN \ BEGIN PRINT "the larger number is";VAL1% WAIT;500 ENDIF \ ELSE \ PRINT "the larger number is";VAL2% VAL1% = 3 VAL2% = 15 IF VAL1% > VAL2% THEN \ PRINT "the larger number is";VAL1% :WAIT;500 \ ELSE \ PRINT "the larger number is";VAL2% END

Output Output for the sample program is:


the larger number is 20 the larger number is 100 the larger number is 15

The following example shows the first method for including multiple statements in the statement group. All the statements between the reserved words BEGIN and ENDIF are treated as one statement.
IF I% = 0 THEN \ BEGIN J% = 1 IF J% = 0 THEN \ BEGIN K% = 1 M% = 1 ENDIF \ ELSE \ BEGIN IF J% = 1 THEN \ BEGIN K% = 2 M% = 2 ENDIF K% = 2 M% = 2 ENDIF ENDIF \ ELSE \ BEGIN

The following program fragment shows a nested IF statement with ELSE clauses without using the BEGIN and ENDIF keywords. Control transfers to the corresponding ELSE clause whenever an expression evaluates to false. Corresponding IF/THEN portions and ELSE clauses are lined up in the same column.
IF expression1 THEN \ ! 1st nesting level Statement1 :\ Statement2 :\ IF expression2 THEN \ ! 2nd nesting level Statement11 :\ Statement12 :\ IF expression3 THEN \ ! 3rd nesting level Statement21 :\ Statement22 :\ Statement23 :\ ELSE \ ! 3rd nesting level

86

IBM 4680 BASIC: Language Reference

IF Statement
Statement31 :\ Statement32 :\ ELSE \ ! 2nd nesting level Statement41 :\ Statement42 :\ . ELSE \ ! 1st nesting level Statement51 :\ Statement52 :\ .

IF END # Statement
Syntax
IF END#I/O session numberTHENlabel

Use

store controller and terminal

Explanation The IF END # statement transfers control to the specified label when a file access exception occurs. v I/O session number is a unique identification number you assign to a file or device in a CREATE or OPEN statement. v Label is the statement to which control transfers. For SEQUENTIAL, DIRECT, and RANDOM files, the IF END # statement detects the following file access exceptions: v Attempting to READ past an end-of-file v Disk full when writing to a file v A partial file reads and writes. (An error occurs after some of the data is read or written.) For KEYED files only, IF END # detects the following file access exceptions: v Attempting to OPEN a file that does not exist v Record not found (on a READ FORM statement or a DELREC statement) v Keyed file is full. For Totals Retention only, IF END # detects the following exception: Data exceeds space available for a WRITE # statement. An IF END # statement applies only to the file specified by the I/O session number. A program can have any number of IF END # statements, thereby allowing the same file to transfer execution to different labels. The most recently executed IF END # statement for a given I/O session number is the one in effect when a file-access exception occurs. To detect access errors for a given series of statements, the IF END # statement must execute before the statements. You can execute an IF END # statement for an I/O session number before that I/O session number is active. This procedure traps errors caused by opening a file that does not exist.

Chapter 7. Statements and Language-Defined Functions

87

IF END # Statement
An IF END # statement overrides an ON ERROR statement. The only way to cancel the effect of an IF END # is to close or delete the file. You cannot use the RESUME statement if control has been transferred to an IF END # label. The IF END # statement has no further affect unless you reassign the I/O session number with a CREATE or OPEN statement. Example Sample Program
! ! ! ! ! The following example uses the IF END# statement to transfer control to the statement label 100. The IF END# statement detects the end of file when the READ statement attempts to read a fourth data field that does not exist.

STRING A$,B$,C$,FIELD1$,FIELD2$,FIELD3$,FIELD4$ A$ = "A" B$ = "B" C$ = "C" CREATE "FILE.DAT" AS 15 PRINT # 15; A$,B$,C$ CLOSE 15 IF END # 15 THEN 100 OPEN "FILE.DAT" AS 15 READ # 15; FIELD1$,FIELD2$,FIELD3$,FIELD4$ PRINT FIELD1$,FIELD2$,FIELD3$,FIELD4$ STOP 100 PRINT "TRANSFERRING CONTROL" PRINT "NO MORE DATA...END-OF-FILE" END

Output Output for the sample program is:


TRANSFERRING CONTROL NO MORE DATA...END-OF-FILE

INKEY Function
Syntax
i2% = INKEY

Use

store controller only

Explanation The INKEY function waits for a character to be entered at the console keyboard and then returns the ASCII decimal value equal to that character. i2% is an integer returned by the INKEY function. All sixteen bits of the keyboard data are returned to the application. Unlike the CONCHAR% function, INKEY does not display the character on the screen. Therefore, INKEY is useful for preventing passwords and other special characters from being echoed. Note: INKEY accepts control characters. Example Sample Program

88

IBM 4680 BASIC: Language Reference

INKEY Statement
! The following example writes the ASCII value ! of a pressed key using the INKEY function. ! Notice the key does not show on the screen. INTEGER*2 KEYVALUE% PRINT "press the a key (without the SHIFT key)" KEYVALUE% = INKEY PRINT PRINT "the ASCII decimal equivalent is ";KEYVALUE% END

Output Output for the sample program is:


press the a key (without the SHIFT key) the ASCII decimal equivalent is 97

INPUT Statement
Syntax
================ INPUT variable prompt string; .. , ....

Use

store controller only

Explanation The INPUT statement accepts data from the keyboard during program execution and assigns the data to program variables. v Prompt string must be a string constant. v Each variable initiates a request from the screen. Each response at the keyboard corresponds to a variable in the INPUT statement. The maximum number of variables in the INPUT statement is 15. If you do not specify a literal prompt string, the INPUT statement prompts you for a response with a question mark during program execution. One blank space prints after the prompt. You must separate individual response items with commas. You can enclose string responses in quotation marks, allowing commas to serve as literal characters. Press the carriage return key to complete a response. All characters entered in response are echoed on the screen. For numeric data entered in response to an INPUT statement, the data type converts to the assigned variable data type. Conversion terminates if INPUT encounters an unexpected character. If the number of items entered is less than the number requested with the INPUT statement, a runtime error occurs. Example Sample Program
! The following example uses the INPUT statement ! to enter both a string and an integer from the ! keyboard INTEGER*2 INNUM% STRING INWORD$ INPUT "enter the word HELLO:";INWORD$ PRINT
Chapter 7. Statements and Language-Defined Functions

89

INPUT Statement
PRINT "you have entered the word ";INWORD$ PRINT INPUT "enter the number 123:";INNUM% PRINT PRINT "you have entered the number ";INNUM% END

Output Output for the sample program is:


enter the word HELLO: you entered the word HELLO enter the number 123: you entered the number 123

Note: Entering different strings or numbers produces different results.

INPUT LINE Statement


Syntax
================= INPUT LINEstring variable prompt string;

Use

store controller only

Explanation The INPUT LINE statement accepts one line of data from the keyboard and assigns it to a string variable. v Prompt string is a literal keyboard message that you supply. Prompt string is optional. v String variable is an identifier used to represent values during program execution. The INPUT LINE statement is a special form of the INPUT statement. Only one variable can appear following the reserved word LINE. If you do not specify a literal prompt string, INPUT LINE prompts you for response with a question mark during program execution. INPUT LINE accepts all characters in response, including commas and spaces, until you press the Enter key. If you enter only a carriage return in response, INPUT LINE assigns a null string to the variable. The maximum length of a line is 255 characters. Example Sample Program
! ! ! ! The following example uses the INPUT LINE statement to read in a string from the keyboard. Unlike the INPUT statement, there can be embedded blanks in this string. See the INPUT statement in this chapter.

STRING NAME$,ADDRESS$ INPUT "enter your name: "; LINE NAME$ INPUT "enter your address: "; LINE ADDRESS$ PRINT

90

IBM 4680 BASIC: Language Reference

INPUT LINE Statement


PRINT "hello ";NAME$ PRINT "you live at ";ADDRESS$ PRINT "goodbye" END

Output Output for the sample program depends on what you type in. For example:
enter your name: Thomas Magnum enter your address: 1233 Ocean Blvd., Hawaii hello Thomas Magnum you live at 1233 Ocean Blvd., Hawaii

INT Function
Syntax
x = INT(numeric expression)

Use

store controller and terminal

Explanation The INT function truncates the fractional portion of the numeric expression and returns the integer portion as a real (floating-point) number. v x is a real number returned by the INT function. v Numeric expression is any real number or integer expression. Example Sample Program
! The following example uses the INT function to ! truncate the decimal portion of a real number REAL NUM,TRUNCNUM NUM = 1234.567 TRUNCNUM = INT(NUM) PRINT NUM;"is a real number with decimal places" PRINT PRINT TRUNCNUM;"is the result of using the INT" PRINT " function to truncate the decimal portion" END

Output Output for the sample program is:


1234.567 is a real number with decimal places 1234 is the result of using the INT function to truncate the decimal portion

INT% Function
Syntax
i4 = INT%(numeric expression)

Use

store controller and terminal

Explanation INT% truncates the fractional portion of the numeric expression and returns the integer portion as an integer. Integer expressions first convert to real numbers then back to integer form.
Chapter 7. Statements and Language-Defined Functions

91

INT% Function
v i4 is a 4-byte integer returned by the INT% function. Conversion to a 1 or 2 byte integer takes place if necessary. v Numeric expression is any real number or integer expression. Example Sample Program
! ! ! ! The following example uses the INT% function to truncate the decimal portion of a real number and return the integer portion as a 4-byte integer

INTEGER*4 TRUNCNUM% REAL NUM NUM = 1234.567 TRUNCNUM% = INT%(NUM) PRINT NUM;"is a real number with 3 decimal places" PRINT PRINT TRUNCNUM%;"is the REAL number converted"; PRINT " to an INTEGER" PRINT " with the decimal portion truncated" END

Output Output for the sample program is:


1234.567 is a real number with 3 decimal places

1234 is the REAL number converted to an INTEGER with the decimal portion truncated

INTEGER Statement
Syntax
==*2=== ========== INTEGER*1 variable *4 GLOBAL .. , .....

Use

store controller and terminal

Explanation The INTEGER statement is a declaration statement that specifies the integer data type for variables and functions. You must place declaration statements before any statements in a program. Integers can be 1, 2, or 4 bytes long. v The length specification consists of an asterisk followed by a number (1, 2, or 4). If the size is not specified, the default length of 2 bytes is used. Refer to the following table. v GLOBAL is an attribute that allows other modules to access specified identifiers. You cannot use GLOBAL in a subprogram or multiline function. To allow a separately compiled function or subprogram to access a global variable, declare the global variable before the function or subprogram definition. v Variable is an identifier. To use an array identifier in an INTEGER statement, place the number of subscripts in parentheses after the array name.

92

IBM 4680 BASIC: Language Reference

INTEGER Statement
Table 10. Integer Memory 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

Example Sample Program


! ! ! ! The following example uses the INTEGER statement to declare an INTEGER of each possible size and store a value in the integer that will not fit in the next smaller size.

INTEGER*1 I% INTEGER*2 J% INTEGER*4 K% I% = 100 J% = 12750 K% = 2077312336 PRINT I%;"is a 1 byte integer" PRINT J%;"is a 2 byte integer" PRINT K%;"is a 4 byte integer" END

Output Output for the sample program is:


100 is a 1 byte integer 12750 is a 2 byte integer 2077312336 is a 4 byte integer

LEFT$ Function
Syntax
a$ = LEFT$(string expression,numeric expression)

Use

store controller and terminal

Explanation The LEFT$ function returns a string consisting of the leftmost characters in a string expression. When evaluating the numeric expression, LEFT$ converts real numbers to integers. v a$ is a string value returned by the LEFT$ function. v String expression is any combination of string operands concatenated with the character operator. v Numeric expression is any real number or integer expression. Numeric expression is a positive value specifying the number of characters to return. If the numeric expression is negative, an error occurs. If the numeric expression equals zero, LEFT$ returns a null string. If the numeric expression specifies more characters than the string contains, LEFT$ returns the entire string Example Sample Program

Chapter 7. Statements and Language-Defined Functions

93

LEFT$ Function
! ! ! ! The following example uses the LEFT$ function to return a substring from a given string starting from the left-hand side of the string and returning a specified number of characters

STRING A$,B$ A$ = "this is a test string" B$ = "another test string" PRINT LEFT$(A$,4) PRINT LEFT$(A$,7) PRINT LEFT$(B$,7) PRINT LEFT$(B$,2) END

Output Output for the sample program is:


this this is another an

LEN Function
Syntax
i2% = LEN(string expression)

Use

store controller and terminal

Explanation The LEN function returns an integer value that is the length of the string expression. LEN returns zero if the expression is a null string. v i2% is an integer returned by the LEN function. v String expression is any combination of string operands concatenated with the character operator. Note: If the LEN value i2% is greater than 32767, the value is negative. Note: The return value of this value is string length in bytes. The length of a DBCS character is 2, while the length of an SBCS character is 1. LEN(eD1D2D3D4) = 5, where e means an SBCS character, and D1D2 and D3D4 mean valid DBCS characters. Example Sample Program
! ! ! ! ! ! ! ! The following example uses the LEN function to determine the length of a string as it doubles from a length of 1 to a length of 32,768. Notice that when LEN returns a negative number it can be converted to positive with the AND statement as in the example below. This condition will happen when the string length reaches 32,768 or greater.

INTEGER*2 I% INTEGER*4 L% STRING A$ A$ = "Z" FOR I% = 1 TO 15

94

IBM 4680 BASIC: Language Reference

LEN Function
A$ = A$ + A$ L% = LEN(A$) IF L% < 0 THEN \ BEGIN L% = L% AND 0000FFFFh PRINT "- LEN returned negative number -" PRINT "- converting length to positive -" ENDIF PRINT "the string length is ";L% NEXT I% END

Output Output for the sample program is:


the string length is 2 the string length is 4 the string length is 8 the string length is 16 the string length is 32 the string length is 64 the string length is 128 the string length is 256 the string length is 512 the string length is 1024 the string length is 2048 the string length is 4096 the string length is 8192 the string length is 16384 - LEN returned negative number - converting length to positive the string length is 32768

LET Statement
Syntax
variable=expression LET

Use

store controller and terminal

Explanation The LET statement assigns the value of expression to variable. The reserved word LET is optional. v Variable is a string, real number, or integer. v Expression is a string, real number, or integer. If the variable is a string variable, the expression must be a string expression. If the variable is numeric, the expression must be numeric. Numeric data types convert automatically if required. Example Sample Program
! The following example uses the LET statement ! to assign an expression to a variable. Note that ! the reserved word LET is optional. INTEGER*2 I%,J% REAL K,L STRING A$,B$ LET I% = 2 + 3 J% = 8 / 4
Chapter 7. Statements and Language-Defined Functions

95

LET Statement
LET K = 10.0 / 4 L = 3 * 2.5 LET A$ = "good" + " " + "morning" B$ = "and to" + " all a " + "good" + PRINT I% PRINT J% PRINT K PRINT L PRINT A$ PRINT B$ END

" night"

Output Output for the sample program is:


5 2 2.5 7.5 good morning and to all a good night

LOAD Statement
Syntax
LOAD"ISTBL = variable1, FMTTBL = variable2, " MODTBL = variable3

Use

terminal only

Explanation The LOAD statement loads the data in the specified files on the LOAD statement. The data is brought into memory to be used by the I/O processor. You must issue a LOAD statement before opening the I/O processor. v variable1 is the file name of the input state table (ISTBL). v variable2 is the file name of the format table (FMTTBL). v variable3 is the file name of the modulo check table (MODTBL). Note: See Name Specification on page 34 for a complete description of the file names. ISTBL is required, but both FMTTBL and MODTBL are optional and have no default value. The table identifiers ISTBL, FMTTBL, and MODTBL must be specified in all uppercase (all capital letters); otherwise, an LD runtime error occurs. If any of the files cannot be loaded, a runtime error occurs, and none of the files are loaded. Refer to the IBM 4680 Store System: Programming Guide or the IBM 4690 Store System: Programming Guide for more information on building ISTBL, FMTTBL, and MODTBL tables. Example Sample Program
! In the following example, the LOAD statement ! loads the file data represented by the string ! variable IOFILES$ for use by the I/O processor:

96

IBM 4680 BASIC: Language Reference

LOAD Statement

%ENVIRON T STRING DATA1$,DATA2$,DATA3$,IOFILES$,VAR4$,VAR5$,\ VAR6$,VAR7$,VAR8$,VAR9$,VAR10$,VAR11$ IOFILES$ = \ "ISTBL = R::ISTBL.POS,FMTTBL=R::FMTTBL.POS," + \ "MODTBL = R::MODTBL.POS" LOAD IOFILES$ OPEN "IOPROC:" AS 20 BUFFSIZE 60 . . READ #20; DATA1$,DATA2$,DATA3$,IOFILES$,VAR4$, \ VAR5$,VAR6$,VAR7$,VAR8$,VAR9$,VAR10$,VAR11$ . . CLOSE 20 END

LOCATE # Statement
Syntax
LOCATE row.value,column.value #I/O session number; ===,ON== ,OFF

Use

store controller and terminal

Explanation The LOCATE # statement sets the current character location. This is the starting coordinate where to READ from, or WRITE to, the display. A display coordinate is defined as (Row, Column). v I/O session number is the number assigned to the display in the OPEN statement. LOCATE # addresses the default console in a controller application if an I/O session number is not specified. An I/O session number is required for a terminal application. v Row is a 2 byte integer or constant that can range from 1 to the maximum number of rows supported by the display. v Column is a 2 byte integer or constant that can range from 1 to the maximum number of columns supported by the display. v ON sets the cursor on (visible) for displays that support a cursor. v OFF sets the cursor off (invisible) on displays that support a cursor. Example Sample Program
! The following example uses the LOCATE # statement ! to write text at specific screen coordinates. CLEARS LOCATE 10,10 PRINT "this appears at row #10, col #10" LOCATE 3,40 PRINT "this appears at row #3, col #40" LOCATE 24,1 PRINT "this appears at row #24,col #1" END
Chapter 7. Statements and Language-Defined Functions

97

LOCATE # Statement
Output The output should appear at the specified place on the screen.

LOCK Function
Syntax
i4 = LOCK(I/O session number,record number)

Use

store controller only

Explanation The LOCK function prevents any other program from modifying the data in a record. LOCK returns a zero (0) if the record is locked successfully. LOCK returns a non-zero value if the record is already locked or cannot be locked because of accessing rights, or an error condition that prevents the record from being locked. If an operating system error occurs, the non-zero value that LOCK returns is the operating system error code. v i4 is a 4-byte integer returned by the LOCK function. v I/O session number is a unique identification number you assign to a file with the CREATE or OPEN statement. v Record number is a 4-byte integer. A record can be locked only if the file has a fixed record length and is accessed in the UNLOCKED mode. A record remains locked until it is unlocked with the UNLOCK function, or until the file is deleted or closed. Refer to the UNLOCK function, CREATE statement, and OPEN statement in this chapter for more information. Do not use the LOCK function for files written with a WRITE # statement that specifies the HOLD parameter. Instead, use the READ AUTOLOCK/WRITE UNLOCK functions. Example Sample Program
! In the following example, the LOCK function ! locks the first record preventing modification ! of data in this record and prints a message . INTEGER*4 E% INTEGER*2 B%,D% REAL C STRING A$ CREATE "READ.TST" RECL 16 AS 1 A$ = "ABCD" B% = 85 C = 613.51 WRITE FORM "C4 I2 R"; #1,1; A$,B%,C OPEN "READ.TST" RECL 16 AS 11 D% = 1 E% = LOCK(11,D%) PRINT E% IF E% = 0 THEN \ PRINT "RECORD "; D%;" IS LOCKED."\ ELSE\ PRINT "ATTEMPT TO LOCK RECORD FAILED." CLOSE 1 END

Output

98

IBM 4680 BASIC: Language Reference

LOCK Function
Output for the sample program is:
0 RECORD 1 IS LOCKED

LOCKDEV Statement
Syntax
=========== LOCKDEVI/O session number ,PURGE

Use

terminal only

Explanation The LOCKDEV statement restricts further input from input devices. A device remains locked under LOCKDEV until it is unlocked with the UNLOCKDEV statement, or until the device is closed. v I/O session number is a unique identification number you assign to a device with the OPEN statement. v PURGE is a flag valid only for the I/O processor in the terminal. If PURGE is present, the I/O processor purges the input queue. Example The following example opens both the I/O processor (IOPROC:) and the magnetic stripe reader (MSR:). During item sales, the magnetic stripe reader is locked. When the mode changes to tender processing, the magnetic stripe reader is unlocked to allow a credit card purchase.
OPEN "MSR:" AS 1 OPEN "IOPROC:" AS 2 BUFFSIZE 40 ! ! While item sales are occurring ! keep MSR: locked. LOCKDEV 1 . . ! During tender processing allow ! input from MSR:. UNLOCKDEV 1 . . END

LPRINTER Statement
Syntax
LPRINTER

Use

store controller only

Explanation The LPRINTER statement directs program output to a printer and output continues to be sent to the printer until a CONSOLE statement is executed. The initial condition when a program begins execution is that output appears on the screen. Neither the LPRINTER nor CONSOLE statement affect the INPUT or INPUT LINE statement prompts which always appear on the screen.

Chapter 7. Statements and Language-Defined Functions

99

LPRINTER Statement
If the current output column is not 1, both the LPRINTER and the CONSOLE statements send a carriage return/line feed before redirecting the output. See CONSOLE Statement on page 50 for more information. Example Sample Program
! The following example uses the LPRINTER statement ! to direct output to the printer. ! NOTE: see also the CONSOLE statement this chapter PRINT "*** WARNING ***" PRINT PRINT "make sure your printer is ready" PRINT "press any key to proceed" PRINT WHILE NOT CONSTAT% WAIT ; 200 ! suspend execution to service lower priority tasks WEND PRINT "this appears on the screen" LPRINTER PRINT "this appears on the printer" CONSOLE PRINT "now we are back to the screen" PRINT PRINT "thats all folks" END

Output Output for the sample program appears on the printer and on the display and is as follows:
SCREEN OUTPUT ------------*** WARNING *** make sure your printer is ready press any key to proceed this appears on the screen now we are back to the screen thats all folks PRINTER OUTPUT -------------this appears on the printer

MATCH Function
Syntax
i2% = MATCH(pattern string,string expression,numeric expression)

Use

store controller and terminal

Explanation The MATCH function returns the position of the first occurrence of a specified character pattern in a string. MATCH searches the string expression for a series of characters matching the pattern defined in the pattern string.

100

IBM 4680 BASIC: Language Reference

MATCH Function
v i2% is a 2-byte integer returned by the MATCH function. v Pattern string contains a series of letters and digits, plus the following wildcard matching characters, that represent different classes of characters: # represents any digit ! represents any lowercase or uppercase letter ? represents any character ! represents any lowercase or uppercase letter, or first or second byte of a valid DBCS character. v String expression is any combination of string operands concatenated with the character operator. v The numeric expression specifies the position at which MATCH starts searching in the string expression for the specified pattern string. If the numeric expression is less than or equal to zero, an error occurs. MATCH returns a zero (0) if either the pattern string or string expression is a null string or cannot be found. The backslash is an escape character in the pattern string. Any character after the backslash is literal, and does not serve as a wildcard character. If you want to have one literal backslash (\), you must enter two backslashes (\\). Note: If the i2% value in the MATCH statement is greater than 32767, the value is negative. Note: The type of the returned position of the entire string should match the type of the first character of the pattern string. (The type includes SBCS characters, the first byte of a valid DBCS character, or the second byte of a valid DBCS character.) MATCH (D2D3, D1D2D3D4, 1) = 0, where D2D3, D1D2, and D3D4 mean valid DBCS characters. Example Sample Program No. 1
! The following example uses the MATCH function to ! determine the position of a character pattern ! in a string in 5 different situations. INTEGER*4 I%,J%,K%,L%,M% I% = MATCH("is","Now is the time",1) J% = MATCH(" ##","April 5, 1987",1) K% = MATCH("a?","character",4) L% = MATCH("\#","1#2345#6789",3) M% = MATCH("abcd","abc",1) PRINT "the results from the MATCH function are:" PRINT I% PRINT J% PRINT K% PRINT L% PRINT M% END

Output (for Sample Program No. 1)

Chapter 7. Statements and Language-Defined Functions

101

MATCH Function
the results from the MATCH function are: 5 9 5 7 0

Sample Program No. 2


! ! ! ! ! ! ! The following example uses the MATCH function to determine the position of a character pattern in a string. Notice that if MATCH returns a negative number, it can be converted to positive using the AND statement. This will happen if the position of the pattern string is 32,768 or greater.

INTEGER*2 I% INTEGER*4 P% STRING A$ A$ = "Z" FOR I% = 1 TO 15 A$ = A$ + A$ NEXT I% A$ = A$ + "TEST" P% = MATCH("TEST",A$,1) IF P% < 0 THEN \ P% = P% AND 0000FFFFh PRINT "the position of the word TEST" PRINT "in the target string is ";P% END

Output (for Sample Program No. 2)


the position of the word TEST in the target string is 32769

MFRE Function
Syntax
i4 = MFRE

Use

store controller and terminal

Explanation The MFRE function returns a 4-byte integer equal to the largest number of contiguous bytes of available memory space in the heap. i4 is a 4-byte integer returned by the MFRE function. Note: MFRE returns an integer that is less than or equal to the value returned by the FRE function. The FRE function returns the total amount of unallocated space in the heap whether or not it is contiguous. Example Sample Program
! The following example uses the MFRE function to ! determine remaining contiguous free heap space INTEGER*4 SPACE% SPACE% = MFRE PRINT "contiguous remaining heap space is "; PRINT SPACE%;"bytes"

102

IBM 4680 BASIC: Language Reference

MFRE Function
IF SPACE% < 1000 THEN \ PRINT "CAUTION - low heap space" \ ELSE \ PRINT "heap space OK" END

Output Output for the sample program is:


contiguous remaining heap space is heap space OK 65527 bytes

Note: The actual number of bytes of contiguous available memory in the heap depends on the current state of the system when the MFRE function is executed.

MID$ Function
Syntax
a$ = MID$(string expression,numeric expression,numeric expression)

Use

store controller and terminal

Explanation The MID$ function returns a segment of a string. When evaluating the numeric expression, MID$ converts real numbers to integers. v a$ is a string value returned by the MID$ function. v String expression is any combination of string operands concatenated with the character operator. v The first numeric expression specifies the position of the first character to return from the string expression. v The second numeric expression specifies the length of the string segment to return. If the first numeric expression is greater than the length of the string, MID$ returns a null string. If the second numeric expression is greater than the number of characters to the right of the first character, MID$ returns all characters to the right of the first character. Example Sample Program
! ! ! ! The following example uses the MID$ function to return a substring from a given string starting at a specified position in the string and returning a specified number of characters

STRING A$,B$ A$ = "this is a test string" B$ = "hello out there" PRINT MID$(A$,1,7) PRINT MID$(A$,11,4) PRINT MID$(B$,7,3) PRINT MID$(B$,11,3) END

Output Output for the sample program is:

Chapter 7. Statements and Language-Defined Functions

103

MID$ Function
this is test out the

MKDIR Statement
Syntax
MKDIRpathname

Use

store controller only

Explanation The MKDIR statement creates a new directory identified by the string expression pathname. To use the MKDIR statement, it is assumed that you have hierarchical or tree structured directories. Pathname is a string that specifies a valid path. You can create as many subdirectories as you want. You are limited only by the amount of disk space available. However, you should check that the maximum length of any single path from the root directory to the level that is wanted is not greater than 127 characters, including embedded backslashes. Example Sample Program
! The following example uses the MKDIR statement ! to create a new subdirectory in the current ! directory. STRING DIRNAME$ DIRNAME$ = "NEWDIR" MKDIR DIRNAME$ DIRNAME$ = "ANOTHER" MKDIR DIRNAME$ DIRNAME$ = "ONEMORE" MKDIR DIRNAME$ PRINT "there should now be the following" PRINT "new subdirectories in the current directory:" PRINT PRINT " NEWDIR ANOTHER ONEMORE" PRINT PRINT " use the RMDIR command to erase them" END

Output Output for the sample program is:


there should now be the following new directories in the current directory: NEWDIR ANOTHER ONEMORE use the RMDIR command to erase them

MOD Function
Syntax
i4 = MOD(numeric expression,numeric expression)

104

IBM 4680 BASIC: Language Reference

MOD Function
Use store controller and terminal

Explanation The MOD function divides the first numeric expression by the second numeric expression and returns the remainder as an integer value. Real numbers convert to integers. All values are converted to 4-byte integers. v i4 is a 4-byte integer returned by the MOD function. v The first numeric expression is the dividend. v The second numeric expression is the divisor. Examples Sample Program
! The following example uses the MOD function to ! return the remainder of the division of two ! INTEGER values. INTEGER*4 I%,J%,K% I% = MOD(10,3) J% = MOD(20,4) K% = MOD(15,4) PRINT "10 / 3 leaves a remainder of";I% PRINT "20 / 4 leaves a remainder of";J% PRINT "15 / 4 leaves a remainder of";K% END

Output Output for the sample program is:


10 / 3 leaves a remainder of 1 20 / 4 leaves a remainder of 0 15 / 4 leaves a remainder of 3

NEXT Statement
Syntax
NEXT index variable

Use

store controller and terminal

Explanation The NEXT statement denotes the end of a FOR/NEXT loop. The NEXT statement sends control to the beginning of the FOR/NEXT loop, until the termination criteria for the loop is met. See FOR Statement on page 76 for more information. Index variable must match the index variable in the corresponding FOR statement. Example Sample Program
! The following example uses the NEXT statement to ! mark the end of two nested FOR/NEXT loops. See ! the FOR statement in this chapter. INTEGER*2 I%,J% FOR I% = 1 TO 3 FOR J% = 5 TO 1 STEP -1

Chapter 7. Statements and Language-Defined Functions

105

NEXT Statement
PRINT "I% = ";I%;"J% = ";J% NEXT J% NEXT I% END

Output Output for the sample program is:


I% I% I% I% I% I% I% I% I% I% I% I% I% I% I% = = = = = = = = = = = = = = = 1 1 1 1 1 2 2 2 2 2 3 3 3 3 3 J% J% J% J% J% J% J% J% J% J% J% J% J% J% J% = = = = = = = = = = = = = = = 5 4 3 2 1 5 4 3 2 1 5 4 3 2 1

ON Statement
Syntax
GOTO ONnumeric expression label GOSUB .. , ..

Use

store controller and terminal

Explanation The numeric expression determines where to transfer the program execution. If the expression evaluates to 1, ON branches to the first label. If the expression evaluates to 2, ON branches to the second label, and so on. If the numeric expression evaluates to a number less than one or greater than the number of labels, control is returned to the first statement following the ON statement. v Numeric expression is any real number or integer expression. Real numbers are converted to integers before evaluation. v Label identifies the statement to which control passes. Label is a statement label, not an expression. Note: The maximum number of labels you can ever specify with this statement is 58. This number may be less than 58, depending on how your program is written. Example Sample Program
! ! ! ! The following example illustrates how the ON statement may be used to alter execution depending on what a user enters. This can be used to create a menu of choices for the user.

INTEGER*2 CHOICE% WHILE CHOICE% <> 3 PRINT "1. read message of the day"

106

IBM 4680 BASIC: Language Reference

ON Statement
PRINT "2. read the golden rule" PRINT "3. quit" PRINT INPUT "enter 1,2 or 3 -> ";CHOICE% PRINT IF CHOICE% < 1 OR CHOICE% > 3 THEN \ PRINT "*** INVALID RESPONSE ***" ON CHOICE% GOSUB MESS,GRULE,DONE WEND MESS: PRINT "the message of the day is:" PRINT "structured programming is a good practice" PRINT RETURN GRULE: PRINT "he who has the GOLD makes the RULES" PRINT RETURN DONE: PRINT "thats all folks" STOP END

Output Output for the sample program depends on what number is entered at the prompt. For example, if a 1 is entered in response to this prompt: 1. read message of the day 2. read the golden rule 3. quit enter 1,2, or 3 -> 1 The output will be:
the message of the day is: structured programming is a good practice

ON ASYNC ERROR CALL Statement


Syntax
ON ASYNC ERROR CALLsubprogram name

Use

store controller and terminal

Explanation The ON ASYNC ERROR CALL statement sends program control to a specified subprogram upon detection of an asynchronous runtime error. Use ON ASYNC ERROR CALL specifically for errors associated with asynchronous I/O operations. Refer to the ON ERROR statement for handling errors associated with synchronous I/O operations. Asynchronous errors are associated with writes to the terminal printer, serial I/O driver, coin dispenser and host communication drivers. Program control reverts to an ON ASYNC ERROR CALL statement when an asynchronous runtime error occurs in a program following the ON ASYNC ERROR CALL statement. You can have multiple ON AYNC
Chapter 7. Statements and Language-Defined Functions

107

ON ASYNC ERROR CALL Statement


ERROR CALL statements in your application. Only one can be in effect at any one time. If your application consists of multiple functions and subprograms, each of these can contain its own ON ASYNC ERROR CALL subprogram. When a function or subprogram is entered and an ON ASYNC ERROR CALL statement is executed, the runtime library remembers the previous ON ASYNC ERROR CALL subprogram that was in effect. When the function or subprogram is exited, the runtime library restores the ON ASYNC ERROR CALL subprogram to the label it had prior to entering the procedure. Subprogram name identifies the subprogram designed to handle the asynchronous error. Note: The subprogram definition must be in the same module as the ON ASYNC ERROR CALL statement (it must not be defined as an external routine). Subprograms and functions cannot be nested. The subprogram specified on this statement must be previously defined. The subprogram must have the following format:
SUB SUBPROGRAM NAME (retryflag,overlaystr) INTEGER*2 retryflag STRING overlaystr ! ! PROCESS ERROR AND SET PARAMETERS APPROPRIATELY ! EXIT SUB ! ! END SUB

v retryflag specifies if the failing I/O operation is to be attempted again or not. A value of 0 for retry flag informs the runtime library not to retry the operation. A value of -1 indicates the operation is to be retried. v overlaystr specifies if any data are to overlay part of the failing print line. Also specified is the offset where these characters are to be printed. If you do not want to overlay part of the print line, or if the failing I/O is not associated with the printer, this variable must be a null string. The format of the string data for this variable (if not null) is: 2 bytes indicating the offset to use followed by The overlay string (1 - 38 characters). v This subprogram must have its own ON ERROR GOTO statement to handle any errors associated with any statements in this subprogram. It also must have its own IF END # statements if the mainline program has any IF END # statements and the subprogram uses any of these files. This is because when this subprogram executes, the mainline program is suspended, and therefore this subprogram cannot share the mainline programs ON ERROR routine or any IF END # routines. Notes: 1. There are no parameters coded on the ON ASYNC ERROR CALL subprogram statement. There are two parameters on the subprogram definition. This is because the runtime library, not your application, actually calls the subprogram. The ON ASYNC ERROR CALL statement simply identifies the subprogram that should get control if an error associated with an asynchronous event occurs. 2. Do not issue a TCLOSE in your subprogram. This would cause a deadlock situation to occur and your application would never resume executing. 3. Do not issue an asynchronous write operation in your subprogram.

108

IBM 4680 BASIC: Language Reference

ON ASYNC ERROR CALL Statement


4. All open I/O sessions in your main program can be used by your subprogram by using the same I/O session number. 5. On a coin dispenser ASYNC I/O error, the RETRYFLAG is ignored and the failing statement will NOT be retried (it will work as a RESUME). 6. Do not close an I/O session in your subprogram for which you issue a WAIT in your mainline program. 7. If a global variable is accessed or changed as part of an ON ASYNC ERROR CALL subprogram, the global in the mainline application program must be bracketed by a DISABLE/ENABLE instruction pair. This way, the ON ASYNC ERROR CALL subprogram can not unexpectedly change the global. Example Sample Program
%environ t integer countr,maximum,condition ** ON ASYNC ERROR SUBROUTINE *** sub asyncsub(rflag,over) integer*2 rflag ! Retry flag string over ! Overlay string on error goto serror ! Handle synchronous I/O errors countr = countr + 1 ! Increment retry counter rflag = -1 ! Retry print line over = "00**" ! Overstrike first two print positions ! with asterisks if countr > maximum then \ ! Make sure we can exit if hard begin ! Failure rflag = 0 ! Do not retry print line over = "" ! No overlay characters countr = countr - 1 ! Reset to correct count endif clears 4 ! Clear the display and indicate ! Error to operator if err = "DO" then \ ! If device is offline begin ! if errn eq 80900525h then \! If it is a paper path error begin write #4; "OUT OF JOURNAL PAPER" . ! . ! Wait for operator to correct . ! Problem and let application . ! Know endif \ endif \ else \ begin . . . . endif exit sub ! serror: . . . end sub ** MAIN PROGRAM *** on error goto errora ! Set up normal synchronous error handler
Chapter 7. Statements and Language-Defined Functions

! Synchronous error rtn for errors ! which occur during the asynchronous ! error subroutine

109

ON ASYNC ERROR CALL Statement


on async error call asyncsub ! Set up asynchronous error handler open "ANDISPLAY:" as 4 ! Open devices open "CR:" as 1 open "SJ:" as 2 clears 4 ! Clear the display condition = -1 ! Set condition true . . . . while (condition) ! Loop as long as condition is true . . . . i%=disable ! Turn off software interrupts countr = 0 ! Reset retry count i%=enable ! Turn on software interrupts . . write form "c38,a1"; #1; crmsgl$ ! Write to customer receipt write form :c38,a1"; #2; sjmsgl$ ! Write to summary journal . . . . wend stop errora: . . . . end

ON ERROR Statement
Syntax
ON ERRORGOTOlabel

Use

store controller and terminal

Explanation The ON ERROR statement sends program control to the specified label upon detection of a synchronous runtime error. Treat this as a subroutine and refer to the ON ASYNC ERROR CALL statement for handling errors associated with asynchronous I/O. Refer to the IBM 4680 Store System: Programming Guide or the IBM 4690 Store System: Programming Guide for additional information on using error recovery procedures. Note: You must recover from an ON ERROR statement with a RESUME for each entry to the ON ERROR statement to avoid a dump or hang. Program control reverts to an ON ERROR statement when a synchronous runtime error occurs in a program following the ON ERROR statement. If you use more than one ON ERROR statement in a program, the last one to execute remains in effect, with the following exception. If you reset the current ON ERROR label in a function or subprogram (by issuing a new ON ERROR label), the runtime subroutine library automatically resets the

110

IBM 4680 BASIC: Language Reference

ON ERROR Statement
label (to the value it had prior to entering the function or subprogram) when you exit the function or subprogram. label identifies a statement to which control passes. An IF END statement overrides an ON ERROR statement. See Appendix B, Runtime Error Messages for additional information on runtime error handling. Notes: 1. A program terminates if a runtime error occurs with no ON ERROR statement in effect. 2. Every time an ON ERROR routine is entered, important runtime subroutine library state data is saved. Therefore, it is imperative that a RESUME statement be issued for each entry into the ON ERROR routine. For example, the following error handling sequence is not correct and produces unpredictable results: a. A WRITE # statement is issued in the mainline code and an error is returned. b. In the ON ERROR routine, another error occurs and the application issues a RESUME label statement. The label is back in the mainline (not in the ON ERROR routine) code. In the example above, the ON ERROR routine was entered twice, but only exited once (using the RESUME label). To ensure proper error handling, you may want to increment a counter every time your ON ERROR routine is entered and decrement it before a RESUME or RESUME RETRY statement is executed. The value should be decremented and tested (to be equal to zero) before issuing a RESUME label statement that will direct program execution outside the ON ERROR routine. If the counter has a value greater than zero, you can issue a RESUME label to within the ON ERROR routine, perform the decrement, and test again. Example Sample Program
! ! ! ! ! The following example uses the ON ERROR statement as well as all of the error functions to obtain a complete picture of an I/O error. Notice the conversion routine used to obtain the hex digits from the ERRN function.

! NOTE: must be compiled with the N option for ! ERRL to return a line number. 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% = ERRN ERRFX$ = "" FOR S% = 28 TO 0 STEP -4
Chapter 7. Statements and Language-Defined Functions

111

ON ERROR Statement
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 = 15 ERRN = 80204010

OPEN Statement
Syntax
================================= OPENname ========= KEYEDRECL record length DIRECT ========BUFF 1========== ASI/O session number BUFF number of buffers ====BUFFSIZE 128===== =UNLOCKED= LOCKED BUFFSIZE buffersize READONLY ========== =========== ========= NOREAD NOWRITE NODEL ========== ======== PRIORITY APPEND

Use

store controller and terminal

Explanation The OPEN statement opens disk files, pipes, and other input/output (I/O) devices for subsequent I/O requests. See Chapter 8, Using Input and Output Devices and Pipes for a list of supported devices and other special reserved file/pipe names and services. v Name is any valid file, pipe, or device name. See Name Specification on page 34 for a complete description. v The KEYED flag indicates the file is a keyed file. v The DIRECT flag indicates the file is the direct type of random access file.

112

IBM 4680 BASIC: Language Reference

OPEN Statement
v RECL specifies a record length for a random, keyed, or direct file. The record length value you specify for RECL is a numeric expression. A record length specification is required for random, keyed, and direct files. When you do not specify KEYED or DIRECT, but do specify the RECL parameter, you open a random file. If you omit RECL, you open a sequential file. v I/O session number is a unique identification number you assign to a file, a pipe, or a device. It can be any numeric expression that evaluates to a 2-byte integer ranging from 1 to 99. v BUFF specifies a numeric value used to determine the size of the I/O buffer. The BUFF value multiplied by 128 determines the size of the buffer in number of bytes. For pipes, the BUFF value times 128 determines the size of the pipe. Unless you are opening the I/O processor and you specify BUFFSIZE, BUFF is ignored. In the store controller, the BUFF parameter assigns additional runtime library buffers for increased sequential file throughput. The runtime library will buffer data when writing to a sequential file only when it is opened in a LOCKED mode. The default value is BUFF 1. A BUFF value greater than one is ignored for random, direct, or keyed files. v BUFFSIZE specifies a numeric value representing the size of the I/O buffer in number of bytes. This is more flexible than the BUFF parameter, which represents only multiples of 128 bytes. If you specify BUFFSIZE, the BUFF parameter is ignored. BUFFSIZE is ignored for pipes. The default buffer size is device dependent. Refer to Writing a File Record in the IBM 4680 Store System: Programming Guide or the IBM 4690 Store System: Programming Guide for more information on this parameter. v LOCKED requests exclusive access to the files. v UNLOCKED specifies that other processes be granted both read and write privileges. The default mode is UNLOCKED. v READONLY requests that other processes be allowed to read from but not write to the file. v NOREAD specifies that read privileges are not being requested. You must not specify NOREAD for a keyed file. v NOWRITE specifies that write privileges are not being requested. v NODEL specifies that delete privileges are not being requested. (This does not prevent your program from deleting the file if it has delete access rights. It does allow your program to open a file if you do not have delete access rights.) v PRIORITY is a flag specifying that disk accesses for this file have priority over other pending disk requests. The PRIORITY flag is valid only in the terminal. v APPEND is a flag that causes sequential files to be opened in append mode. The file is repositioned to the end-of-file, so that all data is written to the file after any existing data. You must open a sequential file with the APPEND reserved word if you are going to write to that file. Failure to specify APPEND causes the runtime library to generate an error (ERR=XD) when a write to that file is executed. Using BUFF and BUFFSIZE for the I/O processor driver enables you to specify multiple input buffers (BUFF) and the size of each buffer (BUFFSIZE). This allows an operator to key ahead, and still have the I/O processor perform appropriate error checking of the input.
Chapter 7. Statements and Language-Defined Functions

113

OPEN Statement
If BUFF is zero and BUFFSIZE is either absent or zero and the I/O session is a disk file, no buffering across records occurs when reading and writing to the file. This has the effect of forcing a physical write on every WRITE # statement, and a physical read on every READ statement. Disabling the buffering of multiple records is required, if the HOLD flag on the WRITE # statement is to work properly for sequential files. See WRITE # Statement on page 164 for more information. LOCKED, UNLOCKED, and READONLY have meaning only for disk files. They specify if and how the file is to be shared with other processes until the process that opened the file closes the file. UNLOCKED allows read and write access only to those users with read and write privileges to this file. READONLY disallows writes to the file even from processes that have write privileges. It does not grant temporary read privileges to processes that usually do not have them. LOCKED assures exclusive use of the file until closed, even though the file is open to world users. However, if you specify NOWRITE and NODEL with the LOCKED option, other processes can open the file READONLY. By default, read, write, and delete privileges for the process are requested. If the program cannot be granted this access, because access is disallowed by the file attributes, or because another process has opened the file within a LOCKED or READONLY shared mode, the OPEN fails. You can reduce the level of requested access with the NOREAD, NOWRITE, and NODEL reserved words. These reserved words can be used to prevent OPEN failures when full access rights are not required. Example Sample Program
! ! ! ! The following example uses the OPEN statement to open a file and read records from it. See the CREATE statement in this chapter for more information.

INTEGER*2 C% REAL D STRING A$,B$ PRINT CREATE "TESTFILE.TMP" RECL 25 AS 10 PRINT "creating new file called TESTFILE.TMP" A$ = "field one" B$ = "field two" C% = 321 D = 4.5 WRITE #10,1;A$,B$ WRITE #10,2;C%,D PRINT "writing two records to file" CLOSE 10 PRINT "closing file" PRINT OPEN "TESTFILE.TMP" RECL 25 AS 5 PRINT "opening the new file" READ #5,1;A$,B$ READ #5,2;C%,D PRINT "reading two records from the file" PRINT "first record is :";A$;B$ PRINT "second record is:";C%;D CLOSE 5 PRINT "closing file" PRINT "thats all folks" END

114

IBM 4680 BASIC: Language Reference

OPEN Statement
Output Output for the sample program is:
creating new file called TESTFILE.TMP writing two records to file closing file opening the new file reading two records from the file first record is: field one field two second record is: 321 4.5 closing file thats all folks

OPEN LINK Statement


Syntax
SNA OPEN LINKBSClink configuration record id ASYNC ======================= ,tele.no AS ,tele.no,host ,,host link numberBUFFSIZE buffersize

Use

store controller only

Explanation The OPEN LINK statement opens a host communications link. Once a link is opened, host communication sessions can be created on that link. See OPEN SESSION Statement on page 117 for more information. v SNA specifies System Network Architecture communication. v BSC specifies Binary Synchronous Communication. v ASYNC specifies Asynchronous Communication. v link configuration record id is a string that identifies the link configuration data to use on this OPEN. It is any valid name defined in the system configuration process. v tele.no is a string defining the telephone number for an auto-dial network. Tele.no overrides the telephone number specified in the system configuration process. See the IBM 4680 Store System: Programming Guide and the IBM 4680 Store System: Planning and Configuration Guide or the IBM 4690 Store System: Programming Guide and the IBM 4690 Store System: Planning, Installation, and Configuration Guide for more information. (tele.no is valid only for ASYNC communications.) v host is a string defining the ID of the host processor to be dialed. Host overrides the Host ID specified in the system configuration process. See the IBM 4680 Store System: Programming Guide or the IBM 4690 Store System: Programming Guide for more information. It is valid only for SNA and BSC communications. v link number can be any numeric expression that evaluates to a 2-byte integer ranging from 1 to 99. v BUFFSIZE buffer size is numeric and is valid only for ASYNC. It is a required parameter and must be in the range of 1 to 518.

Chapter 7. Statements and Language-Defined Functions

115

OPEN LINK Statement


See Chapter 8, Using Input and Output Devices and Pipes for examples of the OPEN LINK statement. Example The following program fragment uses the OPEN LINK statement to open a link for SNA host communications. The example also opens a communications session named data.ses on the open SNA link.
! STRING bind3, data BINDVAR bind3 AS 33

OPEN LINK SNA data AS 32 OPEN SESSION "data.ses" ON 32 . . CLOSE 33 CLOSE 32 END

OPEN SERIAL Statement


Syntax
==300== =="E"=== OPEN SERIALn, , , speed parity ====7=== ====1=== , ASI/O session number data stop ====BUFFSIZE 128======= BUFFSIZE buffersize

Use

terminal only

Explanation The OPEN SERIAL statement opens a SERIAL I/O driver session. You should use this version of the OPEN statement to open I/O sessions on the SERIAL I/O device because you must specify several pieces of information for this device at open time that are not required to open other devices or files. v n is numeric and specifies which of four serial ports to open. It must be in the range 1 to 4. The value specified for n converts automatically to a 2-byte integer if necessary. v Speed is a numeric value that specifies the transmit/receive bit rate in bits per second (bps). Allowed values are 110, 300, 1200, 2400, 4800, and 9600. The default value is 300. v Parity is a string with a leftmost character that specifies parity for transmit/receive. The meaningful values are E (for even), O (for odd), and N (for none). The default is E. v Data is a numeric indicating the number of transmit/receive data bits. The range of meaningful values is 5 to 8. The default is 7. v Stop is a numeric indicating the number of stop bits. The only meaningful values are 1 and 2. If data is 5, a value of 2 for stop indicates 1.5 stop bits. The default value is 1 unless speed is 110, in which case the default is 2.

116

IBM 4680 BASIC: Language Reference

OPEN SERIAL Statement


v I/O session number is a unique number assigned to the Serial I/O session. It can be any numeric expression that evaluates to a 2-byte integer ranging from 1 to 99. v BUFFSIZE specifies the size of the I/O buffer in number of bytes. The maximum size is 247 bytes. Example The following program fragment opens serial port 1 at 1200 bps, even parity checking, five data bits per byte, one stop bit per byte and a buffer size is 247 bytes.
! OPEN SERIAL 1, 1200, "E", 5, AS 12 BUFFSIZE 247 . . CLOSE 12 END \

OPEN SESSION Statement


Syntax
OPEN SESSIONsession nameONlink number BINDVAR bindvar$ASI/O session number

Use

store controller only

Explanation The OPEN SESSION statement opens a host communication session. This is a special variation of the OPEN statement that opens a host communication session on the specified link. It is valid only for a session opened on an SNA link. v Session name is a string variable or constant that names the session. v Link number is numeric and defines the number of a previously opened link where the session is to be bound. v BINDVAR specifies a string variable that serves as the destination for bind information returned on completion of the OPEN SESSION operation. If BINDVAR is a null string the open is completed as soon as all control blocks are allocated. Issuing a read to the session then obtains the BIND request sent from the host processor. Use this method if you do not want an INIT-SELF command sent to the host processor if the host processor has not yet issued a BIND request. v I/O session number is a unique number assigned to the host communication session. It can be any numeric expression that evaluates to a 2-byte integer ranging from 1 to 99. See Chapter 8, Using Input and Output Devices and Pipes and either the IBM 4680 Store System: Programming Guide, or the IBM 4690 Store System: Programming Guide for more specific information on the OPEN SESSION statement. Example The following program fragment uses the OPEN SESSION statement to open a communications session named data.ses on an open SNA link named data.
! STRING bind3, data
Chapter 7. Statements and Language-Defined Functions

117

OPEN SESSION Statement


OPEN LINK SNA data AS 32 OPEN SESSION "data.ses" ON 32 . . CLOSE 33 CLOSE 32 END

bindvar bind3 AS 33

OPTION Statement
Syntax
========DECIMAL"."============ OPTION DECIMALnumeric separator =========CURRENCY"$"========= CURRENCYcurrency symbol

Use

store controller and terminal

Explanation The OPTION statement specifies alternate punctuation characters to use when processing numeric fields. Use OPTION with the appropriate editing symbols specified in the format string referenced by a WRITE or PRINT statement. v DECIMAL specifies a string expression that determines the numeric separators to be used in numeric values. The first character in the string determines which characters are used as the decimal point and the thousands separator. If the first character is a period, or if you omit the DECIMAL parameter entirely, the period is used as the decimal point, and the comma is used as the thousands separator. If the first character is a comma, the comma is used as the decimal point, and the period is used as the thousands separator. The separators are output when appropriate editing symbols are specified in a format string for WRITE FORM or PRINT USING statements. If the first character of the string is not a comma or period, a runtime error results. v CURRENCY specifies the currency symbol used in numeric values representing monetary quantities. You can use any character as a currency symbol. The symbol is output when you use the floating currency symbol specifier in a format string for WRITE FORM or PRINT USING statements. Example Sample Program
! ! ! ! ! ! In the following example, the OPTION statement specifies a numeric separator consisting of a variable to which the value "," has been assigned, and a currency symbol consisting of a variable to which the value "#" has been assigned.

%ENVIRON T REAL AMT.DUE STRING NUM.SEP$,CURR.SYM$ NUM.SEP$ = "," CUR.SYM$ = "#" AMT.DUE = 5.6E3 OPTION DECIMAL NUM.SEP$ CURRENCY CUR.SYM$

118

IBM 4680 BASIC: Language Reference

OPTION Statement
OPEN "VDISPLAY:" AS 1 WRITE FORM "/AMOUNT DUE = / PIC($$#,###.##)"; \ #1; AMT.DUE END

Output In the preceding example, the WRITE FORM statement sends the following output to the display:
AMOUNT DUE = #5.600,00

PACK$ Function
Syntax
a$ = PACK$(string)

Use

store controller and terminal

Explanation The PACK$ function returns the packed binary coded decimal (BCD) representation of the string. String is any string value. PACK$ strips off the four most significant bits of each character, and then packs the resulting low-order 4 bits, two per byte. The 4 bits in the returned string are packed high-order first. If string contains an even number of characters, then the first character of string is mapped into the high-order 4 bits of the first byte of the returned string. If string contains an odd number of characters, then the odd nibble is mapped into the low-order nibble of the first byte (the high-order nibble is set to F). You can use PACK$ to pack strings of ASCII numerals before disk file storage to save space. PACK$ does not check the contents of string for valid ASCII decimal numerals (30h to 39h). Therefore, you can pack any characters. However, only characters with the ASCII values of 30 to 3E (0, 1, ... 9, :, ;, <, =, >) can be reconstructed using the UNPACK$ function. See the UNPACK$ function later in this chapter. Example Sample Program
! ! ! ! The following example uses the PACK$ function to pack the digits in BCD form and then uses UNPACK$ to restore them to the original form. See the UNPACK$ statement in this chapter.

INTEGER*2 I% STRING A$,B$,C$ I% = 12345 A$ = STR$(I%) B$ = PACK$(A$) C$ = UNPACK$(B$) PRINT "first we have an INTEGER value of";I% PRINT "when converted to a STRING it looks like ";A$ PRINT "after using PACK$ it looks like ";B$ PRINT "after using UNPACK$ it looks like ";C$ END

Output Output for the sample program is:


Chapter 7. Statements and Language-Defined Functions

119

PACK$ Function
first we have an INTEGER value of 12345 when converted to a STRING it looks like 12345 after using PACK$ it looks like #E after using UNPACK$ it looks like 12345

PEEK Function
Syntax
i% = PEEK(numeric expression)

Use

store controller only

Explanation The PEEK function returns the contents of a specified memory address. PEEK accepts only 4-byte integer values representing 32-bit addresses. Using input values obtained from SADD or VARPTR protects against any attempt to read a memory protected address. The value that PEEK returns is a byte embedded in a 16-bit integer. Using PEEK on an address that is not owned by the process causes a processor exception. v i% is an integer returned by the PEEK function. v Numeric expression is any real number or integer expression. Example Sample Program
! In the following example, the PEEK statement is used to ! read each byte of string DATA$. See SADD Function ! for information on the use of SADD. INTEGER*4 INDEX%, LOC% STRING DATA$ DATA$ = "test data" LOC% = SADD(DATA$) ! SADD returns the address of the ! length field of the string; add ! 2 to get the address of the data.

LOC% = LOC% + 2 FOR INDEX% = 0 to 8 PRINT CHR$(PEEK(LOC% + INDEX%)) NEXT INDEX% END

Output Output for the sample program is:


t e s t d a t a

POINT Statement
Syntax
POINTI/O session number;offset

Use

store controller and terminal

120

IBM 4680 BASIC: Language Reference

POINT Statement
Explanation The POINT statement positions a sequential disk file pointer so that the next READ operation is performed at the necessary place in the file opened under the specified I/O session number. v I/O session number is a unique identification number you assign to a file with the CREATE or OPEN statement. v Offset is a 4-byte integer variable that is often assigned a value with the PTRRTN function. The POINT statement may also be used to set the size of a disk file to zero. This can be accomplished only if the following conditions are true: v The file has been opened in LOCKED or READONLY mode. v The file has been opened without specifying NOWRITE. v The value specified for offset is 80000000H. If any other negative value is specified, the value is changed to zero, and the size of the file is unchanged. POINT is not valid for a file that is open UNLOCKED (shared), unless you specify the NOWRITE reserved word in the OPEN statement. If this condition is not met, you receive a runtime error. For disk files, a write operation cannot follow a POINT. POINT is also valid for the totals retention driver in the terminal. The offset value you specify is for the next sequential READ or WRITE that occurs. Example Sample Program
! ! ! ! ! ! ! ! The following example uses the POINT statement to position a sequential disk file pointer for subsequent read operations. We write two records to the file. The PTRRTN function returns the offset of the second record. The POINT statement repositions the file pointer according to the offset returned by PTRRTN, so the second record can be read.

INTEGER*4 OFFSET% STRING A$,B$,C$ CREATE "FILE.POS" AS 19 LOCKED A$ = "A" B$ = "B" WRITE #19; A$ WRITE #19; B$ OFFSET% = PTRRTN PRINT "PTRRTN RETURNS OFFSET = ";OFFSET% CLOSE 19 OPEN "FILE.POS" AS 10 NOWRITE POINT 10; OFFSET% PRINT "POINT RETURNS OFFSET = ";OFFSET% READ # 10; C$ PRINT "THE SECOND RECORD IS = ";C$ CLOSE 10 END

Output Output for the sample program is:

Chapter 7. Statements and Language-Defined Functions

121

POINT Statement
PTRRTN RETURNS OFFSET = 5 POINT RETURNS OFFSET = 5 THE SECOND RECORD IS = B

POKE Statement
Syntax
POKEnumeric expression,numeric expression

Use

store controller only

Explanation The POKE statement stores one byte of data into memory at a specified address. Using input values obtained from SADD or VARPTR protects against attempting to write a memory protected address, which causes the operating system to end the program. Address values other than return values from SADD and VARPTR, generally yield unpredictable results. The input data argument is a byte embedded in a 2-byte integer. Using POKE on an address that is not owned by the process causes a processor exception. v The first numeric expression is the address argument, a 4-byte integer representing 32 bits of address. v The second numeric expression is the input data argument. Example Sample Program
! In the following example, the POKE statement ! is used to change the first byte of string MSG$ ! from f to m. See SADD Function on page 146! for information on the use of SADD. INTEGER*4 MSG.LOC% STRING MSG$ MSG$ = "fiddle" PRINT MSG$ MSG.LOC% = SADD(MSG$) MSG.LOC% = MSG.LOC% + 2 POKE MSG.LOC%, ASC("m") PRINT MSG$ END

! SADD returns the address of the ! length field of the string. Add ! 2 to get the address of the data. ! Replace f with m.

Output Output for the sample program is:


fiddle middle

POS Function
Syntax
i2% = POS

Use

store controller only

Explanation POS returns the position of the next output column for either the console or the printer, depending on which output mode is in effect.

122

IBM 4680 BASIC: Language Reference

POS Function
i2% is a 2-byte integer returned by the POS function. POS first determines the number of characters and spaces output to the console or the printer since the last carriage return, and then returns that total plus one indicating the next column available for output. Note: POS returns inaccurate values if you output cursor control characters or backspace characters. Example Sample Program
! The following example uses the POS function to ! determine the next output column for both the ! screen and the printer. ! IMPORTANT: make sure printer is on and ready ! before executing this program. INTEGER*2 I2% LPRINTER PRINT "PRINTER OUTPUT TEST" PRINT "the print head is at column ";POS CONSOLE PRINT "CONSOLE OUTPUT TEST" I2% = POS PRINT "the next output column is ";I2% END

Output Output for the sample program appears on both the screen and the printer.
PRINTER OUTPUT -------------PRINTER OUTPUT TEST the print head is at column SCREEN OUTPUT ------------CONSOLE OUTPUT TEST the next output column is 1 29

PRINT Statement
Syntax
================= PRINT expression ...delimiter...

Use

store controller only

Explanation The PRINT statement sends data to the display, or to the printer if the LPRINTER statement is in effect. Expression contains the data to be output. You can use any number of expressions with the PRINT statement. v Expression is the data to be output. v Delimiter is either a comma or a semicolon.

Chapter 7. Statements and Language-Defined Functions

123

PRINT Statement
The comma tabs to the next column that is a multiple of 20 before printing the next expression. The semicolon allows expressions to print continuously on a line with no spaces in between. Numeric expressions that are output are always separated by one space. The reserved word, PRINT, with no expression list, sends a carriage return/line-feed pair to the printer. The PRINT statement sends a carriage return/line-feed to the printer after each execution unless a comma or semicolon follows the last expression. See Chapter 8, Using Input and Output Devices and Pipes for more information on data output. See Appendix F, Character Sets For Terminal Printers, Displays, and Controller Video Display for escape sequences for the display and extended codes for keyboard input for the store controller. Example Sample Program
! ! ! ! ! The following example uses the PRINT statement to demonstrate the difference between using commas and semicolons to separate items in the print list. Also notice that the PRINT statement with no list is used to print a blank line.

INTEGER*2 I% REAL J STRING K$ I% = 10 J = 25.77 K$ = "TESTSTRING" PRINT "first we will use the PRINT statement" PRINT "with a list separated by commas" PRINT PRINT I%,J,K$,K$ PRINT PRINT "now we will use the PRINT statement" PRINT "with a list separated by semicolons" PRINT PRINT I%;J;K$;K$ PRINT PRINT "end of demonstration" END

Output Output for the sample program appears in the columns indicated:
column 10 1 10 1 25.77 20 TESTSTRING 40 TESTSTRING 60

column

25.77 TESTSTRINGTESTSTRING 5 11

PRINT USING Statement


Syntax

124

IBM 4680 BASIC: Language Reference

PRINT USING Statement


PRINT USINGformat string;expression .... , ..... PRINT USINGformat string;#I/O session number ==================== ;expression ,record number .... , .....

Use

store controller only

Explanation The PRINT USING statement allows you to specify special formats for output data. The PRINT USING # variation directs formatted output to a random or sequential disk file. Each PRINT USING statement prints one complete screen line. Each PRINT USING # prints one file record. v The format string is a model for the output. The format string must be a string constant or a string variable. It cannot be a null string or expression. A format string contains format items (specifications) and literal data. Table 11 describes characters that have special meaning in format strings. v Expressions in the expression list hold the data to be formatted. Separate each expression with a comma. The comma does not cause automatic tabbing as it does with unformatted printing. v I/O session number is a unique identification number you assign to the I/O device with the CREATE or OPEN statement. v Record number is the number of the record in a random file that the data is printed to.
Table 11. Special Characters in Format Strings Character ! & / # ** $$ . ^ , \ Meaning single-character string field variable-length string field fixed-length string field delimiter digit position in numeric field asterisks fill in numeric field float currency symbol in numeric field decimal point position in numeric field leading or trailing sign in numeric field exponential position in numeric field place thousands separator every third digit before decimal point symbol escape character

PRINT USING matches each expression in the list with a data field in the format string. If there are more expressions than there are fields in the format string, the format string is reused from the beginning of the string. The type of the next expression in the list, either string or numeric, determines which format item to use next from the format string. IBM 4680 BASIC rounds (half adjusts) all real constants to 18 digits of precision and maintains only 18 digits internally.
Chapter 7. Statements and Language-Defined Functions

125

PRINT USING Statement


You can use the CURRENCY and DECIMAL reserved words in the OPTION statement to change the symbols used for monetary values, thousands separation, and the decimal point. See OPTION Statement on page 118 for more information. See Formatted Printing on page 179 for additional information on PRINT USING. Example Sample Program
! ! ! ! ! ! The following example, using the PRINT USING statement, allows you to specify special formats for data output to disk file. We create and write data to a random file. Then we read and print the data in the file. The READ LINE brings in the whole record, then you must parse.

REAL A,B STRING FORMAT$,AMOUNT$ CREATE "FILE.DAT" RECL 25 AS 11 A = 7333.54 B = 6125.00 FORMAT$ = "$$#,###.##" PRINT USING FORMAT$; #11,1; A,B PRINT "FILE IS CREATED" READ #11,1; LINE AMOUNT$ PRINT "RECORD 1 = ";AMOUNT$ CLOSE 11 END

Output Output for the sample program is:


FILE IS CREATED RECORD 1 = $7,333.54 $6,125.00

PRINT # Statement
Syntax
================== PRINT#I/O session number ;expression ,record number ... , ......

Use

store controller only

Explanation The PRINT # statement sends data to random files, sequential files, and pipes. PRINT # writes the data specified in an expression to the file specified by I/O session number. See WRITE # Statement on page 164 for more information (WRITE # is the preferred statement for accessing files). Each PRINT # statement creates a single record. v I/O session number is a unique identification number you assign to a file with the CREATE or OPEN statement. v Use record number for random files. Record numbers start with one, not zero. v Each expression used in the PRINT # statement creates a single field within the record. Use any number of expressions with the PRINT # statement and separate each with a comma.

126

IBM 4680 BASIC: Language Reference

PRINT # Statement
The amount of data written to a random file must not exceed the record length specified in the RECL argument in the CREATE or OPEN statement. You must add two bytes for the carriage return/line-feed when determining the amount of data you can print to a record. Strings are embedded inside quotation marks, and fields are delimited by commas when printing to a file. Numeric values are converted to ASCII form. Example Sample Program
! The following example uses the PRINT # statement ! to write three character strings to a sequential file. ! Then it reads them with the READ # statement. STRING A$,B$,C$,FIELD1$,FIELD2$,FIELD3$ A$ = "a" B$ = "b" C$ = "c" CREATE "FILE.DAT" AS 15 PRINT "file.dat has been created" PRINT # 15; A$,B$,C$ CLOSE 15 OPEN "FILE.DAT" AS 16 READ # 16; FIELD1$,FIELD2$,FIELD3$ PRINT "file.dat contains:" PRINT FIELD1$ PRINT FIELD2$ PRINT FIELD3$ CLOSE 16 END

Output Output for the sample program is:


file.dat has been created file.dat contains: a b c

PTRRTN Function
Syntax
i4 = PTRRTN

Use

store controller and terminal

Explanation The PTRRTN function returns a 4-byte integer containing the current offset value in a sequential file or in the totals retention driver (TOTRET:). This offset value corresponds to the last record that you read or wrote to the last accessed sequential file (or the Totals Retention Area). This value may be specified as the offset value for the POINT statement. i4 is a 4-byte integer returned by the PTRRTN function. Read and write operations for a sequential file update the internal value of PTRRTN. If you want to save a particular value, you must assign it to a variable immediately after the READ or WRITE # statement.

Chapter 7. Statements and Language-Defined Functions

127

PTRRTN Function
PTRRTN is not valid for a disk file that is opened in UNLOCKED mode, unless the file is opened with the NOWRITE reserved word specified. If the file does not meet this condition, a runtime error occurs (ERR=XM). Example Sample Program
! ! ! ! ! ! The following example uses the PTRRTN statement to return an offset value in a sequential file indicating where the last READ or WRITE operation occurred. We write two records to the file. The PTRRTN function returns the offset of the second record. The POINT statement repositions the file pointer according to the offset returned by PTRRTN, so the second record can be read.

INTEGER*4 OFFSET% STRING A$,B$,C$ CREATE "FILE.POS" AS 19 LOCKED A$ = "A" B$ = "B" WRITE #19; A$ WRITE #19; B$ OFFSET% = PTRRTN PRINT "PTRRTN RETURNS OFFSET = ";OFFSET% CLOSE 19 OPEN "FILE.POS" AS 10 NOWRITE POINT 10; OFFSET% PRINT "POINT RETURNS OFFSET = ";OFFSET% READ # 10; C$ PRINT "THE SECOND RECORD IS = ";C$ CLOSE 10 END

Output Output for the sample program is:


PTRRTN RETURNS OFFSET = 5 POINT RETURNS OFFSET = 5 THE SECOND RECORD IS = B

PUT Statement
Syntax
PUTI/O session number,data

Use

store controller only

Explanation The PUT statement sends one byte of data to the specified I/O session number. Each execution of the PUT statement writes the binary data for one byte to the file. v I/O session number is a unique identification number you assign to a file with the CREATE or OPEN statement. v Data is the 1-byte value to be output. Data can be any value between 0 and 255. Real expressions convert to integers. PUT is valid only for disk files and pipes. Example Sample Program

128

IBM 4680 BASIC: Language Reference

PUT Statement
! ! ! ! ! ! ! ! ! The following example uses PUT to put a byte from an existing file into a new file called UPPERCSE.TXT. The example uses GET to sequentially retrieve every byte from an existing text file named LOWERCSE.TXT. If the byte corresponds to a lowercase ASCII character, it is replaced by the corresponding uppercase ASCII character. If the byte is not a lowercase ASCII character, it is not changed. \

REM Translate a lowercase text file into an uppercase text file INTEGER*2 I% OPEN "LOWERCSE.TXT" AS 1 CREATE "UPPERCSE.TXT" AS 2 IF END # 1 THEN DONE WHILE 1 I% = GET(1) IF I% >= 97 AND I% <=122 THEN I% = I% - 32 PUT 2, I% WEND STOP DONE: PRINT "TRANSLATION IS COMPLETE." CLOSE 1 CLOSE 2 END

Output Output for the sample program is:


TRANSLATION IS COMPLETE.

PUTLONG Statement
Syntax
PUTLONGI/O session number,data

Use

store controller and terminal

Explanation The PUTLONG statement writes data to a specified I/O session. v I/O session number is the number assigned to the I/O device in the OPEN statement. v Data is the 4-byte integer containing information specific to an I/O device. See Terminal Input/Output Device Drivers on page 198 for the definition of data for each I/O device. Example Sample Program
! ! ! ! ! In the following example, the PUTLONG statement sends a 4-byte integer that contains symbolized requests to the asynchronous communications driver. The asynchronous link is identified with the I/0 session number 53.

INTEGER*4 REQUEST% . . OPEN LINK ASYNC "ASYNCLIN.DAT" AS 53

Chapter 7. Statements and Language-Defined Functions

129

PUTLONG Statement
PUTLONG 53, REQUEST% . . END

RANDOMIZE Statement
Syntax
RANDOMIZE

Use

store controller only

Explanation The RANDOMIZE statement seeds the random number generator for use with the RND function. RANDOMIZE uses the operating system time-of-day function to provide an arbitrary seed value. See RND Function on page 144 for more information. Example Sample Program
! ! ! ! ! ! In the following example, the RANDOMIZE statement seeds the random number generator to avoid an easily repetitious sequence of numbers. The RND function returns a uniformly distributed random real number between 0 and 1. Your output will vary due to randomization.

INTEGER*2 I% RANDOMIZE FOR I% = 1 TO 5 PRINT RND NEXT I% END

Output Output for the sample program is:


.6950087256129059 .04454464856724359 .2584800862255069 .5438035116766581 .8745303432448281

READ Statement
Syntax
READvariable .. , .....

Use

store controller and terminal

Explanation The READ statement sequentially assigns the constants in a DATA statement to variables. Variables data type must match corresponding data constants. IBM 4680 BASIC maintains a pointer to keep track of the next constant in the DATA statement constant list. Each time a READ statement executes, READ assigns a constant in the DATA statement to the next variable in the

130

IBM 4680 BASIC: Language Reference

READ Statement
READ statement. Then, READ sets the pointer to the next constant in the DATA statement. A runtime error occurs if the READ statement attempts to read past the last constant. READ statements must assign each constant to a variable with a matching data type. If data types do not correspond, the READ statement assigns erroneous data to the variables. Refer to DATA Statement on page 59 and RESTORE Statement on page 140 for more information. Example Sample Program
! ! ! ! ! The following example uses the READ statement to read a list of values provided by the DATA statement and assign them to the corresponding variables. See the DATA statement in this chapter.

INTEGER*4 I%,EMPNUM% REAL WAGE STRING EMPNAME$ FOR I% = 1 TO 5 READ EMPNAME$,EMPNUM%,WAGE PRINT EMPNAME$,EMPNUM%,WAGE NEXT I% DATA DATA DATA DATA DATA END MOHR,123976,22.75 MEBANE,144965,4.75 ADKINS,333927,75.88 SMITH,739528,35.27 REAGAN,927653,95.75

Output Output for the sample program is:


MOHR MEBANE ADKINS SMITH REAGAN 123976 144965 333927 739528 927653 22.75 4.75 75.88 35.27 95.75

READ # Statement
Syntax
READ#I/O session number ================================ =========== ,record number AUTOLOCK ;variable .. , .....

Use

store controller and terminal

Explanation The READ # statement reads data from a random or sequential disk file, a

Chapter 7. Statements and Language-Defined Functions

131

READ # Statement
pipe, or the I/O processor (IOPROC:). READ # assigns the data to variables specified in the input list. READ # is not valid for keyed or direct files. If the READ # statement results in an error (record or terminal not found, for example) and an ON ERROR routine processes the error, the variables associated with the read statement are set to nulls (if strings) or zero (if numeric) when a RESUME statement is executed. The CBASIC user should restrict use of the read statement to the available memory at hand. Applications usually cannot recover from Out of Memory (OM) errors. To determine the number of bytes of memory required to execute the CBASIC Read Form, use the following formula:
The bytes of memory required = [(2 * readsize) - 256]

The following example shows a readsize of 12336 bytes:


READ FORM C12336;#3;A$ ! size is much too large

Therefore,
The bytes of memory required = [(2 * 12336) - 256] = 24416.

This implies using 24416 bytes of RAM to complete the read. v I/O session number is a unique identification number you assign to a file or pipe with the CREATE or OPEN statement or to the I/O processor with the OPEN statement. v The AUTOLOCK flag specifies that the record be locked before it is read. The application program must wait for the record to become available. AUTOLOCK has meaning only for random files. v The record number applies only to random files. It is a numeric expression converted to a 4-byte integer. Record numbers start with 1, not 0. v The variable and the data to be read must have matching data types. Example Sample Program
! ! ! ! The following example uses the READ # statement to read two records from a file. See the CREATE statement in this chapter for more information.

INTEGER*2 C% REAL D STRING A$,B$ PRINT CREATE "TESTFILE.TMP" RECL 25 AS 10 PRINT "creating new file called TESTFILE.TMP" A$ = "field one" B$ = "field two" C% = 321 D = 4.5 WRITE #10,1;A$,B$ WRITE #10,2;C%,D PRINT "writing two records to file" CLOSE 10 PRINT "closing file" PRINT OPEN "TESTFILE.TMP" RECL 25 AS 5

132

IBM 4680 BASIC: Language Reference

READ # Statement
PRINT "opening the new file" READ #5,1;A$,B$ READ #5,2;C%,D PRINT "reading two records from the file" PRINT "first record is :";A$;B$ PRINT "second record is:";C%;D CLOSE 5 PRINT "closing file" PRINT "thats all folks" END

Output Output for the sample program is:


creating new file called TESTFILE.TMP writing two records to file closing file opening the new file reading two records from the file first record is: field one field two second record is: 321 4.5 closing file thats all folks

READ # LINE Statement


Syntax
READ#I/O session number ================================ ,record number AUTOLOCK ;LINEstring variable

Use

store controller and terminal

Explanation The READ # LINE statement works like the READ # statement, except READ # LINE reads an entire record, including delimiters, into a string variable. Only one string variable name can follow LINE. Otherwise, the compiler reports an error. READ # LINE is not valid for keyed or direct files. It will take less time to read a pipe with a READ FORM # than it will for the same data with a READ # LINE. The actual time difference between the two will vary with the amount of data read and the speed of the processor. If you need to minimize pipe read time, use the READ FORM #. To read variable length data with a READ FORM #, put a fixed length header to specify the number of bytes in the variable length part of the message before the variable length message. If the READ # LINE statement results in an error (record not found or terminal offline, for example) and an ON ERROR routine processes the error, the variable associated with the read statement is set to null when a RESUME statement is executed. v I/O session number is a unique identification number you assign to a file or pipe with the CREATE or OPEN statement or to I/O devices with the OPEN statement.

Chapter 7. Statements and Language-Defined Functions

133

READ # LINE Statement


v The AUTOLOCK flag specifies that the record be locked before it is read. The application program must wait for the record to become available. AUTOLOCK has meaning only for random files. v The record number applies only to random files. It is a numeric expression converted to a 4-byte integer. v LINE is a reserved word indicating that the entire record is to be read into the single string variable. Only one string variable name can follow LINE, and the variable type must be a string. For more information, see Formatted Input/Output on page 175. Example Sample Program
! ! ! ! ! ! ! ! The following example uses the READ # LINE statement to read one record of data from a file into a specified string variable. We create and write data to the file using the PRINT USING statement to format the data. Then we read each record of the file into a string variable and print the variables. READ LINE brings in the whole record, then you must parse.

REAL A,B STRING FORMAT$,AMOUNT$ CREATE "FILE.DAT" RECL 25 AS 11 A = 7333.54 B = 6125.00 FORMAT$ = "$$#,###.##" PRINT USING FORMAT$; #11,1; A,B PRINT "FILE IS CREATED" READ #11,1; LINE AMOUNT$ PRINT "RECORD 1 = ";AMOUNT$ CLOSE 11 END

Output Output for the sample program is:


FILE IS CREATED RECORD 1 = $7,333.54 $6,125.00

READ FORM # Statement


Syntax
READ FORMformat string;#I/O session number ==================================== ========== ,record number AUTOLOCK KEYkeyvalue ;variable ... , ....

Use

store controller and terminal

134

IBM 4680 BASIC: Language Reference

READ FORM # Statement


Explanation The READ FORM # statement reads data from an I/O session into a list of variables under control of the format specification given in the string expression format string. If the READ FORM # statement results in an error (record not found or terminal offline, for example) and an ON ERROR routine processes the error, the variables associated with the read statement are set to nulls (if strings) or zero (if numeric) when a RESUME statement is executed. Note: READ FORM # LINE is not allowed. Formatted reads are not required if the destination of the entire record is one variable. v The format string contains format items. The format string must be a string constant or a string variable. It cannot be a null string or expression. The following are format items that can be part of a format string (see Formatted Input on page 178 for more information): Tvalue tabs to a column or character position (relative to column zero) specified by value. nCvalue specifies the number of characters to be read into a string variable. nIvalue reads an integer variable of 1, 2, or 4 bytes as specified by value. If value is omitted, it is assumed to be 2. nR Real variable T, C, I, and R can be lowercase. The replication factor, n, is an integer constant that specifies the number of times to repeat the operation it precedes. The replication factor can range from 1 to 32767. Value is an integer constant. Value can range from 1 to 127. Commas or blanks can be used as delimiters between the various format items. v I/O session number is a unique identification number you assign to a file or pipe with the CREATE or OPEN statement or to I/O devices with the OPEN statement. v The AUTOLOCK parameter specifies that the record be locked before it is read. The application program must wait for the record to become available. AUTOLOCK is valid for random, direct, and keyed files. v The record number applies to random and direct files. It is a numeric expression converted to a 4-byte integer. v KEY keyvalue is a string for use with files opened as keyed files. Its length must equal the key length specified on the CREATE POSFILE KEYED statement that created the referenced file. v The data type of a variable must match the corresponding format item. A runtime error is generated on a random, direct, or keyed formatted READ, if the record length does not equal the length of the FORM specification. For more information, see Formatted Input/Output on page 175. Example Sample Program

Chapter 7. Statements and Language-Defined Functions

135

READ FORM # Statement


! ! ! ! ! ! ! ! ! ! ! In the following example, we create a file and write a record to the file. We use the READ FORM # statement to read the data from the first record for the file into specified variables under the control of a format string and then print the record. The record consists of 4 bytes representing the ASCII characters to be assigned to A$, followed by 2 bytes representing the integer value to be assigned to B%, followed by 10 bytes representing the real number to be assigned to C.

INTEGER*2 B%,E% REAL C,F STRING A$,D$ CREATE "READ.TST" RECL 16 AS 1 A$ = "ABCD" B% = 85 C = 613.51 WRITE FORM "C4 I2 R"; #1,1; A$,B%,C READ FORM "C4 I2 R"; #1,1; D$,E%,F CLOSE 1 PRINT D$ PRINT E% PRINT F END

Output Output for the sample program is:


ABCD 85 613.51

READ MATRIX Statement


Syntax

READ MATRIX#I/O session number;array element,number of elements

Use

store controller only

Explanation The READ MATRIX statement is a special form of the READ # statement and is valid only for sequential files. The READ MATRIX statement allows one-dimensional string arrays to be read from the disk efficiently. READ MATRIX reads a record from a sequential file and parses the record into an array. Each field in the record must be enclosed in quotes and separated by a comma. The last field in the record must be followed by a carriage-return and line-feed. If the number of fields in the record is less than the number of elements to parse, the array elements with no corresponding record fields are set to null values. If the number of fields in the records are greater than the number of elements to parse, the record fields beyond the specified number of elements to parse are ignored. If the number of elements to parse exceeds the size of the array, unpredictable results occur. v I/O session number is a unique identification number you assign to a file with the CREATE or OPEN statement.

136

IBM 4680 BASIC: Language Reference

READ MATRIX Statement


v The array element specifies the start of the input data list. Each array element must be less than or equal to 508 bytes. v The number of elements is a numeric expression specifying the number of elements to parse into the array. The starting element plus the number of elements to parse must not exceed the dimensioned size of the array or unpredictable results occur. Note: Be careful not to read into an array beyond its limit because this causes a protection exception or the *F runtime error. Example Sample Program
! ! ! ! ! In the following example, the READ MATRIX statement allows a 1 dimensional string to be read from a file efficiently. We use WRITE MATRIX to write the 1 dimensional string to the file.

INTEGER*4 A,I4% STRING COLOR$(1) DATA "ORANGE", "RED", "VIOLET", "GREEN", "BLUE" DATA "YELLOW", "BROWN", "MAGENTA" DIM COLOR$(8) CREATE "COLORS.DAT" AS 4 FOR I4% = 1 TO 8 READ COLOR$(I4%) NEXT I4% WRITE MATRIX #4; COLOR$(1),8 READ MATRIX #4; COLOR$(1),8 PRINT "THE COLORS ARE:" FOR I4% = 1 TO 8 PRINT COLOR$(I4%) NEXT I4% CLOSE 4 END

Output Output for the sample program is:


THE COLORS ARE: ORANGE RED VIOLET GREEN BLUE YELLOW BROWN MAGENTA

REAL Statement
Syntax
========== REAL variable GLOBAL .. , .....

Use

store controller and terminal

Explanation The REAL statement is a declaration statement that specifies a real number data type for variables and function names. Declaration statements
Chapter 7. Statements and Language-Defined Functions

137

REAL Statement
override the default data types specified with the last character in an identifier. Use REAL statements in the declaration group of a program, subprogram, or multiline user-defined function. v GLOBAL is an option that allows other modules to access specified identifiers. You cannot use GLOBAL in a multiline function. v Variable is an identifier. To use an array identifier in a REAL statement, place the number of subscripts in parentheses after the array name. See Chapter 2, Elements of IBM 4680 BASIC for more information on declarations and identifiers. Example Sample Program
! In the following example, the REAL statement ! specifies a real data type for a variable. REAL A A = 5.55 PRINT A END ! ASSIGN A VALUE TO A ! PRINT A

Output Output for the sample program is:


5.55

REMARK Statement
Syntax
REMARKany characters REMany characters !any characters

Use

store controller and terminal

Explanation The REMARK statement documents a source program to improve readability. Adding comments to a program with the REMARK statement makes the program easier to understand and maintain. Use any characters you want to comment your source program. Remarks do not affect the size of a compiled program. The compiler ignores everything that follows the reserved words REMARK, REM, or ! on a physical line. The continuation character allows a remark to span more than one physical line. A REMARK statement can appear on the same line with other statements, but must be the last statement on a logical line. A colon is not required to separate a REMARK statement from other statements. Note: If you have a continuation symbol (backslash) in a line that is a remark, the next line will also be treated as a remark. Example Sample Program

138

IBM 4680 BASIC: Language Reference

REMARK Statement
! ! ! ! In the following example, the REMARK statement allows you to place comments in the source program to improve readability. The three remark statements are REMARK, ! and REM. THIS PROGRAM ASSIGNS A INTEGER VALUE TO A% AND THEN PRINTS THE VALUE

REMARK REM

INTEGER*2 A% A% = 55 PRINT A% END ! ASSIGN A VALUE TO A% ! PRINT A%

Output Output for the sample program is:


55

RENAME Function
Syntax
i% = RENAME(name,name)

Use

store controller and terminal

Explanation The RENAME function allows you to change the name of a disk file during program execution. v i% is an integer value returned by RENAME. RENAME returns a -1 if the operation is successful, and a 0 (numeric) if the operation fails. v Name, in its first occurrence, is the new name assigned to the file. See Name Specification on page 34 for a complete description. v Name, in its second occurrence, is the file to rename. See Name Specification on page 34 for a complete description. Assigning a name to a file that duplicates the name of an existing file causes a runtime error. Example Sample Program
! The following example uses the RENAME function ! to rename a file and then checks to see if the ! operation was successful. INTEGER*2 I% PRINT "creating new file called TESTFILE.TMP" CREATE "TESTFILE.TMP" AS 10 PRINT "renaming TESTFILE.TMP to NEWNAME.TMP" I% = RENAME("NEWNAME.TMP","TESTFILE.TMP") IF I% THEN \ PRINT "RENAME SUCCESSFUL" \ ELSE \ PRINT "RENAME FAILED" PRINT PRINT "check current directory for NEWNAME.TMP" PRINT PRINT "thats all folks" END

Output
Chapter 7. Statements and Language-Defined Functions

139

RENAME Function
Output for the sample program is:
creating new file called TESTFILE.TMP renaming TESTFILE.TMP to NEWNAME.TMP RENAME SUCCESSFUL check current directory for NEWNAME.TMP thats all folks

RESTORE Statement
Syntax
RESTORE

Use

store controller and terminal

Explanation The RESTORE statement repositions the DATA statement pointer to the beginning of the DATA statement constant list. Use a RESTORE statement to reread the constants in the DATA statements. The CHAIN statement automatically executes a RESTORE statement. See DATA Statement on page 59 and READ # Statement on page 131 for more information. Example Sample Program
! ! ! ! The following example uses the RESTORE statement to allow a list of constants to be re-used by a READ statement. See the READ statement in this chapter.

INTEGER*4 I%,EMPNUM% REAL WAGE STRING EMPNAME$ FOR I% = 1 TO 5 READ EMPNAME$,EMPNUM%,WAGE PRINT EMPNAME$,EMPNUM%,WAGE NEXT I% RESTORE PRINT "lets read the values again" FOR I% = 1 TO 5 READ EMPNAME$,EMPNUM%,WAGE PRINT EMPNAME$,EMPNUM%,WAGE NEXT I% DATA DATA DATA DATA DATA END MOHR,123976,22.75 MEBANE,144965,4.75 ADKINS,333927,75.88 SMITH,739528,35.27 REAGAN,927653,95.75

Output Output for the sample program is:


MOHR 123976 MEBANE 144965 ADKINS 333927 SMITH 739528 REAGAN 927653 lets read the values again 22.75 4.75 75.88 35.27 95.75

140

IBM 4680 BASIC: Language Reference

RESTORE Statement
MOHR MEBANE ADKINS SMITH REAGAN 123976 144965 333927 739528 927653 22.75 4.75 75.88 35.27 95.75

RESUME Statement
Syntax
======= RESUMERETRY label

Use

store controller and terminal

Explanation The RESUME statement allows recovery from synchronous runtime errors. RESUME without the RETRY parameter or a label specification causes program control to pass to the next sequential instruction following the instruction that caused the error. v RETRY specifies re-execution of the instruction that caused the error. For errors related to input and output (I/O errors), RETRY causes the runtime library to re-execute the failed I/O operation. v The optional label specifies a statement to pass control to when an error occurs and RETRY is not specified. The RESUME label works like a GOTO statement. Use the RESUME label, not the GOTO label, to recover from the ON ERROR user code. Note: The RESUME statement may only be executed within an ON ERROR routine. Do not place the RESUME statement in a subprogram, function, or subroutine which is called by the ON ERROR routine. Do not RESUME to a label that identifies a subroutine. See Appendix B, Runtime Error Messages for information on runtime error handling and for a list of the IBM 4680 BASIC runtime errors, indicating what form of the RESUME statement is applicable to each. Refer to the IBM 4680 Store System: Programming Guide or the IBM 4690 Store System: Programming Guide for additional information on using error recovery procedures. See the ON ASYNC ERROR CALL statement for information on recovery from asynchronous errors. Example Sample Program
! ! ! ! ! The following example uses the RESUME statement to provide a recovery method for the runtime errors not due to program logic. The example attempts to open a file that does not exist and should return an "OE" error.

STRING A$,B$ ON ERROR GOTO ERRORA CLEARS A$ = "A" PRINT "WILL TRY TO OPEN A FILE THAT IS NOT PRESENT" PRINT "THE ERROR WILL DISPLAY, THEN THE EXAMPLE WILL" PRINT "RESUME AT THE NEXT STATEMENT"
Chapter 7. Statements and Language-Defined Functions

141

RESUME Statement
OPEN "FILE.111" AS 15 PRINT "RESUMING AT THE NEXT STATEMENT" STOP ERRORA: PRINT "ERROR OPENING FILE RESUME END ERR = ";ERR

Output Output for the sample program is:


WILL TRY TO OPEN A FILE THAT IS NOT PRESENT THE ERROR WILL DISPLAY, THEN THE EXAMPLE WILL RESUME AT THE NEXT STATEMENT ERROR OPENING FILE ERR = OE RESUMING AT THE NEXT STATEMENT

RETURN Statement
Syntax
RETURN

Use

store controller and terminal

Explanation Use the RETURN statement to transfer control back to the caller of a subroutine that was called with a GOSUB statement. To return from a function, use the EXIT FUNCTION statement. To return from a subprogram, use the EXIT SUB statement. Note: The RETURN statement can only be used with a GOSUB statement. Example Sample Program
! ! ! ! ! ! ! ! In the following example, we use the RETURN statement to transfer control back to the next statement after the GOSUB statement. Notice that the STOP statement in the main program prevents entering the routine directly. NOTE: Always and only use a RETURN statement with a GOSUB statement, never use a RETURN statement with a function or subroutine. PRINT GOSUB PRINT GOSUB STOP "now in main program" PRINT.MESSAGE "back in main program" PRINT.MESSAGE

PRINT.MESSAGE: PRINT PRINT "now executing PRINT.MESSAGE" PRINT "the message is HELLO" PRINT RETURN END

Output Output for the sample program is:

142

IBM 4680 BASIC: Language Reference

RETURN Statement
now in main program now executing PRINT.MESSAGE the message is HELLO back in main program now executing PRINT.MESSAGE the message is HELLO

RIGHT$ Function
Syntax
a$ = RIGHT$(string expression,numeric expression)

Use

store controller and terminal

Explanation The RIGHT$ function returns a string consisting of the rightmost characters in the string expression. When evaluating expressions, real numbers are converted to integers. v a$ is a string value returned by the RIGHT$ function. v String expression is any combination of string operands concatenated with the character operator. v Numeric expression is a positive value specifying the number of characters from the string expression. If the numeric expression is negative, a runtime error occurs. If the numeric expression equals zero, RIGHT$ returns a null string. If the numeric expression specifies more characters than the string contains, RIGHT$ returns the entire string. Example Sample Program
! ! ! ! The following example uses the RIGHT$ function to return a substring from a given string starting from the right-hand side of the string and returning a specified number of characters

STRING A$,B$ A$ = "this is a test string" B$ = "hello out there" PRINT RIGHT$(A$,6) PRINT RIGHT$(A$,11) PRINT RIGHT$(B$,5) PRINT RIGHT$(B$,3) END

Output Output for the sample program is:


string test string there ere

RMDIR Statement
Syntax

Chapter 7. Statements and Language-Defined Functions

143

RMDIR Statement
RMDIRpathname

Use

store controller only

Explanation RMDIR removes a directory named by pathname from the specified disk. Pathname is a string that specifies a valid path consisting of the root directory and subdirectories. The last subdirectory name in the pathname is the subdirectory you need to remove. The named subdirectory must be empty before you can remove it. You cannot delete the root directory and the current subdirectory. Example Sample Program
! The following example uses the RMDIR statement ! to remove a directory. STRING DIRNAME$ DIRNAME$ = "NEWDIR" PRINT "creating new subdirectory named NEWDIR" MKDIR DIRNAME$ PRINT "deleting new subdirectory named NEWDIR" RMDIR "NEWDIR" PRINT PRINT "there should not be a subdirectory called" PRINT "NEWDIR in the current directory" END

Output Output for the sample program is:


creating new subdirectory named NEWDIR deleting new subdirectory named NEWDIR there should not be a subdirectory called NEWDIR in the current directory

RND Function
Syntax
x = RND

Use

store controller only

Explanation The RND function generates and returns a uniformly distributed random number between 0 and 1. The RANDOMIZE statement seeds a random number generator to avoid identical sequences of random numbers. RND returns a real number. x is a real number returned by the RND function. See RANDOMIZE Statement on page 130 for more information. Examples Sample Program
! ! ! ! ! ! In the following example, the RND function returns a uniformly distributed random real number between 0 and 1. The RANDOMIZE statement seeds a random number generator to avoid identical sequence of numbers. Your output will vary due to randomization.

144

IBM 4680 BASIC: Language Reference

RND Function

INTEGER*2 I% RANDOMIZE FOR I% = 1 TO 5 PRINT RND NEXT I% END

Output Output for the sample program is:


.6950087256129059 .04454464856724359 .2584800862255069 .5438035116766581 .8745303432448281

ROUND Function
Syntax
x = ROUND(y,i%j%)

Use

store controller and terminal

Explanation The ROUND function returns the value of a real number rounded to a specified number of digits in a specified manner. v The Y argument is the real value to be rounded. Y is converted to real if necessary. v The I% argument is a numeric expression that specifies the decimal place at which rounding of the number occurs. I% is converted to real if necessary. If I% is positive, the digit position is to the right of the decimal point. If I% is negative, the digit position is to the left of the decimal point. If I% is zero, rounding of the number occurs at the decimal point. v The J% argument is a numeric expression that specifies how the rounding of the number is to be done. If J% is positive, the number is rounded up (away from zero). If J% is negative, the number is rounded down (toward zero), truncated at the appropriate place. If J% is zero, normal or half adjust rounding of the number occurs. Example Sample Program
! ! ! ! The following example uses the ROUND function to return the value of the real number rounded to -2, 0, and 4 decimal places and up, down, and half-adjust respectively.

REAL A,B,C,COST COST = 132.956789 A = ROUND(COST,-2,1) B = ROUND(COST,0,-1) C = ROUND(COST,4,0) PRINT A PRINT B PRINT C END

Output
Chapter 7. Statements and Language-Defined Functions

145

ROUND Function
Output for the sample program is:
200 132.0 132.9568

SADD Function
Syntax
i4 = SADD(string variable)

Use

store controller and terminal

Explanation The SADD function returns a 4-byte value representing a 32-bit address. The SADD function returns the address of the specified string variable. v i4 is the 32-bit address of the string variable. v String variable specifies the string identifier for the address you want to locate. Strings are stored as a sequential list of ASCII characters. The first two bytes hold the length of the string followed by the actual ASCII values. The length is stored as an unsigned binary integer. SADD returns an integer equal to the address of the first byte of the length of the string. Example Sample Program
! The following example places the addresses of ! S1$ and S2$ into the addresses stored in PARM.LOC% ! AND PARM.LOC%+1. INTEGER*4 PARM.LOC% STRING S1$,S2$ POKE PARM.LOC%, SADD(S1$) AND OFFH POKE PARM.LOC%+1, SADD(S2$)/256 END

SGN Function
Syntax
i% = sgn(numeric expression)

Use

store controller and terminal

Explanation The SGN function returns an integer value representing the algebraic sign of the numeric expression. SGN returns a -1 if the expression is negative, a 0 if the expression is zero, and a +1 if the expression is positive. Real number expressions are converted to integers. v i% is an integer returned by the SGN function. v Numeric expression is any real number or integer expression. Example Sample Program
! ! ! ! In the following example, the SGN$ function returns an integer value (either -1, 0, or 1) representing the algebraic sign of the numeric expression.

INTEGER*2 A%,ASGN%,BSGN%,CSGN%

146

IBM 4680 BASIC: Language Reference

SGN Function
REAL B,C A% = -12345 B = 0.0 C = 2.3456 ASGN% = SGN(A%) BSGN% = SGN(B) CSGN% = SGN(C) PRINT ASGN% PRINT BSGN% PRINT CSGN% END

Output Output for the sample program is:


-1 0 1

SHIFT Function
Syntax
i4 = SHIFT(numeric expression,numeric expression)

Use

store controller and terminal

Explanation The SHIFT function performs an arithmetic right shifting of a value a specified number of bits. You can use the function to isolate individual bits in an integer value. v i4 is a 4-byte integer returned by the SHIFT function. v The first numeric expression is a 4-byte integer that specifies the value to shift. v The second numeric expression is a 2-byte integer that specifies the number of positions to shift the first value. This value is converted to a 2-byte integer, if necessary. The SHIFT function shifts arithmetically. SHIFT divides the value in the first expression by 2, for each position shifted to the right. The function retains the arithmetic sign of the first expression after a shift. Therefore, if the first expression is positive, zeros shift into the high-order bit positions. When the value is negative, ones shift into the high-order bit positions. Example Sample Program
! ! ! ! ! ! ! ! In the following example, the SHIFT function returns an integer that is arithmetically shifted a specified number of bits or positions to the right. SHIFT divides the value in the first expression by 2, the specified number of times. In this example, eight is the specified number; therefore, the value 291 is divided by 2 eight times which equals 1.

INTEGER*4 A% INTEGER*2 B%,C% PRINT "BEGIN EXAMPLE" B% = 291 C% = 8 PRINT "SHIFTING"


Chapter 7. Statements and Language-Defined Functions

147

SHIFT Function
A% = SHIFT(B%,C%) PRINT "A = "; A% END

Output Output for the sample program is:


A = 1

SIZE Function
Syntax
i4 = SIZE(name)

Use

store controller and terminal

Explanation The SIZE function returns a 4-byte integer value representing the size in bytes of the file specified by name. v i4 is a 4-byte integer returned by the SIZE function. v Name is any valid file name. See Name Specification on page 34 for a complete description of this reserved word. In the terminal, you may only use a filename that is already opened in that terminal. In the controller, SIZE accepts the use of the wildcard characters (* and ?) to determine the size in bytes of file groups. If the specified file cannot be found, a runtime error occurs. The error is OE and ERRF% is set to 0. Example Sample Program
! ! ! ! ! In the following example, we create a file and write a record to the file. Then we execute the SIZE function to determine and return the size of the file as a 4-byte integer integer value.

INTEGER*4 A% STRING B,C CREATE "SIZE.TST" RECL 35 AS 18 B = "THIS" C = "IS IT" PRINT #18,1; B PRINT #18,2; C CLOSE 18 A% = SIZE("SIZE.TST") PRINT A% END

Output Output for the sample program is:


70

STOP Statement
Syntax
STOP

148

IBM 4680 BASIC: Language Reference

STOP Statement
Use store controller and terminal

Explanation The STOP function closes all open files and returns control to the operating system. Any number of STOP statements can appear in a program. Example Sample Program
! The following example uses the STOP statement to ! terminate the program if the user responds to the ! prompt with an S. STRING CHOICE$ PRINT PRINT "enter S to stop" PRINT " OR" PRINT "anything else to continue "; INPUT CHOICE$ PRINT IF CHOICE$ = "S" THEN \ BEGIN PRINT "program halted by user" STOP ! PROGRAM WILL STOP HERE IF "S" IS ! ENTERED ENDIF PRINT PRINT "program will now continue" PRINT "thats all folks" END ! PROGRAM WILL STOP HERE IF SOMETHING ! OTHER THAN "S" WAS ENTERED

Output The output from the example depends on what the user enters when prompted. If the user enters a capital S, the program stops; otherwise, the program continues.

STR$ Function
Syntax
a$ = STR$(numeric expression)

Use

store controller and terminal

Explanation The STR$ function converts a numeric expression to a string of characters identical to the digits in the expression. STR$ deletes blank space that precedes or follows a number. STR$ deletes leading zeros from the return value, unless the value is zero. If the return value is zero, only one zero is returned. v a$ is a string value returned by the STR$ function. v Numeric expression is any real number or integer expression. Example Sample Program
! The following example uses STR$ to convert a hexadecimal ! integer and a real number to decimal number strings. INTEGER*4 VAL1% REAL VAL2 STRING DECIMAL$,VALUE$,PRICE$

Chapter 7. Statements and Language-Defined Functions

149

STR$ Function
VAL1% = 0FFH VAL2 = 543.21 DECIMAL$ = STR$(VAL1%) VALUE$ = STR$(VAL2) PRICE$ = "$" + VALUE$ PRINT DECIMAL$ PRINT PRICE$ END

Output Output for the sample program is:


255 $543.21

STRING Statement
Syntax
========== STRING variable GLOBAL ... , ....

Use

store controller and terminal

Explanation The STRING statement is a declaration statement that specifies a string data type for variables and function names. Use STRING statements in the declaration group of a program, multiline function or subprogram. Declaration statements override the default data type specified with the last character in an identifier. v GLOBAL is an option that allows other modules to access the specified identifier. v Variable is an identifier. To use an array identifier in a STRING statement, place the number of subscripts in parentheses following the array name. When a variable is assigned a value, space is dynamically allocated to contain that value. If the same variable is assigned a smaller value, the original space is not recovered unless the variable is FIRST set to null. Example Sample Program
! The following example uses the STRING statement ! to declare three STRING variables in which ! character literals are placed. STRING A$,B$,C$ A$ = "this is a test" B$ = "heres another string" C$ = "thats all folks" PRINT A$ PRINT B$ PRINT C$ END

Output Output for the sample program is:

150

IBM 4680 BASIC: Language Reference

STRING Statement
this is a test heres another string thats all folks

STRING$ Function
Syntax
a$ = STRING$(numeric expression,string expression)

Use

store controller and terminal

Explanation The STRING$ function returns a string that consists of one string copied a specific number of times. v a$ is a string value returned by the STRING$ function. v Numeric expression is any real number or integer expression. Numeric expressions that evaluate to real numbers are converted to integers. The numeric expression specifies the number of times to copy the string in the string expression. v String expression is any combination of string operands concatenated with the character operator. The length of the returned string equals the length of the string in the string expression, multiplied by the numeric expression. STRING$ reduces memory fragmentation when building large strings and executes significantly faster than building a string using concatenation. Example Sample Program
! The following example uses STRING$ function to ! demonstrate string copying. REAL VAL1 STRING A$,B$,VALUE$,COPY1$,COPY2$ VAL1 = 543.21 A$ = "BASIC " VALUE$ = STR$(VAL1) B$ = VALUE$ + " " COPY1$ = STRING$(2,B$) COPY2$ = STRING$(3,A$) PRINT COPY1$ PRINT COPY2$ END

Output Output for the sample program is:


543.21 543.21 BASIC BASIC BASIC

SUB Statement
Syntax

Chapter 7. Statements and Language-Defined Functions

151

SUB Statement
================= ============ SUBsubprogram name EXTERNAL (parameter) PUBLIC ... , ..... maximum 15 ============= RECURSIVE

Use

store controller and terminal

Explanation The SUB statement marks the beginning of a subprogram definition. The subprogram name is an identifier that marks a logically independent block of code you can compile separately from the calling program and from other subprograms. v Subprogram name is an identifier. v Formal parameter list is a list of parameters that act as place holders for the actual parameters to be passed to the subprogram, by the calling program. Formal parameters should be declared in the subprogram definition. v EXTERNAL identifies an abbreviated subprogram definition that corresponds to a complete PUBLIC subprogram definition in a separate module. The abbreviated EXTERNAL subprogram definition consists of the SUB statement, parameter declarations, and the END SUB statement. v PUBLIC identifies the complete subprogram definition accessible from separate modules in your program. v RECURSIVE is an optional flag indicating that the function will be called recursively. RECURSIVE indicates that the subprogram can call itself. RECURSIVE causes the compiler to allocate any local variables declared by the subprogram on the stack. These local variables exist only while the subprogram has control, and they do not retain their values between calls to the subprogram. RECURSIVE functions are less efficient than nonrecursive ones because of the overhead associated with managing stack variables. Arguments can be passed to a subprogram when it is called. A subprogram works the same as a multiline user-defined function, except that the arguments are passed by reference instead of by value. This means that any change to the argument in the function is reflected in its value, after control is returned to the caller. Unlike multiline user-defined functions, subprograms cannot be referenced within an expression. Example Sample Program
! ! ! ! The following example uses the SUB statement to define a subprogram that calculates the average of two REAL numbers and returns the result as a STRING.

STRING AVESTRING$ SUB AVERAGE(INVAL1,INVAL2,OUTVAL$) REAL INVAL1,INVAL2,TEMP STRING OUTVAL$ TEMP = (INVAL1 + INVAL2) / 2 OUTVAL$ = "$" + STR$(TEMP)

152

IBM 4680 BASIC: Language Reference

SUB Statement
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

Output 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

TAB Function
Syntax
TAB(numeric expression)

Use

store controller only

Explanation The TAB function moves the cursor or print head to the column number specified in a numeric expression. TAB does not return a value. You must use TAB as an expression within a PRINT statement. Numeric expression is any real number or integer expression. The numeric expression converts to an integer. TAB sends blank characters until the cursor or print head reaches the appropriate position. If the value of the expression is less than or equal to the current print position, TAB sends a carriage return and line-feed before tabbing to the specified column. The expression cannot exceed the line width. An incorrect TAB column can result if a program outputs cursor or printer control characters. Note: Use the TAB function in PRINT or PRINT USING statements only. Do not use TAB with PRINT # statements. Example Sample Program
! In the following example, the TAB function ! moves the cursor or print head to a specified ! column number. STRING A$,B$ A$ = "COLUMN 1" B$ = "COLUMN 30" PRINT A$;TAB(30);B$ END

Output Output for the sample program is:


COLUMN 1 COLUMN 30

Chapter 7. Statements and Language-Defined Functions

153

TCLOSE Statement

TCLOSE Statement
Syntax
TCLOSEI/O session number

Use

store controller and terminal

Explanation The TCLOSE statement causes the program to write disk file buffers to disk. TCLOSE also updates the file directory. To suspend your application while all queued print lines are printed at all of the print stations, issue a TCLOSE with the I/O session number used to open any one of the print stations. I/O session number is a unique identification number you assign to a file with the CREATE or OPEN statement or to a printer station with the OPEN statement. For asynchronous WRITEs to the printer stations, TCLOSE causes the program to suspend execution until the device driver signals the physical completion of all queued output or an error occurs. Note: TCLOSE causes distribution of a file if you specified the ATCLOSE distribution mode. TCLOSE is valid in the terminal only for the terminal printer. Do not issue a TCLOSE for a file from the terminal. Example
OPEN "CR:" OPEN "SJ:" . . WRITE FORM WRITE FORM . . WRITE FORM WRITE FORM TCLOSE 3 . . END AS 3 AS 4 !Open customer receipt station !Open summary journal

"C38, A1"; #4; item.price$ "C38, A1"; #3; item.desc.price$ "C38, A2"; #3; subtotal.line$ "C38, A2"; #3; trailer$ !Wait for all lines to print on CR: and SJ:

TIME$ Function
Syntax
a$ = TIME$

Use

store controller and terminal

Explanation The TIME$ function returns a string indicating the time of day. a$ is a string value returned by the TIME$ function. TIME$ returns a six-character string of the form HHMMSS. HH is one of 24 digit combinations representing the hour, such as 06 for 6:00 AM or 15 for 3:00 PM. MM is 1 of 60 digit combinations representing the minute. SS is 1 of 60 digit combinations representing the second.

154

IBM 4680 BASIC: Language Reference

TIME$ Function
Example Sample Program
! ! ! ! ! In the following example, the TIME$ function returns a six character string indicating the current time of day in the form HHMMSS. Your output will vary depending on the time of execution.

STRING T$,H$,M$,S$ T$ = TIME$ H$ = LEFT$(T$,2) M$ = MID$(T$,3,2) S$ = RIGHT$(T$,2) PRINT H$; ":"; M$; ":"; S$; " IS THE TIME" END

Output Output for the sample program is:


The output from the example is: 14:08:33 IS THE TIME

TRANSLATE$ Function
Syntax
a$ = TRANSLATE$(1st string,2nd string,3rd string)

Use

store controller and terminal

Explanation The TRANSLATE$ function modifies a character string through a match and replace process. v 1st string is the input string for TRANSLATE$ to modify. v 2nd string specifies the characters to be searched for in the first string. v 3rd string specifies the characters used to replace any characters in the first string that match those in the second string. Example Sample Program
! ! ! ! ! In the following example, the TRANSLATE$ function modifies a character string through a match and replace process. TRANSLATE$ is used to encode a message, using a simple alphabetic substitution code:

STRING MESSAGE$,IN$,OUT$,CODE$ MESSAGE$ = "THIS IS A CODED MESSAGE" IN$ = "ABCDEFGHIJKLMNOPQRSTUVWXYZ" OUT$ = "ACEGIKMOQSUWYBDFHJLNPRTVXZ" CODE$ = TRANSLATE$(MESSAGE$,IN$,OUT$) PRINT MESSAGE$ PRINT CODE$ END

Output Output for the sample program is:


THIS IS A CODED MESSAGE NOQL QL A EDGIG YILLAMI
Chapter 7. Statements and Language-Defined Functions

155

UCASE$ Function

UCASE$ Function
Syntax
a$ = UCASE$(string expression)

Use

store controller and terminal

Explanation The UCASE$ function returns the string expression with all of its lowercase characters converted to uppercase characters. UCASE$ does not change the original string. Only letters between lowercase a and lowercase z are affected by this function. v a$ is a string value returned by the UCASE$ function. v String expression is any combination of string operands concatenated with the character operator. Note: The function does not convert a lowercase character to an uppercase character, if the lowercase character is the first or second byte of a valid DBCS character. Example Sample Program
! ! ! ! In the following example, the UCASE$ function returns the string expression with all of its lowercase characters converted to uppercase characters.

STRING A$ A$ = "upper case" PRINT A$ A$ = UCASE$(A$) PRINT A$ END

Output Output for the sample program is:


upper case UPPER CASE

UNLOCK Function
Syntax
i4 = UNLOCK(I/O session number,record number)

Use

store controller only

Explanation The UNLOCK function unlocks a specified record allowing modification of data in the record. The UNLOCK function returns the value that the operating system returns after attempting to unlock a record. UNLOCK returns a zero to indicate the record is unlocked, or if an operating system error occurs, the non-zero value returned is the operating system error code.

156

IBM 4680 BASIC: Language Reference

UNLOCK Function
A record must be part of a file with fixed record lengths to be locked or unlocked. The file must be accessed in the UNLOCKED mode. Refer to the LOCK function, CREATE statement, and OPEN statement in this chapter for more information. v i4 is a 4-byte integer returned by the UNLOCK function. v I/O session number is a unique identification number you assign to a file with the CREATE or OPEN statement. v Record number is a 4-byte integer. Do not use UNLOCK for files written with a WRITE # statement that specifies the HOLD parameter. READ AUTOLOCK/WRITE UNLOCK functions should be used. Example Sample Program
! In the following example, the UNLOCK function ! unlocks a specified record allowing modification ! of data in the record and prints a message. INTEGER*4 E% INTEGER*2 B%,D% REAL C STRING A$ CREATE "READ.TST" RECL 16 AS 1 A$ = "ABCD" B% = 85 C = 613.51 WRITE FORM "C4 I2 R"; #1,1; A$,B%,C OPEN "READ.TST" RECL 16 AS 11 D% = 1 E% = UNLOCK(11,D%) PRINT E% IF E% = 0 THEN \ PRINT "RECORD"; D%;"IS UNLOCKED."\ ELSE\ PRINT "ATTEMPT TO UNLOCK RECORD FAILED." CLOSE 1 END

Output Output for the sample program is:


0 RECORD 1 IS UNLOCKED

UNLOCKDEV Statement
Syntax
=============== UNLOCKDEVI/O session number ,newstate =============== ,PRIORITY

Use

terminal only

Explanation The UNLOCKDEV statement is the inverse of the LOCKDEV statement.


Chapter 7. Statements and Language-Defined Functions

157

UNLOCKDEV Statement
UNLOCKDEV allows input from a device assuming the device was previously locked using LOCKDEV. If the device was not previously locked, the UNLOCKDEV statement has no effect. Therefore there is a possibility for data to be ignored. v I/O session number is the number assigned to the I/O device in the OPEN statement. v Newstate is the numeric argument specifying a new state number for the I/O processor. It is ignored for other devices. v The PRIORITY flag is valid only for the I/O processor. PRIORITY causes any data entered by the operator to be read before data in the I/O processor queue. Example The following example uses the UNLOCKDEV statement to unlock the I/O processor:
OPEN "IOPROC:" AS 3 BUFF 4 BUFFSIZE 48 . . ! Record not found on file. Get operator to ! enter price for missing record item. UNLOCKDEV 3, itementry, PRIORITY . . END

UNPACK$ Function
Syntax
a$ = UNPACK$(string)

Use

store controller and terminal

Explanation The UNPACK$ function reverses the action of the PACK$ function. v a$ is a string value returned by the UNPACK$ function. v String is any string value. Each four bits of a string, starting with the high-order four-bits of the first byte, is converted to a byte value. Bits 4 and 5 of this byte are set equal to one. Each four bits of a string, whose values are between 0 and 9, are converted to their equivalent ASCII decimal numerals. If there is an F in the high-order four-bits, it is discarded. Example Sample Program
! ! ! ! The following example uses the PACK$ function to* pack the digits in BCD form and then uses UNPACK$ to restore them to the original form. See the PACK$ statement in this chapter.

INTEGER*2 I% STRING A$,B$,C$ I% = 12345 A$ = STR$(I%) B$ = PACK$(A$) C$ = UNPACK$(B$) PRINT "first we have an INTEGER value of";I%

158

IBM 4680 BASIC: Language Reference

UNPACK$ Function
PRINT "when converted to a STRING it looks like ";A$ PRINT "after using PACK$ it looks like ";B$ PRINT "after using UNPACK$ it looks like ";C$ END

Output Output for the sample program is:


first we have an INTEGER value of 12345 when converted to a STRING it looks like 12345 after using PACK$ it looks like #E after using UNPACK$ it looks like 12345

USE Statement
Syntax
USEvariable ... , .....

Use

store controller and terminal

Explanation With the USE statement, you obtain arguments from a different application program that initiated the execution of the current application with the CHAIN statement. The mapping of argument values to variables is by order only. The first variable receives the value of the first argument specified in the CHAIN statement, regardless of its type or the argument type. You must know precisely what parameters are being passed from the chaining application. Each variable can contain any number of bytes of data as long as it is less than the available contiguous free space in the heap. Example Sample Program
! ! ! ! ! ! ! ! In the following example, the USE statement obtains parameters passed on a CHAIN statement. In program C.286, the CHAIN statement instructs the system to load program U.286 into memory and passes three parameters to U.286. In U.286, the USE statement specifies three variables. These variables receive the three parameters passed by the CHAIN statement. The output results from executing C.286

! This is program C.286 ! C.286 chains to U.286 INTEGER*2 D% REAL E STRING F$ D% = 123 E = 4.567 F$ = "F" PRINT "INVOKING CHAIN STATEMENT IN C.286" CHAIN "U.286", D%,E,F$ END ! This is program U.286 ! U.286 is chained to from C.286 INTEGER*2 A% REAL B
Chapter 7. Statements and Language-Defined Functions

159

USE Statement
STRING C$ PRINT "INVOKING USE IN U.286" USE A%,B,C$ PRINT A% PRINT B PRINT C$ END

Output Output for the sample program is:


INVOKING CHAIN IN C.286 INVOKING USE IN U.286 123 4.567 F

VAL Function
Syntax
x = VAL(digit string expression)

Use

store controller and terminal

Explanation The VAL function converts the digit string expression to a number. The number is an integer if x is an integer, or the number is a real number if x is a real variable. VAL processes from left to right until it reaches the end of the string. VAL returns a zero if the string is null. A plus or minus sign can precede the digit string. You can place a decimal point symbol in the digit string. (This is either a period or a comma depending on the OPTION statement specification.) VAL returns a runtime error if it encounters a character that is not valid (if the character is not a leading +, -, blank, the first occurrence of the decimal point symbol, or a valid number (0-9)). v x is a number returned by the VAL function. It may be an integer or real variable. v Digit string expression is a string composed only of digits and an optional decimal point symbol. Example Sample Program
! In the following example, the VAL function ! converts the digit string to a number. INTEGER*4 S%,T%,U% REAL W,X S% = VAL("999999") T% = VAL("+8888") U% = VAL("-7777") W = VAL("66.66") X = VAL("55.55555") PRINT S% PRINT T% PRINT U% PRINT W PRINT X END

160

IBM 4680 BASIC: Language Reference

VAL Function
Output Output for the sample program is:
999999 8888 -7777 66.66 55.55555

VARPTR Function
Syntax
i4 = VARPTR(variable)

Use

store controller and terminal

Explanation The VARPTR function returns a 4-byte integer value representing a 16-bit or 32-bit address of a variable. v i4 is a 4-byte integer returned by the VARPTR function. v Variable is a string or numeric identifier. For a non-subscripted numeric variable, VARPTR returns the actual address. For string variables, VARPTR returns the address of a 16-bit (terminal) or 32-bit (store controller) pointer. The actual location of the string varies because strings are allocated dynamically, but the value that VARPTR returns does not change during program execution. If a variable is in COMMON, the VARPTR value location does not change after chaining. For subscripted variables, VARPTR returns the address of a pointer to an array element in the heap. Example Sample Program
! ! ! ! ! In the following example, the VARPTR function returns a 4-byte integer value representing a 16-bit or 32-bit address of a variable. The output address will vary depending on where the program is loaded.

INTEGER*4 A%,B% A% = 1234 B%= VARPTR(A%) PRINT B% END

Output Output for the sample program is:


8847420 !address is in decimal

WAIT Statement
Syntax

Chapter 7. Statements and Language-Defined Functions

161

WAIT Statement
======================= WAIT ;timeout.val I/O session number ........ , .........

Use

store controller and terminal

Explanation Use the WAIT statement to wait for data to be available from one or more I/O sessions. v I/O session number is the session number assigned to the I/O device in the OPEN statement. I/O sessions that can be waited on is 31 (minus the number of outstanding asynchronous events already in use by the application). v timeout.val is a 4-byte integer containing the number of milliseconds to wait for data from the I/O sessions. v If you do not specify an I/O session number, the WAIT statement suspends execution for the number of milliseconds specified in timeout.val. The EVENT% function returns the identity of the I/O session that has available data. EVENT% returns zero if the amount of time set in timeout.val has elapsed before data from an I/O session is available. Example Sample Program
! In the following example, the WAIT statement ! pauses 5 seconds, then the program continues. STRING A$,B$ A$ = "WAITING FIVE SECONDS." B$ = "TIMES UP." PRINT A$ WAIT;5000 PRINT B$ END

Output Output for the sample program is:


WAITING FIVE SECONDS. TIMES UP.

WEND Statement
Syntax
WEND

Use

store controller and terminal

Explanation A WEND statement ends a WHILE/WEND loop. WEND sends control to the beginning of the WHILE/WEND loop until the WHILE expression evaluates to logical false (0). Branching to a WEND statement sends control to the corresponding WHILE statement.

162

IBM 4680 BASIC: Language Reference

WEND Statement
Example Sample Program
! In the following example, the WEND statement ! indicates the end of a waiting WHILE/WEND loop. ! The program continues after pressing any key. STRING A$,B$ A$ = "PRESS ANY KEY TO CONTINUE." B$ = "CONTINUING." PRINT A$ WHILE NOT CONSTAT% WAIT ; 200 ! suspend execution to service lower prioity tasks WEND PRINT B$ END

Output Output for the sample program is:


PRESS ANY KEY TO CONTINUE. CONTINUING.

WHILE Statement
Syntax
WHILElogical expression

Use

store controller and terminal

Explanation The WHILE statement specifies the logical expression that controls a WHILE/WEND loop. Logical expression evaluates to either true or false. All statements between a WHILE statement and a corresponding WEND statement execute until the value of the expression following the reserved word WHILE evaluates to logical false (0). Note: WHILE must first convert real expressions to integers. Using integer expressions reduces execution time. WHILE/WEND loops can be nested. Example Sample Program
! In the following example, the WHILE statement ! creates a waiting WHILE/WEND loop. The program ! continues after pressing any key. STRING A$,B$ A$ = "PRESS ANY KEY TO CONTINUE." B$ = "CONTINUING." PRINT A$ WHILE NOT CONSTAT% WAIT ; 200 ! suspend execution to service lower priority tasks WEND PRINT B$ END

Output
Chapter 7. Statements and Language-Defined Functions

163

WHILE Statement
Output for the sample program is:
PRESS ANY KEY TO CONTINUE. CONTINUING.

WRITE # Statement
Syntax
======================== ======== WRITE FORMformat string; HOLD ============== #I/O session number AUTOUNLOCK ================== ;expression ,record number .... , .....

Use

store controller and terminal

Explanation The WRITE # statement writes data to disk files, pipes, communication sessions, or devices specified by the I/O session number. v FORM and format string parameters enable you to specify a format for the data to be written. You must specify a format when writing to a direct or keyed file. If you do not specify a format (unformatted WRITE #) and the destination is a pipe or a sequential or random disk file, the result is identical to the PRINT # statement. v The format string must be a string constant or a string variable. It cannot be a null string or expression. The format string contains literal data and data specifiers. Literal data can be numeric or string data. For more information on formatted I/O, see Formatted Input/Output on page 175. You can use the following specifiers in a format string: nPIC(...string...) is like the USING in PRINT. It is useful for converting real or integer variables to ASCII form. Special characters are used to represent format items: For example:
INTG = 00000010B WRITE FORM "PIC(INTG = ##)";#2; INTG

Results in:
INTG = 2 WRITE FORM "PIC(INTG = 99)";#2;INTG

Results in:
INTG = 02

Tvalue tabs to column specified by value. nCvalue formats string variables where value is the number of characters to write. For example:
A$ = "EIGHT CH" B$ = "FIFTEEN CHRCTRS" WRITE FORM "2C10";#2; A$,B$

Results in:

164

IBM 4680 BASIC: Language Reference

WRITE # Statement
EIGHT CH FIFTEEN CH

nIvalue is used to write n integer(s) of size value. (Value is 1, 2, or 4 bytes. If omitted, value is defaulted to 2). Generally nIvalue is useful only for writing to devices such as files and hard totals. The actual hexadecimal value is written in blocks of 1, 2, or 4 bytes at a time. For example:
INTG2A = 0102H INTG2B = 0203H INTG4 = 01020304H WRITE FORM "2I2,I4";#2;INTG2A,INTG2B,INTG4

Results in:
0201030204030201 being sent to device #2

(note the interchanging of bytes) nR is used to write n real (floating point) numbers. Each number occupies 10 bytes. Generally, nR is useful only for writing to devices such as files and hard totals. For example:
REALVAR1 = 12345.67890 REALVAR2 = 1234560.789 ! ! .123456789 E +5 .1234560789 E +7

WRITE FORM "2R"; #2; REALVAR1, REALVAR2

Results in the following 20 bytes of hex data:


4500000000907856341247000000008907563412

being sent to device #2. (Numbers are stored in excess 40H notation - 10 * * 5 = 45H). nAvalue is used to advance lines equal to value. For example:
OPEN "CR:" AS 2 PRNTL$ = "1234567890123456789012345678012345678" WRITE FORM "C38,A1";#2;PRNTL$ WRITE FORM "C38,A1";#2;PRNTL$

Results in printing:
1234567890123456789012345678012345678 1234567890123456789012345678012345678

Note that if number = 0, the second line would print on top of the first. Also, only one line can be written to the printer per statement. For example, WRITE FORM C38,A1,C38;#2; will result in a runtime error. The value can range from 1 to 255. n/string/ is a literal string that is written to the file or device driver. It is enclosed between slashes in the format.string and can be preceded by a replication factor. For example:
WRITE FORM "/Inventory Code: / T30 C4"; #1, 1; CODE$

The following example produces the same output as the preceding example:
FMT$="/Inventory Code: / T30 C4" WRITE FORM FMT$; #1, 1; CODE$

Both examples write the literal string Inventory Code: to record 1 of the file assigned to I/O session number 1. They tab to byte 30 in the record, and output the first four characters of CODE$.

Chapter 7. Statements and Language-Defined Functions

165

WRITE # Statement
Note: T, C, I, and R can be lowercase. The replication factor, n, is an integer constant that specifies the number of times to repeat the operation it precedes. The replication factor can range from 1 to 32767. Value is an integer constant. Value can range from 1 to 255. String and picture string are both string variable expressions. You can use Commas or blanks as delimiters between the various format items. v The HOLD flag prevents the data from being physically written to a disk file until the next WRITE HOLD is issued by this process. Each record must be less than or equal to 512 bytes in length. HOLD is valid only for programs executing in the store controller. See the IBM 4680 Store System: Programming Guide or the IBM 4690 Store System: Programming Guide for more information. v I/O session number is a unique identification number you assign to a file or pipe with the CREATE or OPEN statement, or to an I/O device with the OPEN statement. v AUTOUNLOCK is a flag requesting the record be unlocked after being written. It has meaning only for random, direct, or keyed files. v Record number is a numeric expression, converted to 4-byte integer, giving the logical record number to create or overwrite with this WRITE operation, if the file is random or direct. Record number has meaning only for random or direct files. A runtime error is generated on a random, direct, or keyed formatted WRITE, if the record length specified in the OPEN or CREATE statement does not equal the length of the FORM specification. v Expressions are the data to be output. All WRITE # statements from the terminal cause a complete line or record to be written; however, carriage return/line feeds do not affect video display devices. A runtime error is generated on a WRITE # to a device if the number of bytes written does not match the number that the device expects. The WRITE # statement is asynchronous in the store controller for host communications; all other WRITE #s are synchronous in the store controller. Data is not buffered when a WRITE # statement is executed in terminal. This means that every time a WRITE # to a disk file is executed, the file is updated. When a file is opened in UNLOCKED mode in the store controller, the file is also updated on each WRITE #. For KEYED files, the record key is specified as the first data item in the expression list. Writes to keyed files are not buffered. Example Sample Program
! ! ! ! The following example uses the WRITE # statement to write two records to a file. See the CREATE statement in this chapter for more information.

INTEGER*2 C% REAL D STRING A$,B$ CREATE "TESTFILE.TMP" RECL 25 AS 10 PRINT "creating new file called TESTFILE.TMP" PRINT

166

IBM 4680 BASIC: Language Reference

WRITE # Statement
A$ = "field one" B$ = "field two" C% = 321 D = 4.5 WRITE #10,1;A$,B$ WRITE #10,2;C%,D CLOSE 10 PRINT "TYPE the new file to see the contents" PRINT "thats all folks" END

Output Output for the sample program is written to the screen and to a file.
SCREEN OUTPUT ------------creating new file called TESTFILE.TMP TYPE the new file to see the contents thats all folks FILE OUTPUT ----------(contents of TESTFILE.TMP)

"field one","field two" 321,4.5,

WRITE LOGO # Statement


Syntax
WRITE LOGO#I/O session number;array element

Use

terminal only

Explanation WRITE LOGO # is a special form of the WRITE # statement designed to make printing to the middle 300 dots of a print line easy to specify. Each execution of the WRITE LOGO # statement prints a single line. You use multiple WRITE LOGO # statements to print a complete logo. The data for WRITE LOGO # must be in a one-dimensional array of 1-byte integers. Each 1-byte integer contains a bit mask indicating points to print. A bit set to 1 prints a point and a bit set to 0 does not print a point. The bit numbered zero is the top-most bit, while the bit numbered 7 is the bottom-most bit for a print line. v I/O session number is a unique identification number you assign to the customer receipt (CR:) or document insert (DI:) stations with the OPEN statement. v The array element marks the start of the output data list. The number of elements used is always 381. The first 300 elements are the data items to print. The 301st through 380th bytes are not used. The last element is the number of partial line-feeds. There are nine partial line-feeds per line. WRITE LOGO # is valid only for the customer receipt and document insert stations.

Chapter 7. Statements and Language-Defined Functions

167

WRITE LOGO # Statement


There is a special mode of WRITE LOGO # that can also be used to print and endorse customers checks. This mode is selected by using the PUTLONG statement. In check printing mode, the printer driver interprets data in the 381 byte array differently than in logo printing mode. For more information, see Printer Stations for Printer Models 1 and 2 on page 219, Printer Stations for Printer Models 3 and 4/4A on page 223, or see the IBM 4680 Store System: Programming Guide or the IBM 4690 Store System: Programming Guide. Example The following example prints the numeral 1 as an all-points-addressable logo:
%ENVIRON T INTEGER*1 logoarray(1) DIM logoarray(1524) logoarray(4) = 0F8H logoarray(5) = 0FCH logoarray(6) = 0FEH logoarray(7) = 0FFH logoarray(8) = 0FFH logoarray(9) = 0FFH logoarray(10) = 0FFH logoarray(11) = 0FFH logoarray(12) = 0FFH logoarray(13) = 0FFH logoarray(14) = 0FFH logoarray(381) = 8 ! 1st Print Line

OPEN "CR:" AS 1 WRITE LOGO #1; logoarray(1) logoarray(385) = 1 ! 2nd Print Line logoarray(386) = 1 logoarray(387) = 1 logoarray(388) = 1 logoarray(389) = 1 logoarray(390) = 0FFH logoarray(391) = 0FFH logoarray(392) = 0FFH logoarray(393) = 0FFH logoarray(394) = 0FFH logoarray(395) = 0FFH logoarray(762) = 8 WRITE LOGO #1; logoarray(382) logoarray(771) = 0FFH ! 3rd Print Line logoarray(772) = 0FFH logoarray(773) = 0FFH logoarray(774) = 0FFH logoarray(775) = 0FFH logoarray(776) = 0FFH logoarray(1143) = 8 WRITE LOGO #1; logoarray(763) logoarray(1147) = 0F8H ! 4th Print Line logoarray(1148) = 0F8H logoarray(1149) = 0F8H logoarray(1150) = 0F8H logoarray(1151) = 0F8H logoarray(1152) = 0FFH logoarray(1153) = 0FFH logoarray(1154) = 0FFH logoarray(1155) = 0FFH logoarray(1156) = 0FFH logoarray(1157) = 0FFH

168

IBM 4680 BASIC: Language Reference

WRITE LOGO # Statement


logoarray(1158) logoarray(1159) logoarray(1160) logoarray(1161) logoarray(1162) logoarray(1524) = = = = = = 0F8H 0F8H 0F8H 0F8H 0F8H 16

WRITE LOGO #1; logoarray(1144) END

The preceding example produces the following output:

bit # 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7

_______________________________ XXXXXXXX First Print Line XXXXXXXXX XXXXXXXXXX XXXXXXXXXXX XXXXXXXXXXX XXXXXXXXXXX XXXXXXXXXXX XXXXXXXXXXX _______________________________ XXXXXXXXXXX Second Print Line XXXXXX XXXXXX XXXXXX XXXXXX XXXXXX XXXXXX XXXXXX _______________________________ XXXXXX Third Print Line XXXXXX XXXXXX XXXXXX XXXXXX XXXXXX XXXXXX XXXXXX _______________________________ XXXXXX Fourth Print Line XXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX _______________________________

WRITE MATRIX Statement


Syntax
WRITE MATRIX#I/O session number;array element,number of elements

Use

Store controller and terminal

Explanation WRITE MATRIX is a special form of the WRITE # statement and is valid only for sequential files. WRITE MATRIX allows one-dimensional string arrays to be written to the disk efficiently. WRITE MATRIX writes each array element to the file as a separate field surrounded by quotes. All specified array elements are contained in one record. Each field is separated with a comma. The last field is followed with a carriage-return and line-feed.
Chapter 7. Statements and Language-Defined Functions

169

WRITE MATRIX Statement


v I/O session number is a unique identification number you assign to a file with the CREATE or OPEN statement. v The array element specifies the start of the output data list. Each array element must be less than or equal to 508 bytes. v The number of elements is a numeric expression specifying the number of elements to write. Note: Be careful not to write from an array beyond its limit because this causes a protection exception or the *F runtime error. Example Sample Program
! ! ! ! ! In the following example, the WRITE MATRIX statement allows a 1 dimensional string to be written to a file efficiently. We use READ MATRIX to read the 1 dimensional string to the file.

INTEGER*4 A,I4% STRING COLOR$(1) DATA "ORANGE", "RED", "VIOLET", "GREEN", "BLUE" DATA "YELLOW", "BROWN", "MAGENTA" DIM COLOR$(8) CREATE "COLORS.DAT" AS 4 FOR I4% = 1 TO 8 READ COLOR$(I4%) NEXT I4% WRITE MATRIX #4; COLOR$(1),8 READ MATRIX #4; COLOR$(1),8 PRINT "THE COLORS ARE:" FOR I4% = 1 TO 8 PRINT COLOR$(I4%) NEXT I4% CLOSE 4 END

Output Output for the sample program is:


THE COLORS ARE: ORANGE RED VIOLET GREEN BLUE YELLOW BROWN MAGENTA

170

IBM 4680 BASIC: Language Reference

Chapter 8. Using Input and Output Devices and Pipes


You can move data between devices, between data files, or between a file and a device. Different types of files, file protection, pipes, and buffering accommodate the complex interactions required in a store system. For more information on files, file types, host processor, and I/O devices, see the IBM 4680 Store System: Programming Guide or the IBM 4690 OS Version 3: Programming Guide

Pipes
A pipe is an area of temporary storage allocated in the random access memory (RAM) of your computer. You typically use pipes to transfer data from one process to another. Data written at one end of a pipe by a process can be read at the other end of the pipe by another process. For additional information on pipes and pipe routing services, see the IBM 4680 Store System: Programming Guide or the IBM 4690 OS Version 3: Programming Guide. IBM 4680 BASIC treats a pipe the same as a sequential file, with the following exceptions: v To OPEN or CREATE a pipe, specify a pipe name (same as a file name) preceded by the identifier pi: See the program example following this listing. v You use the value you specify for the BUFFSIZE parameter in the OPEN or CREATE statement for a pipe as the total size in bytes for the pipe. It is not the size of the buffer for pipe input/output (I/O). Alternatively, you can specify a BUFF parameter. The value you specify for BUFF is multiplied by 128. The result is the total size in bytes of the pipe. v A pipe should be large enough to handle the largest record your program writes to the pipe. Your program waits until the entire record is written to the pipe or until another program removes data by reading it. v The runtime buffer size for a pipe is 256 bytes unless you specify a record length. A record length specified in an OPEN or CREATE statement for a pipe actually specifies the size of the I/O buffer for the pipe. This buffer is used to map data into the format.string specified in a READ FORM # or WRITE FORM # statement. v Using delimited data, you can read or write a pipe created or opened with no specified record length. Alternatively, you can use these statements: READ FORM # WRITE FORM # If you specify a record length for a pipe, a read operation reads an amount of data equal to the record length. v If there is not enough data in a pipe to satisfy a read, the program performing the read is suspended until the required data is available. v When using pipe routing services (PRS), if a READ FORM # tries to read more bytes than are actually in the PRS pipe, the system purges all data in the PRS pipe and returns an error for the READ FORM #. v All pipes in IBM 4680 BASIC are temporary. A pipe is deleted when the last process that has access to the pipe closes it.
Copyright IBM Corp. 1985, 2003

171

The following program creates a pipe named newpipe that is 40 bytes long.
CREATE "pi:newpipe" a$ = "ABCDEFGHIJ" b% = 32767 c$ = "KLMNOPQRST" WRITE #5; a$, b%, c$ CLOSE 5 END AS 5 BUFFSIZE 40

The WRITE # statement writes delimited data to the pipe as shown in Figure 8.
newpipe "ABCDEFGHIJ",32767,"KLMNOPQRST"cr/lf Pipe length 40 bytes

Figure 8. Pipe With Delimited Data

The following example is similar to the preceding one. This example uses a WRITE FORM # statement to write data to the pipe. The variable D$ represents a format.string for the WRITE FORM # statement.
CREATE "pi:newpipe" A$ B% C$ D$ = = = = "ABCDEFGHIJ" 32767 "KLMNOPQRST" "C10,I2,C10" AS 5 BUFFSIZE 40

WRITE FORM D$; #5; A$, B%, C$ CLOSE 5 END

The WRITE FORM # statement writes data (that is not delimited) to the pipe as shown in Figure 9.
newpipe "ABCDEFGHIJFF7FKLMNOPQRST Pipe length 40 bytes

Figure 9. Pipe

Reading a File Record


You read the data from a disk file record into BASIC variables with the READ#, READ# LINE, READ FORM#, and the READ MATRIX statements. The READ# statement specifies the file to read by the I/O session number, the variables to assign the data to, the format for mapping the data record into the variables, and

172

IBM 4680 BASIC: Language Reference

whether or not to lock the record from use by other applications. See READ FORM # Statement on page 134 for a description of the format string items used with the READ FORM# statement. You can read sequential file records with the READ#, READ# LINE, and the READ MATRIX statements. The READ# LINE statement assigns all of the data in the current record to a single variable and the READ# statement assigns the individual fields of the record to the individual variables specified on the READ# statement. You can also use the READ FORM# for sequential files, but this is less practical because the records in sequential files usually vary in length. The READ MATRIX statement, which is used only for sequential files, allows you to read one-dimensional string arrays from the disk efficiently. READ MATRIX reads a sequential file record and parses the record into an array. You can read random file records with the same statements as sequential files. The READ FORM# is less practical for random file records because the fields of a random file may vary in length. You can only read keyed and direct file records with the READ FORM# statement. The format string items are necessary because there are no field or record delimiters within the data record. The reads of a sequential file normally proceed from the first record of the file to the last record of the file. By using the PTRRTN function, you can save the relative position of a record within a sequential file so that it can be used to reread from that position in the file. You use the POINT function to re-establish the saved relative position. You cannot issue a WRITE# statement after a POINT. The reads of a keyed, direct, and random file are for records at any position in the file. For direct and random files, the record number determines the relative position in the file when it is multiplied by the record length. For keyed files, the key is transformed into a relative sector within the keyed file and that sector and any sectors chained to that sector are scanned for the record.

Writing a File Record


You write the data to a disk file record from IBM 4680 BASIC variables with the WRITE#, WRITE FORM# (described as part of WRITE#), and WRITE MATRIX statements. You can also use the PRINT USING# in the store controller to write data to a disk record. See PRINT USING Statement on page 124. The WRITE statements are the recommended statements. The WRITE statement specifies the file to write by the I/O session number, the variables to get the data from, the format to map the data from the variables into the record data, and whether or not to unlock the record for use by other applications. The IBM 4680 or 4690 Operating System provides record integrity support to ensure that a record is written to the file correctly. The record integrity support depends on a record being no more than 512 bytes. The only exception to this is the WRITE MATRIX statement, which can write records larger than 512 bytes. You can use the WRITE MATRIX statement in both terminal and controller applications. Store controller applications write sequential file records with the WRITE# statement. The WRITE# statement assigns the individual variables of the statement to the fields in the record. String expressions are placed into the record with a
Chapter 8. Using Input and Output Devices and Pipes

173

starting quotation mark and ending quotation mark followed by a comma. Numeric expressions are placed into the record after being converted to their ASCII representation and are followed by a comma. The last expression in the record is followed by a carriage-return/line-feed instead of a comma. You can also use the WRITE FORM# in a store controller application to write a sequential record, but it is not convenient because the application must provide all of the sequential file record delimiters. When using a WRITE# statement to write a shared sequential file, the BUFFSIZE value in the OPEN statement should be as large as the largest record that you are going to write to that file. This value must be large enough to include the quotes enclosing the fields and the two bytes for the carriage return/line feed. Failure to do this can cause the record being written to split if another application writes to that file at the same time. Terminal applications write sequential file records with the WRITE MATRIX statement. The WRITE MATRIX statement assigns the string array elements to the fields in the record in the same way that a WRITE# statement assigns strings to a field. The records a WRITE MATRIX writes to a sequential file may not be in the same chronological sequence in which they were requested. Any application reading a sequential file should provide for this. You can write random file records with the WRITE# statement. You map the variables to the fields within a data record the same as you do for sequential files, except that you place a comma after the last field and the records are padded to fill the record size. You can also use the WRITE FORM# to write a random record, but this is not convenient because the application must provide all of the random file record delimiters. You can only write keyed and direct file records with the WRITE FORM# statement. The format string items are necessary because there are no field or record delimiters recorded with the data. The writes to a sequential file proceed from the first record of the file to the last record of the file. By using the PTRRTN function, you can save the relative position of a record within a sequential file to use at a later time to read from that position in the file. You cannot use PTRRTN for files that are opened, UNLOCKED, to WRITE. You use the POINT function to re-establish the saved relative position. You can also use a POINT statement to truncate a sequential file to zero size if the file is opened LOCKED or READONLY. See POINT Statement on page 120 for a description of the POINT statement. The writes of a keyed, direct, and random file are for records at any position in the file. For direct and random files, the record number determines the relative position in the file when it is multiplied by the record length. For keyed files, the key is transformed into a relative sector within the keyed file and that sector and any sectors chained to that sector are scanned for the record. If the record cannot be found in those sectors, it is added to the file.

174

IBM 4680 BASIC: Language Reference

Formatted Input/Output
Only the FORM # versions of the WRITE and READ statements are valid for direct and keyed files. Therefore, direct and keyed files contain no delimiting characters. The format you specify when you write to the files determines the organization of the data the files contain.

Formatted Output
Use the WRITE # statement to write formatted output to direct and keyed files, pipes, and device drivers. You can also use WRITE # to send output to the store controller printer. The general form of the WRITE # statement using a format.string is:
========= WRITE FORMformat.string; HOLD ============== ================ #I/O session number AUTOUNLOCK ,record number ;expression .... , .....

v format.string specifies the format of the data you are writing. Note: The items that you can include in the format.string are explained in the next section. HOLD is a flag that prevents data from being written to the disk until the process issues the next WRITE HOLD. HOLD is optional and is valid only in the store controller. I/O session number is the session number or file name specified in the CREATE statement that created the session or file. AUTOUNLOCK is a flag requesting to unlock the record after it is written. record number is the number of the record you are writing. expression contains the constants and variables to be written to the file, pipe, or device driver in the format specified by format.string.

v v v v

Write Form Format.String Items The format.string can contain any or all of the items in the following list. The format.string cannot be a null string. replication factor An integer constant that specifies the number of times other items in the format.string are to be used. The replication factor can range from 1 to 32767. Note: In the following explanations, the replication factor is represented as n preceding the items to which it is applicable. string constant A literal string to be written to the file or device driver. It is enclosed between slashes in the format.string and can be preceded by a replication factor. n/string/

Chapter 8. Using Input and Output Devices and Pipes

175

tab position value An integer constant that indicates the column number at which to begin writing the next unit of data with column 1 being the leftmost position. The tab position is always referenced to the leftmost column, not to the last column written to. Specify the tab position in the format.string with the letter T, followed by the number chosen. Tnumber lines-to-advance value An integer constant that indicates the number of line-feeds to send before writing the next unit of data. Lines to advance is valid only for the CR:, SJ:, and DI: stations. Specify the number of lines to advance in the format.string with the letter A, followed by the number chosen. The value can range from 1 to 255. Anumber number of characters to write from a string variable An integer constant that specifies the number of characters to write from a string variable, starting with the leftmost character. Specify the number of string-variable characters to write in the format.string with the letter C, preceded by a replication factor (optional), and followed by the number chosen. nCnumber integer-type specification An integer constant, always 1, 2, or 4, that specifies whether variables to be written are 1-, 2-, or 4-byte integers. Indicate the integer-type specification in the format.string with the letter I, preceded by a replication factor (optional), and followed by the number chosen. nInumber real variable field The letter R, optionally preceded by a replication factor, indicates that the corresponding data item to be written is a real variable. nR picture string A string of special characters and/or constants that specifies the appearance of data items to be written. The picture string in the WRITE # statement corresponds generally to the format.string used with a PRINT USING statement (see Formatted Printing on page 179 and the PRINT USING Statement on page 124 for a list of the special characters that you can use with the PRINT USING statement). The differences between picture-string special characters and PRINT USING special characters are: v The character 9 in a picture string specifies that a digit is to be printed in the current column, even if that digit is a leading zero. 9 has the same effect in a picture string that # has in a PRINT USING format.string, except that # suppresses leading zeros. v The & character (PRINT USING variable-length string indicator) is not allowed in a picture string. Notes: 1. A picture string within the format.string can be preceded by the replication factor and is indicated by:

176

IBM 4680 BASIC: Language Reference

nPIC(picture string). nPIC(...string...) is like the USING in PRINT. It is useful for converting real or integer variables to ASCII form. Special characters are used to represent format items. 2. Generally, lines-to-advance values and picture strings should not be written to direct and keyed files. Format.strings used to write to direct and keyed files should contain only those items allowed in the format.string of a READ FORM # statement. See Formatted Input/Output on page 175 and the READ FORM # Statement on page 134. For direct and keyed files, the length of the format.string (that is, the number of bytes of data it defines) must match the record length specified when the file was created or a runtime error is generated.

Examples
Example 1
Format.strings can be literal or can be assigned to string variables.
WRITE FORM "/Inventory Code: / T30 C4"; #1, 1; CODE$

The following example produces the same output as the preceding example:
FMT$="/Inventory Code: / T30 C4" WRITE FORM FMT$; #1, 1; CODE$

Both examples write the literal string Inventory Code: to record 1 of the file assigned to I/O session number 1. They tab to byte 30 in the record, and output the first four characters of CODE$.

Example 2
NAME1$="JONES" NAME2$="HAMMERS" M%=6 Y%=85 SALES=613.51 WRITE FORM "2C4 2I2 R"; #1, 1; NAME1$, NAME2$, \ M%, Y%, SALES

Assuming the program has created a direct file of record length 22 AS 1, the previous statements write record 1 to that file. Record 1 consists of the following bytes: v Four bytes representing the characters JONE v Followed by four bytes representing the characters HAMM v Followed by two bytes representing the integer 6 v Followed by 2 bytes representing the integer 85 v Followed by 10 bytes representing the real number 613.51.

Example 3
INTG = 00000010B WRITE FORM "PIC(INTG = ##)";#2;INTG

Results in:
INTG = 2 WRITE FORM "PIC(INTG = 99)";#2;INTG

Chapter 8. Using Input and Output Devices and Pipes

177

Results in:
INTG = 02

Formatted Input
Use the READ FORM # statement to do formatted reads of sequential files, random files, direct files, keyed files, pipes, and device drivers. The general form of the READ FORM # statement is:
READ FORMformat.string;#I/O session number ====================================== ============ ,record number AUTOLOCK KEYkeyvalue ,variable ... , .....

v format.string specifies the format of the data to be read. Note: The items you can include in the format string are explained in READ FORM Format.String Items. I/O session number is the session number or file name specified in the CREATE statement that created the session or file. AUTOLOCK is a flag specifying that the record is to be locked before it is read. record number is the record number of the record to be read. keyvalue is a string that must match the keyvalue specified when a keyed file is created. variable(s) contains the data read from the file, pipe, or device driver.

v v v v v

Read Form Format.String Items The format.string can contain any or all of the items in the following list. The format.string cannot be a null string. replication factor An integer constant that specifies the number of times other items in the format.string are to be used. The replication factor can range from 1 to 32767. Note: In the following explanations, the replication factor is represented as n preceding the items to which it is applicable. tab position value An integer constant that indicates the column number to begin reading the next unit of data. The tab position is always relative to column 0, not to the last column read from. Specify the tab position in the format.string with the letter T, followed by the number chosen. Tnumber number of characters to read into a string variable An integer constant that specifies the number of characters to be read into a string variable in the expression list. Specify the number of characters to read into the string variable in the format.string with the letter C, preceded by a replication factor (optional), and followed by the number chosen.

178

IBM 4680 BASIC: Language Reference

nCnumber integer-type specification An integer constant, always 1, 2, or 4, that specifies whether integers to be read are 1-, 2-, or 4-byte integers. The integer-type specification is specified in the format.string by the letter I, optionally preceded by a replication factor, and followed by the number chosen. nInumber real variable field The letter R, optionally preceded by a replication factor, indicates that the corresponding data to be read is to be assigned to a real variable: nR For direct and keyed files, the length of the format.string (that is, the number of bytes of data it defines) must match the record length specified when the file was created or a runtime error is generated.

Examples
READ FORM "2C4 2I2 R"; #1, 1; NAME1$, NAME2$, \ M%, Y%, SALES

Assuming the program has created a direct file as I/O session 1 and of record length 22, the foregoing statement reads record 1 of that file. The first four bytes of the record are assumed to represent ASCII characters and are assigned to the string variable NAME1$. The next four bytes are also treated as ASCII characters and are assigned to the string variable NAME2$. The next two bytes are treated as a two-byte integer and assigned to the integer variable M%. The next two bytes are assigned to the integer variable Y%. The last ten bytes are assigned to the real variable SALES.

Tvalue Example
The following statement skips over the first four bytes of the record, then assigns the next eight bytes to two four-character string variables, SALESP.ONE$ and SALESP.TWO$:
READ FORM "T5 2C4"; #1, 1; SALESP.ONE$, SALESP.TWO$

Assume file data is ABCDEFG. The following statements show the use of Tvalue:
READ FORM "C3,C4";A$,B$ READ FORM "T4,C4";B$ A$ = "ABC", B$ = "DEFG" B$ = "DEFG"

Formatted Printing
The PRINT USING statement allows you to specify special formats for output. You can direct formatted data to a display or printer using the CONSOLE and LPRINTER statements. The PRINT USING # variation directs formatted output to a disk file. The two forms the PRINT USING statement can take are:

Chapter 8. Using Input and Output Devices and Pipes

179

Form 1 PRINT USINGformat.string;expression .... , ..... Form 2 PRINT USINGformat.string;#I/O session number =================== ;expression ,record number .... , .....

The format.string is a model for the output. A format.string contains format items (specifications) and literal data. Format.strings cannot be null string expressions. Table 12 shows characters that have special meanings in format.strings.
Table 12. Special Characters in Format.Strings Character ! & / # ** $$ . ^ , \ Meaning single-character string field variable-length string field fixed-length string field delimiter digit position in numeric field asterisk fill in numeric field float currency symbol in numeric field decimal point position in numeric field leading or trailing sign in numeric field exponential position in numeric field place thousands separator every third digit before decimal point symbol escape character

The expression list explains which variables hold the data to format. Separate variables with commas or semicolons. A comma does not cause automatic tabbing as it does with unformatted printing. The PRINT USING statement matches each variable in the list with a data field in the format.string. If there are more expressions than there are fields in the format.string, execution resets to the beginning of the format.string. While searching the format.string for a data field, the type of the next expression in the list, either string or numeric, determines which data field to use. IBM 4680 BASIC rounds all constants to 18 digits of precision and maintains 18 digits internally.

String Character Fields


Specify a one-character string data field with an exclamation point, !. The PRINT USING statement prints the first character of the next item in the expression list. For example:
F.NAME$="Lynn":M.NAME$ = "Marion":L.NAME$= "Kobi" PRINT USING "!. !. &"; F.NAME$,M.NAME$,L.NAME$

180

IBM 4680 BASIC: Language Reference

Results in:
L. M. Kobi

In the preceding example, the PRINT USING statement treats the period as literal data.

Fixed-Length String Fields


Specify a fixed-length string field of more than one position with a string of characters enclosed between a pair of slashes. The width of the field is equal to the number of characters between the slashes plus two. Place any characters between the slashes to serve as fillers. The PRINT USING statement ignores fill characters for fixed-length string fields. A string expression from the expression list is left-justified in the fixed field and, if necessary, padded on the right with blanks. The PRINT USING statement truncates a string longer than the data field on the right. For example:
for1$ = "The part required is /....5....0....5/" part.descrp$ = "globe valve, angle" PRINT USING for1$; part.descrp$

Results in:
The part required is globe valve, angl

Using periods and numbers between the slashes makes it easy to verify that the data field is 17 characters long. Periods and numbers do not affect the output.

Variable-Length String Fields


Specify a variable-length string field with an ampersand (&). This results in a string output exactly as defined. For example:
COMPANY$ = "SMITH INC." PRINT USING "& &"; "THIS REPORT IS FOR",COMPANY$

Results in:
THIS REPORT IS FOR SMITH INC.

The following example shows how a string can be right-justified in a fixed-length string field using a variable-length string field:
FLD.S% = 20 BLK$ = " " PHONE$ = "408-649-3896" PRINT USING "\#&"; RIGHT$(BLK$ + PHONE$, FLD.S%)

Results in:
# 408-649-3896

The preceding example uses the # as a literal character following the escape character (\). A # can also indicate a numeric data field.

Chapter 8. Using Input and Output Devices and Pipes

181

Numeric Data Fields


Specify a numeric data field with a pound sign, #, to indicate each digit required in the resulting number. You can also include one decimal point in the field. Values are rounded to fit the data field. (See ROUND Function on page 145.) Leading zeros are replaced with blanks. When the number is negative, the PRINT USING statement prints a minus sign to the left of the most significant digit. A single zero prints to the left of the decimal point for numbers less than one if you provide a position in the data field. For example:
X = 123.7546 Y = -21.0 FOR$ = "####.#### ###.# PRINT USING FOR$; X, X, X PRINT USING FOR$; Y, Y, Y

###"

Results in:
123.7546 -21.0000 123.8 -21.0 124 -21

Tell the PRINT USING statement to print numbers in exponential format by appending one to four carets (^) to the end of the numeric data field. For example:
X = 12.345 PRINT USING "#.###^^ "; X, -X

Results in:
1.235E 01 -.123E 02

The PRINT USING statement reserves four positions for the exponent regardless of the number of carets (^) used in the field. If one or more commas appear embedded in a numeric data field, the number prints with a comma preceding each group of three digits to the left of the decimal point. For example:
PRINT USING "##,### "; 100, 1000, 10000

Results in:
100 1,000 10,000

The PRINT USING statement includes each comma that appears in the data field in the width of the field. You need only one comma to obtain embedded commas in the output. However, placing each comma in the data field at the specified position clarifies the formatting statement. For example, the following data fields produce the same results, but the width of the first field allows only nine output digits. The second field allows ten digits.
#,######## #,###,###,###

Commas do not print if you use the exponent option. In this case, the PRINT USING statement treats commas as pound signs, #.

182

IBM 4680 BASIC: Language Reference

You can use asterisk filling in a numeric data field by appending two asterisks to the beginning of the data field. You can float a dollar sign by appending two dollar signs to the beginning of the data field. Use the OPTION statement to change the dollar sign currency symbol. (See OPTION Statement on page 118.) Do not use the exponential format with either asterisk filling or floating dollar signs. The PRINT USING statement includes a pair of asterisks or dollar signs in the count of digit positions available for the field. The asterisks or dollar signs appear in the output if there is enough space. For example, to float a dollar sign in front of a 3-digit number, you must specify $$999. These five characters output one dollar sign followed by the number. The dollar sign does not print if the number is negative. For example:
COST = 8742937.56 PRINT USING "**##,######.## PRINT USING "$$##,######.## "; COST, -COST "; COST, -COST

Results in:
**8,742,937.56 $8,742,937.56 *-8,742,937.56 -8,742,937.56

The PRINT USING statement sends a number with a trailing sign instead of a leading sign if the last character in the data field is a minus sign. A blank replaces the minus sign in the output if the number is positive. For example:
PRINT USING "###- ###^^^^-"; 10, 10, -10, -10

Results in:
10 100E-01 10- 100E-01-

The PRINT USING statement fixes the sign position as the next output position if a minus sign is the first character in a numeric data field. If the number is positive, a blank prints instead of the minus sign. For example:
PRINT USING "-#### "; 10, -10

Results in:
10 10

If a number does not fit in a numeric data field without truncating digits before the decimal point, a percent sign, %, precedes the number in the standard format. For example:
X = 132.71 PRINT USING "##.# ###.#"; X,X

Results in:
% 132.71 132.7

Escape Character
You can use a special format.string character as literal data in a format data field with the escape character. A backslash (\), signals the PRINT USING statement to treat the next consecutive character as a literal character. In the following example, a pound sign (#), can precede a number:
Chapter 8. Using Input and Output Devices and Pipes

183

ITEM.NUMBER = 31 PRINT USING "THE ITEM NUMBER IS \###"; ITEM.NUMBER

Results in:
THE ITEM NUMBER IS #31

Two consecutive backslashes cause one backslash to print as a literal character. An escape character cannot be the last character in a format.string.

Store Controller Input/Output Device Drivers


Three standard I/O devices are used with the store controller: the keyboard, the display, and the printer. This section identifies the statements and functions you can use to operate each device.

Store Controller Keyboard


You can use the following statements and functions to interact with the keyboard: ASSIGNKEY Statement: Use the ASSIGNKEY statement to assign a command string to a specified programmable function key. CONCHAR% Function: The CONCHAR% function reads a character from the keyboard and returns the decimal ASCII representation of that character. CONSTAT% Function: Use the CONSTAT% function to determine if the display has a ready status. Ready status means a character has been entered at the keyboard but has not been read by the program. INKEY Function: The INKEY function waits for a character to be entered at the console keyboard and then returns the ASCII decimal value equal to that character. INPUT Statement: Use the INPUT statement to input data from the keyboard during program execution. INPUT assigns the data to variables. INPUT LINE Statement: The INPUT LINE statement inputs one line of data from the keyboard and assigns it to a string variable.

Store Controller Display


You can use the following statements to communicate with the display: CLEARS Statement: Use the CLEARS statement to clear the display screen of any information related to a specified I/O session. FUNCTIONKEY Statement: Use the FUNCTIONKEY statement to turn on or off the one-line function key definitions that appear at the bottom of the screen. LOCATE Statement: Use the LOCATE statement to set the current character location and the visibility of the cursor at the current character location. PRINT Statement: Use the PRINT statement to direct data to the display when a CONSOLE statement is in effect.

184

IBM 4680 BASIC: Language Reference

Store Controller Printer


You can use the following statements and functions to communicate with the printer (PRN:). Note: When the print spooler is installed, you must open the printer as a device, write to it, and then close it before printing will start. (For more information on the print spooler, see the Print command in the IBM 4680 Store System: Users Guide or the IBM 4690 OS Version 3: Users Guide.) OPEN Statement: Use the OPEN statement to gain access to the printer. Specify PRN: within quotation marks in the OPEN statement after the OPEN reserved word. WRITE # Statement: Use the WRITE # statement to send data to the printer. LPRINTER Statement: Use the LPRINTER statement to direct program output to the printer instead of the console. PRINT Statement: Use the PRINT statement to send data to the printer when an LPRINTER statement is in effect. TAB Function: Use the TAB function to move the printer print head to a specified column number. CLOSE Statement: Use the CLOSE statement to end communication with the store controller printer. CONSOLE Statement: Use the CONSOLE statement to direct program output to the display and to close the printer that was opened for exclusive use by the LPRINTER statement.

Store Controller/Host Communications


IBM 4680 BASIC supports the following three types of store controller/host communications: v System Network Architecture (SNA) Communication v Binary Synchronous (BSC) Communication v Asynchronous (ASYNC) Communication. IBM 4680 BASIC operates with host communication through link and session drivers. These drivers are software components that enable communication between the host processor and the system software. Table 13 defines the various link and session drivers in the IBM 4680 or 4690 Store System.
Table 13. Reserved Link Drivers Name LINK SNA LINK BSC LINK ASYNC SESSION Description SNA host link driver BSC host link driver ASC host link driver SNA SESSION driver

Chapter 8. Using Input and Output Devices and Pipes

185

System Network Architecture Communications


You can use the following nine statements and functions to program System Network Architecture (SNA) communication: OPEN LINK Statement Use the OPEN LINK statement to enable an SNA communications link.
============== OPEN LINK SNAcomm.name ASlink.number ,,host

comm.name A string variable or constant that identifies the link name assigned during system configuration. host A string constant of 1 to 6 alphanumeric characters that identifies the host XID sequence. The constant must be a valid hexadecimal constant. This ID overrides the ID specified during system configuration.

link.number A 2-byte integer variable or constant with a value ranging from 1 to 99. OPEN SESSION Statement Use OPEN SESSION to open a communications session on the specified SNA link.

OPEN SESSIONsession.nameONlink.numberBINDVAR bind.varASsession.number

session.name A string variable or constant that identifies the session name assigned during system configuration. link.number A 2-byte integer or variable constant with a value ranging from 1 to 99 that identifies where to bind the session. This number must match the link number specified in the OPEN LINK statement. bind.var A string variable to hold bind information upon completion of the OPEN SESSION statement. If bind.var is a null string, the OPEN SESSION ends when all control blocks are allocated. A READ # is then used to obtain the BIND request sent from the host processor. This is provided because certain host applications start an INIT-SELF command from the store controller. When an OPEN SESSION is issued and a BIND has not been received from the host processor, an INIT-SELF command is automatically sent to the host processor if bind.var is not a null string. session.number A 2-byte integer variable or constant with a value ranging from 1 to 99. WAIT Statement Use the WAIT statement to wait for a change in the status flags associated with the open SNA session. Use the EVENT% function to retrieve the session number that satisfied the wait.

186

IBM 4680 BASIC: Language Reference

============= WAITsession.number ;timeout.val ,number .........

session.number The same 2-byte integer variable or constant assigned to the session in the OPEN SESSION statement. number An I/O session number assigned to another session or pipe. timeout.val A 4-byte integer variable or constant that specifies the number of milliseconds to wait for a change in the status flags or for data to become available from a pipe. READ # LINE Statement Use the READ # LINE statement to read data from the open SNA session. All data is read into a specified string variable.
READ#session.number;LINEstring.var

session.number The same 2-byte integer variable or constant assigned to the session in the OPEN SESSION statement.

string.var A string variable to contain the input data. This data is not translated by the host communications driver. If EBCDIC data is transmitted by the host processor, string.var will contain EBCDIC data. WRITE # Statement Use the WRITE # statement to write data to the open SNA session. You can optionally specify a format.string. The SNA driver buffers all data written to the session. Completion of a WRITE # statement does not guarantee that data was transmitted to the host processor. Your application program is responsible for checkpointing, positive response, error recovery, and any data translation you want.
WRITE #session.number;data.var FORMformat.string; ... , ....

format.string A string constant or string variable representing less than or equal to 518 bytes.

session.number The same 2-byte integer variable or constant assigned to the session in the OPEN SESSION statement.

data.var A variable or constant that identifies the data to be written. Numeric


Chapter 8. Using Input and Output Devices and Pipes

187

values are first converted to ASCII characters. If the application sends EBCDIC, the application must perform appropriate conversions and place the data in a string. Delimiting quotation marks for string values are not written. The runtime library does not insert delimiters. The total length of data written to the SNA driver must not exceed 518 bytes. GETLONG Function Use the GETLONG function to obtain status information from an open SNA session.
i4 = GETLONG ( session.number )

i4 A 4-byte integer that holds the status information returned by GETLONG. session.number The same 2-byte integer variable or constant assigned to the session in the OPEN SESSION statement. The integer represents information in the form: PPF1F2F3. PP, F1, F2, and F3 each represent one of the four bytes. Byte PP represents PUTLONG flags and can be ignored. Byte F1 represents status information as follows: bit 0 (hex 01) = 1 if the SNA driver has received an ACTLU request. bit 1 = 1 if the SNA driver has received a BIND request. bit 2 = 1 if INIT_SELF has been sent. bit 3 = 1 if TERM_SELF has been sent. bit 4 = 1 if the SNA session is active. bit 5 = 1 if the SNA driver has received an UNBIND request. bit 6 = 1 if the SNA driver has received a pacing response. bit 7 = 1 if the SNA driver has received a pacing request. Byte F2 represents status information as follows: bit 0 (hex 01) = 1 if a LINK/SESSION error has occurred. bit 1 = 1 if a BIND response is required. bit 2 = 1 if the driver is waiting for the link or session to close. bit 3 = 1 if an OPEN SESSION is in progress. bit 4 = 1 if a CLOSE SESSION is in progress. bit 5 = 1 if the SNA session is open. bit 6 = 1 if data is available to be read. bit 7 = 1 if a write buffer is free. Byte F3 represents status information as follows: bit 0 (hex 01) = 1 if the SNA driver has received a STSN. bit bit bit bit bit bit bit 1 2 3 4 5 6 7 = = = = = = = 1 1 1 1 1 0 0 if the SNA driver has received a CLEAR. if the SNA driver has received a QUIESCE. if the SNA driver has received an SDT. if a read of SNA session is outstanding. if a write of SNA session is outstanding. RESERVED RESERVED

Use the GETLONG function to obtain status information from an open SNA link.

188

IBM 4680 BASIC: Language Reference

i4 = GETLONG (

link.number )

i4

A 4-byte integer that holds the status information returned by GETLONG.

link.number The same 2-byte integer variable or constant assigned to the link in the OPEN LINK statement. The 4-byte integer represents information in the form L1L2RRRR. L1, L2, RR, and RR each represent one of the four bytes. The bytes RRRR are reserved for SNA services use. .Byte L1 represents status information as follows: bit 0 (hex01) = 1 if an ACTPU for the link has been received from the host. (Sessions can now be activated.) bit 1 = 1 if a DACTPU request has been received from the host. (All applications must close any sessions and links that have been active.) bit 2 = 1 if an ACTIVE host link has been established. bit 3 = 1 if a LINK error has been detected. (The link will have to be closed until the error is corrected.) bit 4 = 1 if C&SM support is active on this link. bit 5 = 1 if an OPEN LINK request is pending. bit 6 = x Reserved for SNA services use. bit 7 = x Reserved for SNA services use. Byte L2 represents status information as follows: bit 0 (hex01) = 1 if a read to the SDLC or BSC support is outstanding. bit 1 = x Reserved for SNA services use. bit 2 = x Reserved for SNA services use. bit 3 = x Reserved for SNA services use. bit 4 = x Reserved for SNA services use. bit 5 = x Reserved for SNA services use. bit 6 = x Reserved for SNA services use.
Chapter 8. Using Input and Output Devices and Pipes

189

bit 7 = x Reserved for SNA services use. PUTLONG Statement Use the PUTLONG statement to make requests to the SNA driver.
PUTLONG session.number , i4

session.number The same 2-byte integer variable or constant assigned to the session in the OPEN SESSION statement. i4 A 4-byte integer that represents the requests to the SNA driver.

The integer represents information in the form: 000000FF. 00, 00, 00, and FF each represent one of the four bytes. The first three bytes, 000000, are reserved for system use. Byte FF represents flags with the following meanings: bit 0 (hex 01) = 1 send INIT_SELF bit 1 = 1 send TERM_SELF bit 2 = 1 send RQR bit 3 = 0 RESERVED bit 4 = 0 RESERVED bit 5 = 0 RESERVED bit 6 = 0 RESERVED bit 7 = 0 RESERVED Testing the FF Byte For both GETLONG and Putlong, testing of the FF byte (and also the SS, MM and PP bytes for GETLONG) is usually done with a 4-byte integer. The mapping is inverted if a hexadecimal constant is being used, to be PPMMSSFF, where the variables have the same meaning. For example, to set DTR on, the constant to use is x00000021 and the decimal value is 33. A test for data available is x00000100 or decimal 256. The core function for communications with the ASYNC driver, after the open has completed and before the close is to be issued, is: 1. Issue GETLONG to ASYNC a. Error - close. b. Parse status in order of importance: Line Active (x00000800 ,2048) Time Out x00001000 ,4096) Data Available (x00000100 ,256) XOFF Host (x00000400 ,1024)

190

IBM 4680 BASIC: Language Reference

XOFF Controller (x00002000 ,8192) Write Buffer Available (x00000200 ,512) Write Buffer Empty (x00004000 ,16384) Open Received (x00008000 ,32768) 2. Act on returned status as follows: Line Active (if off) Close unless open is pending Time Out User determined action Data Available Issue Read XOFF Host Issue wait for status change XOFF Controller User determined action Write Buffer Available Issue Write if wanted Write Buffer Empty Issue Write if wanted Nothing to act on Issue Wait 3. Step 2 action complete: Close Issued Processing Complete Read Complete Continue at Step 1 Wait Complete Continue at Step 1 Write Complete Continue at Step 1 Putlong Complete Continue at Step 1 If only reads are being done, the core function for communications with the ASYNC driver, after the open has completed and before the close is to be issued, is: 1. Issue GETLONG to ASYNC a. Error - close. b. Parse status in order of importance: Line Active (x00000800 ,2048) Time Out (x00001000 ,4096) Data Available (x00000100 ,256) Open Received (x00008000 ,32768) 2. Act on returned status as follows:

Chapter 8. Using Input and Output Devices and Pipes

191

Line Active (if off) Close unless open is pending Time Out User determined action Data Available Issue Read Nothing to act on Issue Wait 3. Step 2 action complete: Close Issued Processing Complete Read Complete Continue at Step 1 Wait Complete Continue at Step 1 RESUME Statement Use the RESUME statement to recover from an error associated with an SNA link or session, except for errors associated with a WRITE # statement. Use the ON ASYNC ERROR CALL statement for errors associated with a WRITE # statement.
RESUME RETRY label

RETRY Enables the statement that caused the error to execute again. label An IBM 4680 BASIC label local to the program module that identifies a statement to receive control if an error occurs.

CLOSE Statement Use the CLOSE statement to close an SNA link or session. A link cannot be closed if there are any active sessions bound to the link unless you specify the QUIESCE reserved word in the CLOSE statement.
========= CLOSE number QUIESCE

QUIESCE Quiesces all active sessions on the link for this application. number The session or link number.

Binary Synchronous Communications


You can use the following seven statements and functions to program Binary Synchronous Communications (BSC): OPEN LINK Statement Use the OPEN LINK statement to enable a BSC link.
========== OPEN LINK BSCcomm.name ASlink.number ,,host

192

IBM 4680 BASIC: Language Reference

comm.name A string variable or constant that identifies the link name assigned during system configuration. host A string variable or constant 2 to 8 alphanumeric characters long that identifies the host ID sequence. This ID overrides the ID specified during system configuration.

link.number A 2-byte integer variable or constant with a value ranging from 1 to 99. WAIT Statement Use the WAIT statement to wait for a change in the status flags associated with the open BSC link. Use the EVENT% function to retrieve the session number (or link number) that satisfied the wait.
============= WAITlink.number ;timeout.val ,number ...........

link.number The same 2-byte integer variable or constant assigned to the link in the OPEN LINK statement. number An I/O session number assigned to another link or pipe. timeout.val A 4-byte integer variable or constant that specifies the number of milliseconds to wait for a change in the status flags or for data to become available from a pipe. READ # LINE Statement Use the READ # LINE statement to read data from the open BSC link. All data is read into a specified string variable.
READ#link.number;LINEstring.var

link.number The same 2-byte integer variable or constant assigned to the link in the OPEN LINK statement. string.var A string variable to hold the input data. WRITE # Statement Use the WRITE # statement to write data to the open BSC session. You can optionally specify a format.string. The BSC driver buffers all data written to the session. Completion of a WRITE # statement does not mean that data was transmitted to the host processor. Your application program is responsible for checkpointing, positive response, and error recovery. (You can configure your line so that transient line errors are retried and recovered from automatically.)
WRITE #link.number;data.var FORMformat.string .... , .....

Chapter 8. Using Input and Output Devices and Pipes

193

format.string A string constant or string variable representing less than or equal to 518 bytes. link.number The same 2-byte integer variable or constant assigned to the link in the OPEN LINK statement. data.var A string variable or constant that identifies the data to be written. If the application sends EBCDIC data, the application must perform appropriate conversions and place the data in a string. Delimiting quotation marks for string values are not written. The runtime library does not insert delimiters. The first character in the string must be a special Write Control Character. The total length of data written to the BSC driver must not exceed 518 bytes. GETLONG Function Use the GETLONG function to obtain status information from an open BSC link.
i4=GETLONG(link.number)

i4

A 4-byte integer that holds the status information returned by GETLONG.

link.number The same 2-byte integer variable or constant assigned to the link in the OPEN LINK statement. The integer represents information in the form: 000000SS. 00, 00, 00, and SS each represent one of the four bytes. The three most significant bytes, 000000, are reserved for system use. Byte SS represents status information as follows: bit 0 (hex 01) = 1 if data is ready to be read. bit 1 = RESERVED bit 2 = RESERVED bit 3 = 1 if the link is active. bit 4 = RESERVED bit 5 = RESERVED bit 6 = RESERVED bit 7 = RESERVED RESUME Statement Use the RESUME statement to recover from an error associated with a BSC link, except for errors associated with a WRITE # statement. Use the ON ASYNC ERROR CALL statement for errors associated with a WRITE # statement.
======= RESUMERETRY label

RETRY The RETRY option is ignored by the BSC host communication driver. label An IBM 4680 BASIC label local to the program module that identifies a statement to receive control if an error occurs.

194

IBM 4680 BASIC: Language Reference

CLOSE Statement Use the CLOSE statement to close a BSC link.


CLOSEnumber

number The link number.

Asynchronous Communication
You can use the following statements and functions to program asynchronous communications: OPEN LINK Statement Use the OPEN LINK statement to enable an ASYNC communication link.
================ OPEN LINK ASYNCcomm.name ASlink.number ,tele.number BUFFSIZEbuff.size

comm.name A string variable or constant that identifies the line name assigned during system configuration. tele.number A string variable or constant of 1 to 33 alphanumeric characters that identifies the telephone number of an autodial network. This telephone number overrides any telephone number specified during system configuration. link.number A 2-byte integer variable or constant with a value ranging from 1 to 64. buff.size A 2-byte integer variable or constant with value ranging from 1 to 518 that indicates the largest message the driver can receive, and the largest amount of data the runtime can buffer. WAIT Statement Use the WAIT statement to wait for a change in the status flags associated with the open line. Use the EVENT% function to retrieve the session number that satisfied the wait.
============= WAITlink.number ;timeout.val ,number ...........

link.number The same 2-byte integer variable or constant assigned to the line in the OPEN LINK statement. number An I/O session number assigned to another link or pipe.

Chapter 8. Using Input and Output Devices and Pipes

195

timeout.val A 4-byte integer variable or constant that specifies the number of milliseconds to wait for a change in the status flags or for data to become available from a pipe. READ # LINE Statement Use the READ # LINE statement to read data from the open ASYNC line. All data is read into a specified string variable.
READ#link.number;LINEstring.var

link.number The same 2-byte integer variable or constant assigned to the line in the OPEN LINK statement. string.var A string variable to hold the input data. WRITE # Statement Use the WRITE # statement to write data to the open ASYNC line. You can optionally specify a format.string. The ASYNC driver buffers all data written to the session. Completion of a WRITE # statement does not mean that data was transmitted to the host processor. Your application program is responsible for checkpointing, positive response, and error recovery.
WRITE #link.number;data.var FORMformat.string ... , .....

format.string A string constant or string variable representing less than or equal to 518 bytes. link.number The same 2-byte integer variable or constant assigned to the line in the OPEN LINK statement. data.var A variable or constant that identifies the data to be written. GETLONG Function Use the GETLONG function to obtain status information from an open ASYNC line.
i4 = GETLONG(link.number)

i4

A 4-byte integer that holds the status information returned by GETLONG.

link.number The same 2-byte integer variable or constant assigned to the line in the OPEN LINK statement. The integer represents information in the form: FFSSMMPP. FF, SS, MM, and PP each represent one of the four bytes. Byte FF represents status information as follows: bit 0 (hex 01) = 1 data terminal ready. bit 1 = 1 to set request to send. bit 2 = 1 if out 1

196

IBM 4680 BASIC: Language Reference

bit 3 = reserved. bit 4 = 1 if loop bit 5 = 1 if the modem control register was set with PUTLONG. bit 6 = 1 if a send XOFF or XON was set with PUTLONG. bit 7 = 0 if a send XON was set with PUTLONG. bit 7 = 1 if a send XOFF was set with PUTLONG. Byte SS represents status information as follows: bit 0 (hex 01) = 1 if data is ready to be read. bit 1 = 1 if a write buffer is available. bit 2 = Reserved. bit 3 = 1 if the line is active (if direct attached, CTS is active). bit 4 = 1 if a timeout has occurred. bit 5 = Reserved. bit 6 = 1 if write buffer is empty. bit 7 = 1 if an open request is received. Byte MM contains the contents of the modem status register. Byte PP is the port number (1 or 2). PUTLONG Statement Use the PUTLONG statement to make requests to the ASYNC driver.
PUTLONGlink.number,i4

link.number The same 2-byte integer variable or constant assigned to the line in the OPEN LINK statement. i4 A 4-byte integer that represents the requests to the ASYNC driver.

The integer represents information in the form: 000000FF. 00, 00, 00, and FF each represent one of the four bytes. The first three bytes, 000000, are reserved for system use. Byte FF represents flags with the following meanings: bit 0 (hex 01) = 1 to set data terminal to ready. bit 1 = 1 to set a request to send. bit 2 = 1 to set out 1. bit 3 = reserved. bit 4 = 1 to set loop. bit 5 = 1 to set the modem control register. bit 6 = 1 to send XOFF or XON (see bit 7). bit 7 = 0 to send XON. bit 7 = 1 to send XOFF. RESUME Statement Use the RESUME statement to recover from an error associated with an ASYNC line, except for errors associated with a WRITE # statement. Use the ON ASYNC ERROR CALL statement for errors associated with a WRITE # statement.
======= RESUMERETRY label

RETRY Enables the statement that caused the error to execute again. label An IBM 4680 BASIC label local to the program module that identifies a statement to receive control if an error occurs.
Chapter 8. Using Input and Output Devices and Pipes

197

CLOSE Statement Use the CLOSE statement to close an ASYNC link.


CLOSEnumber

number The link number.

Terminal Input/Output Device Drivers


Various I/O devices can be attached to terminals. Each I/O device is controlled by a device driver. A device driver is a software component of the operating system that allows communication between the device and the terminal application. Table 14 lists the I/O devices that can attach to a terminal. The following sections describe the statements supported by each I/O device driver. See the IBM 4680 Store System: Programming Guide or the IBM 4690 Store System: Programming Guide for additional information about programming the I/O device drivers.
Table 14. Reserved Device Names Name ANDISPLAY: ANDISPLAY2: ANDISPLAY3: CDRAWER: COIN: IOPROC: MSR: CR: SJ: DI: SCALE: SDISPLAY: SERIAL I/O TONE: TOTRET: VDISPLAY: VDISPLAY2: Description First 2x20 display Second 2x20 display Third 2x20 display (4690 only) Cash Drawer (alarm) Coin Dispenser I/O processor (keyboard, scanner, OCR, magnetic wand) Magnetic stripe reader Customer Receipt station (printer) Summary Journal station (printer) Document Insert station (printer) Scale Shopper display Serial communications Tone Totals retention First video display Second video display

2x20 Display Driver


Use the following statements to communicate with the alphanumeric or the operator 2x20 display drivers. OPEN Statement Use the OPEN statement to gain access to the 2x20 display driver. OPEN sets the current character location to (1,1). One of these can be the system display.
OPEN"ANDISPLAY:"ASnumber

198

IBM 4680 BASIC: Language Reference

OPEN"ANDISPLAY2:"ASnumber OPEN"ANDISPLAY3:"ASnumber

Note: ANDISPLAY3 is supported by 4690 OS only. number A unique number to assign to the 2x20 session (I/O session number). An I/O session number can be any numeric expression that evaluates to an integer ranging from 1 to 99. LOCATE # Statement Use the LOCATE # statement to set the current character location where to WRITE to or READ from the 2x20 display.
LOCATE#number;row.value,column.value

number The I/O session number assigned to the 2x20 display in the OPEN statement. row.value A 2-byte integer or constant having the value of 1 or 2 indicating on which row the next characters appear. column.value A 2-byte integer or constant having the value of 1 to 20 indicating on which column the next characters appear. CLEARS Statement Use the CLEARS statement to clear the 2x20 display.
CLEARSnumber

number The I/O session number assigned to the 2x20 display in the OPEN statement. WRITE # Statement Use the WRITE # statement to display data on the 2x20 display. You can optionally specify a format.string. If the number of characters specified in the WRITE # statement is greater than the number of characters remaining on the current row of the display, the data extends (wraps around) to the next row. Row 1 wraps to row 2, and row 2 wraps to row 1. Each write operation increments the current character location (initially set to 1,1) by the number of bytes written. Note: If the first byte of a double bite character falls on the last column row 1 and the second byte wraps to the next row, the entire character is written to the next row. If the first byte of a double byte character is is at the end of the last row of the display, the character is truncated.
WRITE #number;data.var FORMformat.string; ...,...

format.string A string constant or variable. The number of bytes represented by the string must be 40 or less.

Chapter 8. Using Input and Output Devices and Pipes

199

number The I/O session number assigned to the 2x20 display in the OPEN statement. data.var A string variable or a constant. GETLONG Function Use the GETLONG function to get status information from the 2x20 display driver.
i4 = GETLONG(number)

i4

A 4-byte integer that represents the driver status.

number The I/O session number assigned to the 2x20 display in the OPEN statement. The integer represents information in the form: 00SSCCRR. 00, SS, CC, and RR each represent one of the four bytes. Byte 00 provides display information. The high order bits (4-7) identify the display type as follows: 0x - 2x20 Alphanumeric Display 2x - Multifunction Keyboard LCD Display 3x - LCD Display (Flagpole mounted) 6x - VFD II, Single-Sided Display 7x - VFD II, Double-Sided Display The low order bits (bits 0-3) identify the code page the display has been set to use. x0 - US/European character set based on code page 437 x1 - Katakana x2 - Code page 858 (Multilingual) x3 - Code page 852 (Central Europe) x4 - Code page 855 (Cyrillic) x5 - Code page 857 (Turkey) x6 - Code page 862 (Israel) x7 - Code page 863 (Canadian French) x8 - Code page 864 (Arabic) x9 - Code page 865 (Nordic) xA - Code page 866 (Cyrillic - Russia) xB - Code page 869 (Greece) Note: Not all displays can be set to use an internal code page. An x0 value indicates that a translate table, which is determined by the language selection when the system is set up, is being used to provide the appropriate code page. Byte SS is set to 24H if the 2x20 display is supported by the alphanumeric display driver. Byte SS is set to 20H if the 2x20 display driver is supported by the operator display driver. Byte SS is set to 2AH if the 2x20 display driver is supported by the APA display driver. Byte CC is the current column (1 - 20). Byte RR is the current row (1 or 2).

200

IBM 4680 BASIC: Language Reference

READ FORM # Statement Use the READ FORM # statement to read data from the 2x20 display buffer. Each read operation increments the current character location (initially set to 1,1) by the number of bytes read.
READ FORMformat.string;#number;data.var .... , ...

format.string A string constant or variable. The number of bytes represented by the string must be 40 or less. number The I/O session number assigned to the 2x20 display in the OPEN statement. data.var A string variable or a constant. RESUME Statement Use the RESUME statement to recover from an error associated with the 2x20 display device.
======= RESUMERETRY label

RETRY Enables the statement that caused the error to execute again. label An IBM 4680 BASIC label local to the program module that identifies a statement to receive control in the event of an error.

CLOSE Statement Use the CLOSE statement to end communication with the 2x20 display driver.
CLOSEnumber

CLOSE Ends communication with the 2x20 display driver. number The I/O session number assigned to the 2x20 display in the OPEN statement.

Example
The following program example contains code for operating a 2x20 display.
%ENVIRON T ! Declare a two-byte integer. INTEGER*2 DISPLAY ! 20-character message for line 1. LINE.ONE$ = "ROW ONE SAMPLE " ! Message for line two. LINE.TWO$ = "ROW TWO SAMPLE " ON ERROR GOTO ERR.HNDLR ! Open the display. DISPLAY = 1 OPEN "ANDISPLAY:" AS DISPLAY ! Clear the display. CLEARS DISPLAY
Chapter 8. Using Input and Output Devices and Pipes

201

! Write a greeting. WRITE #DISPLAY; " 2x20 DISPLAY SAMPLE" ! Pause. WAIT;2000 ! Clear the greeting. CLEARS DISPLAY ! Display the string. WRITE FORM "C20";#DISPLAY; LINE.ONE$ ! Pause. WAIT;2000 ! Set character location (2,1) and display the second line LOCATE #DISPLAY ;2,1 WRITE #DISPLAY; LINE.TWO$ ! Pause. WAIT;2000 ! Clear the display then write sample ending message CLEARS DISPLAY WRITE #DISPLAY; "END OF 2x20 SAMPLE" CLOSE DISPLAY STOP ERR.HNDLR: ! Prevent recursion. ON ERROR GOTO END.PROG ! Determine error type ! and perform appropriate ! recovery and resume steps. END.PROG: STOP END

Cash Drawer Driver


There are five statements and functions you can use to communicate with the cash drawer driver (CDRAWER:). OPEN Statement Use the OPEN statement to gain access to the cash drawer driver.
OPEN"CDRAWER:"ASnumber

number A 2-byte integer or constant with a value of 1 to 99. WRITE FORM # Statement Use the WRITE FORM # statement to open a cash drawer or to set and reset an alarm. You can connect an alarm device to the socket where you would normally connect a second cash drawer.
WRITE FORMformat.string;#number;i1

format.string A string constant or variable consisting of value i1. number The same 2-byte integer variable or constant assigned to the cash drawer in the OPEN statement. i1 A 1-byte integer constant or variable having the value 1, 2, 3, or 4. 1 opens cash drawer number one. 2 opens cash drawer number two. 3 sets the alarm on. 4 sets the alarm off.

GETLONG Function

202

IBM 4680 BASIC: Language Reference

Use the GETLONG function to get status information from the cash drawer driver. The application must allow time for the driver to perform an operation before the results of the operation are reflected in the driver status.
i4 = GETLONG(number)

i4

A 4-byte integer that represents the driver status.

number The same 2-byte integer variable or constant assigned to the cash drawer driver in the OPEN statement. The integer represents information in the form RRRRS1S2. RR, RR, S1, and S2 each represent one of the four bytes. The first two bytes, RRRR, are reserved for system use. Byte S1 = 0 if cash drawer 1 is closed. = 1 if cash drawer 1 is open. = 2 if cash drawer 1 is not connected. = 3 if cash drawer 1 and cash drawer 2/alarm are not connected. if cash drawer 2 is closed or the alarm is off. = 1 if cash drawer 2 is open or the alarm is active. = 2 if cash drawer 2 or an alarm is not connected. = 3 if cash drawer 2/alarm and cash drawer 1 are not connected.

Byte S2

= 0

RESUME Statement Use the RESUME statement to recover from an error associated with the cash drawer driver.
======= RESUMERETRY label

RETRY Enables the statement that caused the error to execute again. label An IBM 4680 BASIC label local to the program module that identifies a statement to receive control in the event of an error.

CLOSE Statement Use the CLOSE statement to end communication with the cash drawer driver.
CLOSEnumber

number The same 2-byte integer variable or constant assigned to the cash drawer in the OPEN statement.

Example
The following program example contains code for operating a cash drawer. The program writes a message to the display, opens the cash drawer, writes another message, and then waits for the drawer to be closed.
%ENVIRON T ! Declare work integers INTEGER*4 I4,S4 INTEGER*1 DRAWER.ONE
Chapter 8. Using Input and Output Devices and Pipes

203

! Constant to open drawer 1 DRAWER.ONE = 1 ! ON ERROR GOTO ERR.HNDLR ! Open the display as #2 OPEN "ANDISPLAY:" AS 2 CLEARS 2 ! Open cash drawer driver as #1 OPEN "CDRAWER:" AS 1 WRITE #2;"CASHDRAWER DRIVER OPEN" WAIT;2000 START.DRAWER.CONTROL: CLEARS 2 WRITE #2; "OPEN DRAWER 1" WAIT;2000 ! Open cash drawer number 1 WRITE FORM "I1";#1;DRAWER.ONE ! DRAWER.OPEN: ! Loop while the drawer is open CLEARS 2 WRITE #2; "CLOSE DRAWER" WAIT;1000 ! Get the status I4 = GETLONG(1) ! Shift status S4 = SHIFT(I4,8) ! Turn off all but status STAT% = S4 and 000000FFH ! Return until cash drawer is closed IF STAT% <> 0 THEN GOTO DRAWER.OPEN \ ELSE\ ! End the execution CLEARS 2 WRITE #2; "end of sample" WAIT;1000 CLOSE 1 CLOSE 2 STOP ERR.HNDLR: ! Prevent recursion ON ERROR GOTO END.PROG ! Determine error type ! and perform appropriate ! recovery and RESUME steps. END.PROG: STOP END

Coin Dispenser
There are four statements you can use to communicate with the coin dispenser driver (COIN:). You must use the ON ASYNC ERROR CALL statement to process an error associated with a WRITE # statement to this driver. OPEN Statement Use the OPEN statement to gain access to the coin dispenser driver.
OPENCOIN:"ASnumber

204

IBM 4680 BASIC: Language Reference

number A 2-byte integer or constant with a value of 1 to 99. WRITE FORM # Statement Use the WRITE FORM # statement to dispense coins.
WRITE FORMformat.string;#number;i4

format.string A string constant or variable consisting of value i4. number The same 2-byte integer variable or constant assigned to the coin dispenser in the OPEN statement. i4 A 4-byte integer constant or variable.

Note: On a coin ASYNC I/O error, the retry flag is ignored and the failing statement is NOT retried (It works as a RESUME.) For more information, see ON ASYNC ERROR CALL Statement on page 107. RESUME Statement Use the RESUME statement to recover from an OPEN error associated with the coin dispenser driver.
======= RESUMERETRY label

RETRY Enables the statement that caused the error to execute again. label An IBM 4680 BASIC label local to the program module that identifies a statement to receive control in the event of an error.

CLOSE Statement Use the CLOSE statement to end communication with the coin dispenser driver.
CLOSEnumber

number The same 2-byte integer variable or constant assigned to the coin dispenser in the OPEN statement.

Example
The following example program runs through one time, dispenses 47 cents, and stops.
%ENVIRON T INTEGER*4 hx%,sx% INTEGER*2 COIN%,ANDSP% SUB ASYNC.ERR(RFLAG,OVER) INTEGER*2 RFLAG STRING OVER RFLAG = 0 OVER = "" hx% = errn errfx$ = "" for s% = 28 to 0 step -4
Chapter 8. Using Input and Output Devices and Pipes

!! INDICATE TERMINAL !! DECLARE VARIABLES

205

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 A$=CHR$(THE.SUM%) errfx$ = errfx$ + A$ next s% clears ANDSP% write #ANDSP%;"err=",err," errl=",errl locate #ANDSP%;2,1 write #ANDSP%;"errf=",errf%," errn=",errfx$ wait ;15000 resume END SUB ON ERROR GOTO ERRORA ON ASYNC ERROR CALL ASYNC.ERR COIN% = 3 ANDSP% = 1 OPEN "ANDISPLAY:" as ANDSP% CLEARS ANDSP% WRITE #ANDSP% ; "SAMPLE COIN PROG" WAIT ; 5000 !! SET "ON ERROR" !! SET "ON ASYNC ERROR" !! INITIALIZE SESSION NUMBERS !! !! !! !! OPEN AN DISPLAY CLEAR AN DISPLAY INDICATE START OF APPL WAIT 5 SECONDS

OPEN "COIN:" AS COIN% !! OPEN COIN LOCATE #ANDSP% ; 2,1 !! LOCATE TO 2ND LINE OF DSPL WRITE #ANDSP% ; "COIN DISPENSER OPEN" WAIT ; 5000 AMOUNT% = 47 !! LOAD AMOUNT TO BE DISPENSED CLEARS ANDSP% !! CLEAR DISPLAY WRITE FORM "C8 PIC(####) C8" ;#ANDSP% ; "WRITING ",AMOUNT%," CENTS. " WRITE FORM "I4" ; #COIN% ; AMOUNT% !! DISPENSE COMMAND WAIT ; 5000 !! WAIT 5 SEC LOCATE #ANDSP% ; 2,1 WRITE #ANDSP% ; "END OF SAMPLE" STOP ERRORA: !!ERROR ASSEMBLY ROUTINE!! hx% = errn errfx$ = "" 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 A$=CHR$(THE.SUM%) errfx$ = errfx$ + A$ next s% clears ANDSP% write #ANDSP%;"err=",err," errl=",errl locate #ANDSP%;2,1 write #ANDSP%;"errf=",errf%," errn=",errfx$ wait ;15000 resume end

206

IBM 4680 BASIC: Language Reference

Input/Output Processor
There are twelve statements and functions you can use tocommunicate with the input/output processor (IOPROC:) driver. LOAD Statement The LOAD statement loads the data in the specified files on the LOAD statement. The data is brought into memory to be used by the I/O processor. You must issue a LOAD statement before opening the I/O processor. The file names specified must include R:: before the file name.
LOAD"ISTBL = variable1, FMTTBL = variable2, " MODTBL = variable3

variable1 The fully qualified file name of the input state table (ISTBL). variable2 The fully qualified file name of the format table (FMTTBL). variable3 The fully qualified file name of the modulo check table (MODTBL). ISTBL is required, but both FMTTBL and MODTBL are optional and have no default value. See the IBM 4680 Store System: Programming Guideor the IBM 4690 Store System: Programming Guide for more information on building ISTBL, FMTTBL, and MODTBL tables. OPEN Statement Use the OPEN statement to gain access to the I/O processor driver.
=====BUFF 1====== OPEN"IOPROC:"ASnumber BUFFnum.buff =====BUFFSIZE 128====== BUFFSIZEbuff.size

number A 2-byte integer or constant with a value of 1 to 99. num.buff A 2-byte integer constant or variable with a value ranging from 1 to 10 that specifies the number of terminal input sequences that can be buffered to the application. buff.size A 2-byte integer constant or variable with a value ranging from 16 to 32767 that indicates the maximum size of each buffer. WAIT Statement

Chapter 8. Using Input and Output Devices and Pipes

207

Use the WAIT statement to wait for data to become available from the I/O processor driver. This includes input from the keyboard, scanner, OCR, or magnetic wand. An application program can wait on multiple input devices concurrently. Use the EVENT% function to retrieve the session number that satisfied the wait.
=============== WAITnumber ;timeout.val ,number.n ...........

number The same 2-byte integer variable or constant assigned to the I/O processor in the OPEN statement. number.n An I/O session number assigned to another driver or pipe. timeout.val A 4-byte integer variable or constant that specifies the number of milliseconds to wait for data to become available from one of the drivers or pipes. UNLOCKDEV Statement Use the UNLOCKDEV statement to enable the I/O processor driver to accept data and specify a new state. You can optionally place data entered by the operator ahead of any buffered data. This is useful if the application program detects an error requiring the operator to enter some additional data.
============ =========== UNLOCKDEVnumber ,new.state ,PRIORITY

number The same 2-byte integer variable or constant assigned to the I/O processor in the OPEN statement. new.state A 2-byte integer constant or variable that indicates a new state for the I/O processor. PRIORITY Specifies that the next data entered by the operator is placed ahead of any data currently in the I/O processor buffer area. READ # Statement Use the READ # statement to read data from the I/O processor driver.
READ#number;string.var ..... , ....

number The same 2-byte integer variable or constant assigned to the I/O processor in the OPEN statement. string.var A string variable to hold the data the statement reads. The first string variable is assigned data as described below. You must specify ten or more additional string variables to map input fields to, as specified in the Input Sequence Table Utility.

208

IBM 4680 BASIC: Language Reference

The field of data returned in the first variable is either 14 bytes long if Enhanced Full Screen support is not being used or 26 bytes long if Enhanced Full Screen support is being used. Enhanced Full Screen is an option specified in the State Table. The data in the first variable is described below: Byte 1 = status field identifier blank a normal status field 1 the tab forward key was pressed last 2 the tab backward key was pressed last = initial state identifier = current state identifier = originating device identifier (last contributing input device) 1 for the keyboard 2 for the OCR 3 for the scanner 4 for the magnetic wand = manager key flag 0 for off 1 for on = label flag 0 if data is not from a keyed label 1 if data is from a keyed label (a label is normally scanned or wanded but can be entered manually from the keyboard) = last function code received = error associated with the last function code blank means no error 1 is RESERVED 2 too much data entered 3 not enough data entered 4 value entered is too large 5 value entered is too small 6 manager key is off (must be on) 7 manager key is on (must be off) 8 data required (no data entered) 9 data entered (not allowed) a the last field is mutually exclusive with a previous field b the data entered failed a modulo check c an invalid key was entered 17 = tab order of last active field 20 = cursor position row 23 = cursor position column 26 = number of fields in the input sequence

Byte 2 to 5 Byte 6 to 9 Byte 10

Byte 11

Byte 12

Byte 13 Byte 14

Bytes Bytes Bytes Bytes

15 18 21 24

to to to to

READ # LINE Statement Use the READ # LINE statement to read data from the I/O processor driver. All data, including any field delimiters, is read into a specified string variable. The first 14-byte field of data assigned to the string variable has the same format described in the READ # statement for the I/O processor.
READ#number;LINEstring.var

Chapter 8. Using Input and Output Devices and Pipes

209

number The same 2-byte integer variable or constant assigned to the I/O processor in the OPEN statement. string.var A string variable to hold the input data. WRITE # Statement Use the WRITE # statement to write data to the I/O processor driver.
WRITE#number;string.var ..... , ....

number The same 2-byte integer variable or constant assigned to the I/O processor in the OPEN statement. string.var A string variable holding the data the statement writes. The first string variable has the same format described in the READ # statement for the I/O Processor. You must specify ten or more additional string variables containing data to be written. GETLONG Function Use the GETLONG function to get status information from the I/O processor driver.
i4 = GETLONG(number)

i4

A 4-byte integer that represents the driver status.

number The same 2-byte integer variable or constant assigned to the I/O processor in the OPEN statement. The integer represents information in the form FFTTSLSH. FF, TT, SL, and SH each represent one of the four bytes. Byte FF represents flags with the following meanings: bit 0 (hex 01) = 0 if the I/O processor is unlocked. bit 0 (hex 01) = 1 if the I/O processor is locked. bit 1 = 0 if the I/O processor is in normal mode (no PRIORITY) or locked. bit 1 = 1 if the I/O processor is in PRIORITY mode and locked. bit 2 = 0 if PURGE was not specified on the last LOCKDEV statement issued for the I/O processor or if the I/O processor is UNLOCKED. bit 2 = 1 if the I/O processor is locked and PURGE was specified on the last LOCKDEV statement issued for the I/O processor. Byte TT is reserved for system use. Bytes SL and SH are a 2-byte state number associated with the last data read by the applications program. SL is the low order byte and SH is the high order byte.

210

IBM 4680 BASIC: Language Reference

PUTLONG Statement Use the PUTLONG statement to make requests to the I/O Processor driver.
PUTLONGnumber,i4

number The same 2-byte integer variable or constant assigned to the I/O Processor in the OPEN statement. i4 A 4-byte integer that represents the requests to the I/O Processor driver.

The integer represents information in the form: FFTTSLSH. FF, TT, SL, and SH each represent one of the four bytes. Byte FF represents flags with the following meanings: bit 0 (hex 01) = 0 RESERVED bit 1 = 0 Set normal mode bit 1 = 1 Set priority mode bit 2 = 0 Dont purge queued buffers or the active input sequence buffer. bit 2 = 1 Purge queued buffers and the active input sequence buffer. bit 3 = 0 RESERVED bit 4 = 0 Purge the active input sequence buffer. bit 4 = 1 Dont purge the active input sequence buffer. Set this bit when the PUTLONG follows a WRITE that preloaded the input sequence buffer. bit 5 = 0 Initialize screen data and attributes. The data in the active input sequence buffer is written to the display screen. bit 5 = 1 Dont initialize screen data and attributes. The display screen is not altered. bit 6 = 0 RESERVED bit 7 = 0 RESERVED Byte TT specifies the tab order to be unlocked to. Bytes SL and SH are a 2-byte state number to be unlocked to. SL is the low order byte and SH is the high order byte. LOCKDEV Statement Use the LOCKDEV statement to prevent the I/O processor from accepting data. You can optionally discard any data in the buffer.
========== LOCKDEVnumber ,PURGE

number The same 2-byte integer variable or constant assigned to the I/O processor in the OPEN statement. PURGE Discards any data in the buffer. RESUME Statement

Chapter 8. Using Input and Output Devices and Pipes

211

Use the RESUME statement to recover from an error associated with the I/O processor driver.
======= RESUMERETRY label

RETRY Enables the statement that caused the error to execute again. label An IBM 4680 BASIC label local to the program module that identifies a statement to receive control in the event of an error.

CLOSE Statement Use the CLOSE statement to end communication with the I/O processor driver.
CLOSEnumber

number The same 2-byte integer variable or constant assigned to the I/O processor in the OPEN statement.

Example
The following program example contains code for operating an I/O processor. The program writes a message to the display, loads an Input Sequence Table, waits for scanner input, checks the input, and writes it (in readable form) to the display.
REM This routine requires that an Input Sequence Table REM be created. REM. The table should REM have at least one function code, which is a motor function REM code. The relative position should be 3,2 or 1 for REM this routine to redisplay the input. %ENVIRON T ! Declare integers INTEGER*2 DISPLAY INTEGER*2 OPERIN DISPLAY = 1 OPERIN = 2 ON ERROR GOTO ERR.HNDLR ! Open the display OPEN "ANDISPLAY:" AS DISPLAY ! Write a greeting CLEARS DISPLAY WRITE #DISPLAY; "I/O PROCESSOR SAMPLE" WAIT;2000 ! Open the I/O Processor and load an ! Input Sequence Table A$= "ISTBL=R::ADX_IPGM\UUUU@SMP.DAT, " B$= "FMTTBL=R::ADX_IPGM\UUUU@LBL.DAT, " C$= "MODTBL=R::ADX_IPGM\UUUU@MOD.DAT " LOAD A$+B$+C$ OPEN "IOPROC:" AS OPERIN BUFFSIZE 70 ! Prompting is displayed by I/O Processor ! as specified in the Input Sequence Table KBWAIT: ! Wait for input WAIT OPERIN;5000 ! You would normally test

212

IBM 4680 BASIC: Language Reference

! for a timeout condition. ! Read the available input data READ #OPERIN; IOPDATA$,B$,C$,D$,E$,F$,G$,H$,I$,J$,K$ ! Display 14 status bytes CLEARS DISPLAY WAIT;2000 WRITE #DISPLAY;"IOP=", IOPDATA$ WAIT;2000 ! Check byte 14 for I/O Processor flagged edit condition ! return for reentry by user if error in data. IF MID$(IOPDATA$,14,1) <> " " THEN GOTO KBWAIT ! Display three of the relative variables CLEARS DISPLAY WRITE #DISPLAY;"B=", B$ WAIT;2000 CLEARS DISPLAY WRITE #DISPLAY;"C=", C$ WAIT;2000 CLEARS DISPLAY WRITE #DISPLAY;"D=", D$ WAIT;2000 CLEARS DISPLAY WRITE #DISPLAY; "END OF SAMPLE" CLOSE DISPLAY, OPERIN STOP ERR.HNDLR: ! Prevent recursion ON ERROR GOTO END.PROG ! Determine error type ! and perform appropriate ! recovery and RESUME steps. END.PROG: STOP END

Magnetic Stripe Reader (Dual-Track and Single-Track)


Eight statements and functions can be used to communicate with the dual-track or single-track magnetic stripe reader (MSR): OPEN Statement Use the OPEN statement to gain access to the magnetic stripe reader driver.
OPEN MSR: AS number

number A 2-byte integer or constant with a value of 1 to 99. WAIT Statement Use the WAIT statement to wait for data to become available from the magnetic stripe reader driver. An application program can wait on multiple input devices concurrently. Use the EVENT% function to retrieve the session number that satisfied the wait.

Chapter 8. Using Input and Output Devices and Pipes

213

=============== WAITnumber ;timeout.val ,number.n ...........

number The same 2-byte integer variable or constant assigned to the magnetic stripe reader in the OPEN statement. number.n An I/O session number assigned to another driver or pipe. timeout.val A 4-byte integer variable or constant that specifies the number of milliseconds to wait for data to become available from one of the drivers or pipes. UNLOCKDEV Statement Use the UNLOCKDEV statement to enable the magnetic stripe reader driver to accept data.
UNLOCKDEV number

number The same 2-byte integer variable or constant assigned to the magnetic stripe reader in the OPEN statement. READ # LINE Statement Use the READ # LINE statement to read data from the magnetic stripe reader driver. All data is read into a specified string variable and returned in binary-coded decimal (BCD) format (for the single-track MSR). (For information on received data format for the dual-track MSR, refer to the IBM 4680 Store System: Programming Guide or the IBM 4690 OS Version 3: Programming Guide)
READ # number LINE string.var

number The same 2-byte integer variable or constant assigned to the magnetic stripe reader in the OPEN statement. string.var A string variable to hold the input data. GETLONG Function Use the GETLONG function to get status information from the magnetic stripe reader driver.
i4 = GETLONG ( number )

i4

A 4-byte integer that represents the driver status.

214

IBM 4680 BASIC: Language Reference

number The same 2-byte integer variable or constant assigned to the magnetic stripe reader in the OPEN statement. For the single-track magnetic stripe reader, the integer represents information in the form RRRRRRLL. RR, RR, RR, and LL each represent one of the four bytes. The first three bytes, RRRRRR, are reserved for system use.
Byte LL = 0 if the MSR is unlocked = 1 if the MSR is locked

The integer represents information in the form RRSSRRLL where RR, SS, RR, and LL each represent one of the four bytes. The only difference between the single and dual-track returned data is the Byte SS representing status information. To determine the attached hardware: open and unlock the MSR, issue a GETLONG, then check the SS byte for the bit settings as shown below. The RR bytes are reserved for system use.
Byte LL = 0 if the MSR is unlocked = 1 if the MSR is locked

Byte SS represents status information as follows: bit 0 (hex 01) = 0 RESERVED bit 1 = EC information is included in the data bit 2 = POR failed bit 3 = 0 RESERVED bit 4 = 1 track 1 or track 3 is enabled bit 5 = 1 track 2 is enabled bit 6 = 0 track 3 is connected bit 6 = 1 track 1 is connected bit 7 = 1 command reject LOCKDEV Statement Use the LOCKDEV statement to prevent the magnetic stripe reader from accepting data. LOCKDEV discards any data in the buffer.
LOCKDEV number

number The same 2-byte integer variable or constant assigned to the magnetic stripe reader in the OPEN statement. RESUME Statement Use the RESUME statement to recover from an error associated with the magnetic stripe reader driver.

Chapter 8. Using Input and Output Devices and Pipes

215

RESUME RETRY label

RETRY Enables the statement that caused the error to run again. label An IBM 4680 BASIC label local to the program module that identifies a statement to receive control in the event of an error.

CLOSE Statement Use the CLOSE statement to end communication with the magnetic stripe reader driver.
CLOSE number

number The same 2-byte integer variable or constant assigned to the magnetic stripe reader in the OPEN statement.

Single-Track MSR Example


The following program example reads data from a card passed through the magnetic stripe reader. The data is converted and displayed. The example processes three card reads before ending.
%ENVIRON T ! Declare integers INTEGER*2 DISPLAY INTEGER*2 MSREADER ! Convert data to display characters FUNCTION CONVERT.TO.HEX$(THE.SUM%) IF THE.SUM% > 9 THEN \ THE.SUM%=THE.SUM%+55\ ELSE \ THE.SUM%=THE.SUM%+48 CONVERT.TO.HEX$=CHR$(THE.SUM%) EXIT FUNCTION END FUNCTION DISPLAY = 1 MSREADER = 2 ON ERROR GOTO ERR.HNDLR ! Open the display OPEN "ANDISPLAY:" AS DISPLAY ! Write a greeting and wait 2 seconds CLEARS DISPLAY WRITE #DISPLAY; "MS READER SAMPLE" WAIT;2000 ! Open the magnetic stripe reader driver OPEN "MSR:" AS MSREADER ! Loop and read three cards FOR I% = 1 to 3 UNLOCKDEV MSREADER ! Display instructions CLEARS DISPLAY WRITE #DISPLAY;"PASS A CARD THROUGH" MSRWAIT:

216

IBM 4680 BASIC: Language Reference

! Wait for input 5 seconds WAIT MSREADER;5000 ! You would normally test for ! a timeout condition ! Read the available input data READ #MSREADER; LINE MSRDATA$ ! Convert the input to displayable characters DISPL.DATA$ = " " ! Loop through the input data and convert ! each character. FOR J% = 1 to LEN(MSRDATA$) A$=MID$(MSRDATA$,J%,1) THE.SUM% = ASC(A$) A$=CONVERT.TO.HEX$(THE.SUM%) DISPL.DATA$ = DISPL.DATA$ + A$ NEXT J% ! Display input data and wait 2 seconds CLEARS DISPLAY WRITE #DISPLAY;DISPL.DATA$ WAIT;2000 NEXT I% CLEARS DISPLAY WRITE #DISPLAY; "END OF SAMPLE" CLOSE DISPLAY,MSREADER STOP ERR.HNDLR: ! Prevent recursion ON ERROR GOTO END.PROG ! Determine error type ! and perform appropriate ! recovery and RESUME steps END.PROG: STOP END

Dual-Track MSR Example


The following program example reads data from a card passed through the dual-track magnetic stripe reader.
%ENVIRON T ! Declare INTEGER*2 INTEGER*2 STRING STRING STRING INTEGER*2 variables DISPLAY MSR2.READER MSR2.DATA MSR2.DATA.TRACK2 MSR2.DATA.TRACK13 L1,L2

DISPLAY=1 MSR2.READER=2 ON ERROR GOTO ERR.HNDLR ! Open the display OPEN "ANDISPLAY:" AS DISPLAY ! Write greeting and wait 2 seconds CLEARS DISPLAY WRITE #DISPLAY; "MSR2 SAMPLE" WAIT;2000
Chapter 8. Using Input and Output Devices and Pipes

217

! Open the MSR driver OPEN "MSR:" AS MSR2.READER ! Loop and read 3 cards FOR I%=1 TO 3 UNLOCKDEV MSR2.READER ! Display instructions CLEARS DISPLAY WRITE #DISPLAY; "PASS A CARD THROUGH ",I% MSRWAIT: ! Wait for 5 seconds WAIT MSR2.READER;5000 ! You would normally test for ! a timeout condition. ! Read the available input data READ #MSR2.READER; LINE MSRDATA$ ! Get the length of the track 2 data (255 indicates error) L1=ASC(MID$(MSRDATA$,38,1)) ! Get the length of the track 1or 3 data (255 indicates error) L2=ASC(MID$(MSRDATA$,39,1)) ! Process track 2 data IF L1 = 255 THEN \ BEGIN ! Display error message CLEARS DISPLAY WRITE #DISPLAY; "TRACK 2 ERROR" WAIT;3000 ENDIF \ ELSE \ BEGIN \ MSR2.DATA.TRACK2 = MID$(MSRDATA$,1,L1) ! Here you would convert the input to ! displayable characters and display it. ENDIF ! Process track 1/3 data IF L2 = 255 THEN \ BEGIN ! Display error message CLEARS DISPLAY WRITE #DISPLAY; "TRACK 1/3 ERROR" WAIT;3000 ENDIF \ ELSE \ BEGIN \ MSR2.DATA.TRACK13 = MID$(MSRDATA$,40,L2) ! Here you would convert the input to ! displayable characters and display it. ENDIF NEXT I% CLEARS DISPLAY WRITE #DISPLAY; "END OF SAMPLE" CLOSE MSR2.READER,DISPLAY STOP ERR.HNDLR: ! Prevent recursion. ON ERROR GOTO ERR.EXIT ! Determine error type and ! perform appropriate recovery ! and RESUME steps.

218

IBM 4680 BASIC: Language Reference

ERR.EXIT: STOP END

Printer Stations for Printer Models 1 and 2


The three printer stations for the IBM 4680 or 4690 Store System are: v The customer receipt station (CR:) v The summary journal station (SJ:) v The document insert station (DI:) There are eight statements and functions you can use to communicate with the printer driver. You must use the ON ASYNC ERROR CALL statement to process an error with a WRITE # statement to this driver. OPEN Statement Use the OPEN statement to access the terminal printer driver.
OPEN CR: SJ: DI: AS number

number A unique 2-byte integer or constant with a value of 1 to 99. WRITE FORM # Statement Use the WRITE FORM # statement to print data on the customer receipt and summary journal stations, and to print a document on the document insert station. Do not issue a WRITE FORM # statement from your ON ASYNC ERROR CALL subprogram.
WRITE FORMformat.string;#number;data.var ...,...

format.string A string constant or variable. The number of bytes represented by the string must be 38 not including the line feed specification (A value). number The same 2-byte integer variable or constant assigned to the appropriate print station in the OPEN statement. data.var A variable, constant, or expression. The total amount of data written must be 38 bytes. WRITE LOGO # Statement Use the WRITE LOGO # statement to print data on the middle 300-dot columns on the customer receipt and document insert stations or to print a check on the document insert station. In order to print a check, the following conditions must be met: v bit 3 of GETLONG byte SS must be 1
Chapter 8. Using Input and Output Devices and Pipes

219

v the check must conform to the United Kingdom APACS standard or the data must fit within the area of the check that can be printed using the check printing mode of the WRITE LOGO # statement. See the descriptions of the PUTLONG statement and GETLONG function in this section and refer to the IBM 4680 Store System: Programming Guide or the IBM 4690 Store System: Programming Guide for information on how to print a check. Note: Do not issue a WRITE LOGO # statement from an ON ASYNC ERROR CALL subprogram.
WRITE LOGO#number;array.element

number The same 2-byte integer variable or constant assigned to the appropriate print station in the OPEN statement. array.element The first element in an array of 1-byte integers to be printed. The number of elements in this one-dimensional array must be a multiple of 381. Each set of 381 elements is comprised of 300 character slices followed by 80 unused bytes followed by one byte that contains the number of partial line-feeds to be issued after the current data prints. RESUME Statement Use the RESUME statement to recover from an error associated with an OPEN, GETLONG, PUTLONG, or CLOSE statement. Use the ON ASYNC ERROR CALL statement for errors associated with a WRITE # or WRITE LOGO # statement.
======= RESUMERETRY label

RETRY Enables the statement that caused the error to execute again. label A BASIC label local to the program module that identifies a statement to receive control in the event of an error.

GETLONG Function Use the GETLONG function to get status information from the impact printer driver.
i4 = GETLONG(number)

i4

A 4-byte integer that represents the driver status.

number The same 2-byte integer variable or constant assigned to any one of the printer stations in the OPEN statement. The integer represents information in the form RRRRMMSS. RR, RR, MM, and SS each represent one of the four bytes. The first two bytes, RRRR, are reserved for system use. Byte MM represents mode information as follows: bit 0 (hex 01) = 0 RESERVED

220

IBM 4680 BASIC: Language Reference

bit 1 = 0 RESERVED bit 2 = 0 RESERVED bit 3 = 0 RESERVED bit 4 = 0 Manual document insert. (You can insert documents from the front or the side. They must be positioned to cover the document sensor.) bit 4 = 1 Automatic document insert. (You can only insert documents from the front. The printer closes the document throat on the document when the first print line on the DI: is issued. It must cover the sensor.) bit 5 = 0 The document cannot be removed and replaced between print lines on DI: (If you remove a document between print lines, an error occurs.) bit 5 = 1 The document can be removed and replaced between print lines on DI:. bit 6 = 0 The document cannot be placed in DI: during printing on CR:. (If you insert a document while printing on CR:, an error occurs. bit 6 = 1 The document can be placed in DI: during printing on CR:. bit 7 = 0 Document sensing not required by DI: during printing on CR:. bit 7 = 1 Document sensing required by DI: for printing on CR: (or, the document must be sensed during CR: printing). Byte SS represents status information as follows: bit 0 (hex 01) = RESERVED bit 1 = 0 RESERVED bit 1 = 1 paper error at SJ: (if bit 2 = 1) bit 2 = 0 no paper error bit 2 = 1 paper error bit 3 = 0 This is not a 4683 Model 2 printer. (Check printing is not supported). bit 3 = 1 This is a 4683 Model 2 printer. (Check printing is supported.) bit 4 = 0 document not present in DI: bit 4 = 1 document present in DI: bit 5 = 0 DI: throat closed

Chapter 8. Using Input and Output Devices and Pipes

221

bit 5 = 1 DI: throat open bit 6 = 0 printer head not at home position bit 6 = 1 printer head at home position bit 7 = 0 printer cover closed bit 7 = 1 printer cover open PUTLONG Statement Use the PUTLONG statement to make changes to the document insert station mode.
PUTLONGnumber,i4

number The same 2-byte integer variable or constant assigned to any one of the printer stations in the OPEN statement. i4 A 4-byte integer that represents the request to the document insert station.

The integer represents information in the form RRRRRRMM. RR, RR, RR, and MM each represent one of the four bytes. The first three bytes are reserved for system use. Byte MM represents mode information as follows: bit 0 (hex 01) = 0 RESERVED bit 1 = 0 RESERVED bit 2 = 0 RESERVED bit 3 = 0 WRITE LOGO # statements that specify the document insert station will be interpreted as normal WRITE LOGO # statements. bit 3 = 1 WRITE LOGO # statements that specify the document insert station will be interpreted as check printing commands. bit 4 = 0 manual document insert bit 4 = 1 automatic document insert bit 5 = 0 document cannot be removed and replaced between print lines on DI: bit 5 = 1 document can be removed and replaced between print lines on DI: bit 6 = 0 document cannot be placed in DI: during printing on CR: bit 6 = 1 document can be placed in DI: during printing on CR: bit 7 = 0 document sensing not required by DI: for printing on CR: bit 7 = 1 document sensing required by DI: for printing on CR:.

222

IBM 4680 BASIC: Language Reference

TCLOSE Statement Use the TCLOSE statement to suspend the application program until all outstanding print lines have been printed at all printer stations. Do not issue a TCLOSE statement from an ON ASYNC ERROR CALL statement subprogram.
TCLOSE#number

number The same 2-byte integer variable or constant assigned any print station in the OPEN statement. CLOSE Statement Use the CLOSE statement to end communication with the printer driver.
CLOSEnumber

number The same 2-byte integer variable or constant assigned to the customer receipt, summary journal or document insert station in the OPEN statement.

Printer Stations for Printer Models 3 and 4/4A


The three printer stations for the IBM 4680 or 4690 Store System are: v The customer receipt station (CR:) v The summary journal station (SJ:) v The document insert station (DI:). There are eight statements and functions you can use to communicate with the printer driver. You must use the ON ASYNC ERROR CALL statement to process an error with a WRITE # statement to this driver. OPEN Statement Use the OPEN statement to access the terminal printer driver.
OPEN"CR:"..AS..number OPEN"SJ:"..AS..number OPEN"DI:"..AS..number

number A unique 2-byte integer or constant with a value of 1 to 99. WRITE FORM # Statement Use the WRITE FORM # statement to print data on the customer receipt and summary journal stations, and to print a document or check on the document insert station. Do not issue a WRITE FORM # statement from your ON ASYNC ERROR CALL subprogram.
WRITE FORMformat.string;#number;data.var ...,...

format.string A string constant or variable. The number of bytes represented by the string must include the line feed specification (A value).

Chapter 8. Using Input and Output Devices and Pipes

223

number The same 2-byte integer variable or constant assigned to the appropriate print station in the OPEN statement. data.var A variable, constant, or expression. The total amount of data written must fit within the station limits. See the IBM 4680 Store System: Programming Guide or the IBM 4690 OS Version 3: Programming Guide for a list of the station limits. Note: Control characters may be imbedded in the data.var value to perform functions such as changing the font or ejecting a document. See Table 15 for a complete list of the control characters for Models 3 and 4.
Table 15. Models 3 and 4 Printer Control Characters Description 15 characters/inch 12 characters/inch 7.5 characters/inch 7.5 cpi double high Document Eject Move Printhead to Left of Receipt (CR:) Station. Emphasized Print Receipt Paper Cut Control Characters CHR$(27), CHR$(59) CHR$(27), CHR$(58) CHR$(27), CHR$(14) CHR$(27), CHR$(23) CHR$(27), CHR$(12) CHR$(27), CHR$(76) or CHR$(27), L CHR$(27), CHR$(69) or CHR$(27), E CHR$(27), CHR$(80) or CHR$(27), P Comments Default font Medium Font. Easier to read on multi-part forms. Double Wide Double High/Double Wide DI: station only. Use TCLOSE Command to move Printhead to Center. May result in darker print when using thick documents. Must be the only characters in the WRITE statement.

See Table 16 for a complete list of the control characters for Model 4A.
Table 16. Model 4A Printer Control Characters Description Document Eject Move Printhead to Left of Receipt (CR:) Station. Receipt Paper Cut Control Characters CHR$(27), CHR$(12) CHR$(27), CHR$(76) or CHR$(27), L CHR$(27), CHR$(80) or CHR$(27), P Comments DI: station only. Use TCLOSE Command to move Printhead to Center. Must be the only characters in the WRITE statement.

WRITE LOGO # Statement Use the WRITE LOGO # statement to print slice data on the receipt or document stations. The LOGO statement calls for an array of 381 slice elements. However, to be compatible with 4680 or 4690 application programs written for the Model 1 and 2 printers, and the Model 3 and Model 4 printer driver defaults to a LOGO width of 300 columns. To use the full 380 column width, set bit 1 of byte LL of the PUTLONG statement to one. There is no provision in the Models 3 and 4 printer for LOGO printing across the entire width of the 86-character wide document station. Therefore, the maximum LOGO width in either the receipt or document station is 380 slices. See the descriptions of the PUTLONG statement and GETLONG function in this section

224

IBM 4680 BASIC: Language Reference

and refer to the IBM 4680 Store System: Programming Guide or the IBM 4690 OS Version 3: Programming Guide for information on how to print LOGO data. Also see WRITE LOGO # Statement on page 167. Note: Do not issue a WRITE LOGO # statement from an ON ASYNC ERROR CALL subprogram.
WRITE LOGO#number;array.element

number The same 2-byte integer variable or constant assigned to the appropriate print station in the OPEN statement. array.element The first element in an array of 1-byte integers to be printed. The number of elements in this one-dimensional array must be a multiple of 381. Each set of 381 elements is comprised of either 300 character slices followed by 80 unused bytes or 380 character slices (depending on the value set in bit 1 of byte LL), and one byte that contains the number of partial line-feeds to be issued after the current data prints. RESUME Statement Use the RESUME statement to recover from an error associated with an OPEN, GETLONG, PUTLONG, or CLOSE statement. Use the ON ASYNC ERROR CALL statement for errors associated with a WRITE # or WRITE LOGO # statement.
======= RESUMERETRY label

RETRY Enables the statement that caused the error to run again. label A BASIC label local to the program module that identifies a statement to receive control in the event of an error.

GETLONG Function Use the GETLONG function to get status information from the impact printer driver.
i4 = GETLONG ( number )

i4

A 4-byte integer that represents the driver status.

number The same 2-byte integer variable or constant assigned to any one of the printer stations in the OPEN statement. The integer represents information in the form RRLLMMSS. RR, LL, MM, and SS each represent one of the four bytes. Byte RR is reserved for system use: bit 0 (hex 01) = RESERVED: This bit is used by the 4680 BASIC runtime subroutines and will vary in value. It should be ignored by all application programs. bit 1 = 0 RESERVED
Chapter 8. Using Input and Output Devices and Pipes

225

bit 2 = 0 RESERVED bit 3 = 0 RESERVED bit 4 = 0 RESERVED bit 5 = 0 RESERVED bit 6 = 0 RESERVED bit 7 = 0 RESERVED Byte LL represents status information as follows: bit 0 (hex 01) = Journal buffer is empty bit 0 = 1 Journal buffer contains data to be printed bit 1 = 0 Print only first 300 slices of LOGO data bit 1 = 1 Print full 380 slices of LOGO data bit 2 = 0 Print buffered journal data bit 2 = 1 Hold buffered journal data bit 3 = 1 RESERVED Value set to 1. bit 4 = 0 WRITE FORM statement line feed specification (A value) represents line feeds (default) bit 4 = 1 WRITE FORM statement line feed specification (A value) represents motor steps bit 5 = 0 6 lines/inch line spacing mode in the receipt station (default) bit 5 = 1 8 lines/inch line spacing mode in the receipt station bit 6 = 0 6 lines/inch line spacing mode in the journal station (default) bit 6 = 1 8 lines/inch line spacing mode in the journal station bit 7 = 0 6 lines/inch line spacing mode in the document station (default) bit 7 = 1 8 lines/inch line spacing mode in the document station. Byte MM represents mode information as follows: bit 0 (hex 01) = 0 Model 1 or Model 2 printer installed bit 0 = 1 Model 3 or Model 4 printer installed bit 1 = 0 document linefeed is in normal mode, bottom-to-top (default)

226

IBM 4680 BASIC: Language Reference

bit 1 = 1 document linefeed is in reverse mode, top-to-bottom bit 2 = 0 MICR installed bit 3 = 0 print head not at left position sensor bit 3 = 1 print head at left position sensor bit 4 = 0 manual document insert (Documents can only be inserted from the top or front.) bit 4 = 1 automatic document insert (Documents can be inserted from the top or front. The printer will close the document feed rollers on the document when the first print line on the DI: is issued. The document must cover the sensor.) bit 5 = 0 document cannot be removed and replaced between print lines on the DI: (If you remove a document between print lines, an error occurs.) bit 5 = 1 document can be removed and replaced between print lines on the DI: bit 6 = 0 document cannot be placed in DI: during printing on CR: (If you insert a document while printing on CR:, an error occurs.) bit 6 = 1 document can be placed in DI: during printing on CR: bit 7 = 0 document sensing not required by DI: for printing on CR: bit 7 = 1 document sensing required by DI: for printing on CR: (Or, the document must be sensed during CR: printing.) Byte SS represents status information as follows: bit 0 (hex 01) = 0 document not present in TOP document station bit 0 = 1 document present in TOP document station bit 1 = 0 RESERVED bit 1 = 1 paper error at SJ: (check bit 2 for more information) bit 2 = 0 out of paper bit 2 = 1 paper error at SJ: (e.g. paper jammed) bit 3 = 0 RESERVED for model 2 printer check printing feature
Chapter 8. Using Input and Output Devices and Pipes

227

bit 4 = 0 document not present in FRONT document station bit 4 = 1 document present in FRONT document station bit 5 = 0 DI: station ready bit 5 = 1 DI: station not ready bit 6 = 0 print head not at center home position bit 6 = 1 print head at center home position bit 7 = 0 printer cover closed bit 7 = 1 printer cover open. PUTLONG Statement Use the PUTLONG statement to make changes to the customer receipt, summary journal, and document insert station mode.
PUTLONG number , i4

number The same 2-byte integer variable or constant assigned to any one of the printer stations in the OPEN statement. i4 A 4-byte integer that represents the request to the printer stations.

The integer represents information in the form RRRRLLMM. RR, RR, LL, and MM each represent one of the four bytes. The first two bytes are reserved for system use. Byte LL represents mode information as follows: bit 0 (hex 01) = 0 RESERVED bit 1 = 0 Print only first 300 slices of LOGO data bit 1 = 1 Print full 380 slices of LOGO data bit 2 = 0 Print buffered journal data bit 2 = 1 Hold buffered journal data bit 3 = RESERVED bit 4 = 0 WRITE FORM statement line feed specification (A value) represents line feeds bit 4 = 1 WRITE FORM statement line feed specification (A value) represents motor steps

228

IBM 4680 BASIC: Language Reference

bit 5 = 0 6 bit 5 = 1 8 bit 6 = 0 6 bit 6 = 1 8 bit 7 = 0 6 bit 7 = 1 8

lines/inch line spacing mode in the receipt station lines/inch line spacing mode in the receipt station lines/inch line spacing mode in the journal station lines/inch line spacing mode in the journal station lines/inch line spacing mode in the document station lines/inch line spacing mode in the document station

Byte MM represents mode information as follows: bit 0 (hex 01) = 0 RESERVED bit 1 = 0 document linefeed is in normal mode, bottom-to-top (default) bit 1 = 1 document linefeed is in reverse mode, top-to-bottom bit 2 = 0 RESERVED bit 3 = 0 RESERVED bit 4 = 0 manual document insert bit 4 = 1 automatic document insert bit 4 = 0 RESERVED (Model 4A printer) bit 5 = 0 document cannot be removed and replaced between print lines on the DI: bit 5 = 1 document can be removed and replaced between print lines on the DI: bit 5 = 0 RESERVED (Model 4A printer) bit 6 = 0 document cannot be placed in DI: during printing on CR: bit 6 = 1 document can be placed in DI: during printing on CR: bit 6 = 0 RESERVED (Model 4A printer) bit 7 = 0 document sensing not required by DI: for printing on CR: bit 7 = 1 document sensing required by DI: for printing on CR: bit 7 = 0 RESERVED (Model 4A printer) TCLOSE Statement Use the TCLOSE statement to suspend the application program until all outstanding print lines have been printed at the CR: or DI: stations. Do not issue a TCLOSE statement from an ON ASYNC ERROR CALL statement subprogram.

Chapter 8. Using Input and Output Devices and Pipes

229

TCLOSE #

number

number The same 2-byte integer variable or constant assigned any print station in the OPEN statement. CLOSE Statement Use the CLOSE statement to end communication with the printer driver. Do not CLOSE a printer station from an ON ASYNC ERROR CALL subprogram.
CLOSE number

number The same 2-byte integer variable or constant assigned to the customer receipt, summary journal or document insert station in the OPEN statement.

Example
The following program example contains code for operating the terminal. The program writes messages to the display, sets up the synchronous and asynchronous error handlers, and prints lines at the CR and DI stations.
%ENVIRON T ! Declare integers INTEGER*2 DISPLAY,NUMA INTEGER*4 REQ%,STAT% ! Async error handling subprogram SUB ASYNCSUB(RFLAG,OVER) INTEGER*2 RFLAG STRING OVER ! Set up synchronous error handler ! for async subprogram. ON ERROR GOTO SERROR ! See the error recovery example ! for the ON ASYNC ERROR CALL ! statement in Chapter 7. EXIT SUB END SUB ! Opens the print station designated in ! the variables. FUNCTION PRINTER OPEN STATIONS$ AS NUMA CLEARS DISPLAY WRITE #DISPLAY; "OPEN PRINTER ", STATIONS$ EXIT FUNCTION END FUNCTION ! Tcloses to clear all the print requests, ! then displays and closes the print station. FUNCTION CLOSEA TCLOSE NUMA CLEARS DISPLAY WRITE #4; "CLOSE = ", NUMA CLOSE NUMA EXIT FUNCTION END FUNCTION ! Start execution

230

IBM 4680 BASIC: Language Reference

! the Alphanumeric display ! is opened for prompt displaying. ! Set up the asynchronous error handler ! and the synchronous error handler. ON ASYNC ERROR CALL ASYNCSUB ON ERROR GOTO ERR.HNDLR DISPLAY = 4 OPEN "ANDISPLAY:" AS DISPLAY CLEARS DISPLAY WRITE #DISPLAY; "PRINTER SAMPLE" WAIT;2000 ! Start printing. ! Print and space at the customer receipt station CR.PRINTER: NUMA = 3 STATIONS$ = "CR:" CALL PRINTER WRITE FORM "C38 A1";#NUMA; "PRINT CASH RECEIPT AND WRITE FORM "C38 A2";#NUMA; "PRINT CASH RECEIPT AND WRITE FORM "C38 A3";#NUMA; "PRINT CASH RECEIPT AND WRITE FORM "C38 A4";#NUMA; "PRINT CASH RECEIPT AND WRITE FORM "C38 A5";#NUMA; "PRINT CASH RECEIPT AND CALL CLOSEA ! Print and space at the Document Insert station DI.PRINTER: NUMA = 2 STATIONS$ = "DI:" CALL PRINTER REQ% = 00000H ! Set manual document insert ! requires operator to press Close button PUTLONG NUMA , REQ% INSERT.DOC: CLEARS DISPLAY WRITE #DISPLAY; "INSERT DOCUMENT" ! Test for document present REQ% = GETLONG (NUMA) STAT% = REQ% AND 00000030H IF STAT% <> 00000010H THEN GO TO INSERT.DOC WRITE FORM "C38 A1";#NUMA; "PRINT ON DOCUMENT WRITE FORM "C38 A2";#NUMA; "PRINT ON DOCUMENT WRITE FORM "C38 A3";#NUMA; "PRINT ON DOCUMENT WRITE FORM "C38 A4";#NUMA; "PRINT ON DOCUMENT CALL CLOSEA CLEARS DISPLAY WRITE #DISPLAY; "END OF PRINT SAMPLE" CLOSE DISPLAY GOTO END.PROG ERR.HNDLR: ! Prevent recursion ON ERROR GOTO END.PROG ! Determine error type ! and perform appropriate ! recovery and RESUME steps END.PROG: STOP END

SPACE SPACE SPACE SPACE SPACE

1 2 3 4 5

AFTER AFTER AFTER AFTER AFTER

" " " " "

AND AND AND AND

SPACE SPACE SPACE SPACE

1 2 3 4

AFTER AFTER AFTER AFTER

" " " "

Chapter 8. Using Input and Output Devices and Pipes

231

IBM 4689 Printer


OPEN Statement Use the OPEN statement to gain access to the printer driver.
OPEN CR: SJ: AS number

CR SJ

Customer receipt station Summary journal station

number A 2-byte integer variable or constant with a value of 1 to 99. WAIT Statement Use the WAIT statement to wait for data to become available from the printer driver.
WAIT number ; timeout.var

number The same 2-byte integer variable or constant assigned to the printer driver in the OPEN statement. timeout.var A 4-byte integer variable or constant that specifies the number of milliseconds to wait for data to become available from the printer driver. Note: Your application can wait on data from other device drivers while waiting for data from the printer driver. EVENT % Function Use the EVENT% function to determine if data has been received from the printer driver.
i2 = EVENT %

i2

A 2-byte integer that is set to one of three values: number The same 2-byte integer variable or constant assigned to the printer driver in the OPEN statement. This indicates that data has been received from the printer driver. 0000 No data has been received. The timeout value specified in the WAIT statement (timeout.var) has elapsed.

other value Data has been received from the driver that was assigned the 2-byte integer value on the OPEN statement. Note: A WAIT on multiple device drivers was issued.

232

IBM 4680 BASIC: Language Reference

WRITE # Statement Use the WRITE # statement to write the data to the printer driver.
WRITE # number var$

number The same 2-byte integer variable or constant assigned to the printer driver in the OPEN statement var$ A single string variable to contain the information to be sent to the printer.

Note: The maximum size of a WRITE buffer is 244 bytes. WRITE LOGO # Statement Use the WRITE LOGO # statement to print data on the middle 300-dot columns on the customer receipt station.
WRITE LOGO#number;array.element

number The same 2-byte integer variable or constant assigned to the appropriate print station in the OPEN statement. array.element The first element in an array of 1-byte integers to be printed. The number of elements in this one-dimensional array must be a multiple of 381. Each set of 381 elements is comprised of either 300 character slices followed by 80 unused bytes or 380 character slices followed by 80 unused bytes followed by one byte that contains the number of partial line feeds to be issued after the current data prints. RESUME Statement Use the RESUME statement to recover from an error associated with an OPEN, READ, GETLONG, PUTLONG, or CLOSE statement. Use the ON ASYNC ERROR CALL statement for errors associated with a WRITE # statement.
RESUME RETRY label

RETRY Enables the statement that caused the error to execute again. label A BASIC label local to the program module that identifies a statement to receive control in the event of an error.

GETLONG Statement Use the GETLONG function to get status information from the printer driver.
i4 = GETLONG ( number )

i4

A 4-byte integer that represents the driver status.

Chapter 8. Using Input and Output Devices and Pipes

233

number The same 2-byte integer variable or constant assigned to the printer driver in the OPEN statement The integer represents information in the form EELLMMSS. EE, LL, MM, and SS each represent one of the four bytes.
Table 17. GETLONG Byte EE Bit 0 0 1 2 3 3 (x08) 4 5 6 7 (x80) 1 0 1 Setting 0 1 Description Stream mode enabled Honor station mode enabled Reserved Reserved No IBM 4689 printer attached An IBM 4689 printer is attached Reserved Reserved Reserved Enhanced mode enabled. IBM 4689 printer commands must be used. This is required.

Table 18. GETLONG Byte LL Bit 0 1 2 3 4 5 6 7 Table 19. GETLONG Byte MM Bit 0 1 2 3 4 5 6 7 Setting 0 Description Mode 1 or Mode 2 printer installed Reserved Reserved Reserved Reserved Reserved Reserved Reserved Setting Description Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved

234

IBM 4680 BASIC: Language Reference

Table 20. GETLONG Byte SS Bit 0 1 1 2 2 3 3 4 5 6 7 7 Setting 0 0 1 0 1 0 1 0 0 0 0 0 Description Reserved Reserved Paper error at SJ (if bit 2=1) No paper error Paper error This is not a 4683 Model 2 printer This is a 4683 Model 2 printer Reserved Reserved Reserved Printer cover closed Printer cover open

PUTLONG Statement Use the PUTLONG statement to make changes to printer modes.
PUTLONG number , i4

number The same 2-byte integer variable or constant assigned to the printer driver in the OPEN statement. i4 A 4-byte integer that represents the requested mode changes for the printer.

The integer represents information in the form EEFFPPPP. EE, FF, PP, and PP each represent one of the four bytes. EE Determines the printer driver IBM 4689 printer commands will be accepted. The high order bit must be on to use IBM 4689 printer commands. The function to perform. The parameter associated with the function to perform.
Setting Description Reserved Reserved Reserved Reserved Reserved Reserved Reserved

FF PPPP

Table 21. PUTLONG Byte EE Bit 0 1 2 3 4 5 6

Chapter 8. Using Input and Output Devices and Pipes

235

Table 21. PUTLONG Byte EE (continued) Bit 7 (0x80) Setting 1 Description Set enhanced mode on. IBM 4689 printer commands must be used.

TCLOSE Statement Use the TCLOSE statement to suspend the application program until all outstanding print lines have been printed at all printer stations. Do not issue a TCLOSE statement from an ON ASYNC ERROR CALL statement subprogram.
TCLOSE # number

number The same 2-byte integer variable or constant assigned to the printer driver in the OPEN statement. CLOSE Statement Use the CLOSE statement to end communication with the printer driver.
CLOSE number

number The same 2-byte integer variable or constant assigned to the printer driver in the OPEN statement.

Fiscal Printers
Refer to the IBM 4690 OS Version 3: Programming Guide for information on how to program Fiscal Printers.

Scale Driver
There are four IBM 4680 BASIC statements you can use to communicate with the scale driver (SCALE:). OPEN Statement Use the OPEN statement to access the scale driver.
OPEN"SCALE:"ASnumber

number A 2-byte integer or constant with a value of 1 to 99. READ FORM # Statement Use the READ FORM # statement to read data from the scale driver.
READ FORMformat.string;#number;i4

format.string A constant string or variable with the value i4.

236

IBM 4680 BASIC: Language Reference

number The same 2-byte integer variable or constant assigned to the scale driver in the OPEN statement. i4 A 4-byte integer variable.

RESUME Statement Use the RESUME statement to recover from an error associated with opening or reading data from the scale driver.
RESUME RETRY label

RETRY Enables the OPEN or READ statement that caused the error to execute again. label An IBM 4680 BASIC label local to the program module that identifies a statement to receive control in the event of an error.

CLOSE Statement Use the CLOSE statement to end communication with the scale driver.
CLOSE number

number The same 2-byte integer variable or constant assigned to the personal identification number pad in the OPEN statement.

Example
This example reads the weight from the scale, displays it on the alphanumeric display, and stops. To run the example, put a weight on the scale and start the program.
%ENVIRON T INTEGER*4 hx%,sx%,WEIGHT% INTEGER*2 SCALE%,ANDSP% ON ERROR GOTO ERRORA ANDSP% = 1 SCALE% = 2 OPEN "ANDISPLAY:" as ANDSP% CLEARS ANDSP% !! INDICATE TERMINAL !! DEFINE VARIABLES !! !! !! !! !! INDICATE "ON ERROR" LABEL SET AN DISPLAY SESSION # TO 1 SET SCALE SESSION # TO 2 OPEN AN DISPLAY CLEAR AN DISPLAY

WRITE #ANDSP% ; "SAMPLE SCALE PROG" WAIT ; 5000 !! WAIT 5 SECONDS SO DISPLAY CAN BE READ CLEARS ANDSP% !! CLEAR AN DISPLAY OPEN "SCALE:" AS SCALE% !! OPEN THE SCALE WRITE #ANDSP% ; "SCALE OPEN" !! INDICATE THE SCALE WAS OPENED WAIT ; 5000 !! WAIT 5 SECONDS SO DISPLAY CAN BE READ CLEARS ANDSP% !! CLEAR DISPLAY WRITE #ANDSP% ; "READ THE SCALE NOW!" READ FORM "I4" ; #SCALE% ; WEIGHT% WRITE FORM "C10 PIC(####)" ; #ANDSP% ; " WEIGHT = ",WEIGHT% WAIT ; 6000 !! WAIT 6 SECONDS SO WEIGHT CAN BE READ LOCATE #ANDSP% ; 2,1 !! LOCATE TO SECOND LINE
Chapter 8. Using Input and Output Devices and Pipes

237

CLOSE SCALE% !! CLOSE SCALE WRITE #ANDSP% ; "SCALE IS CLOSED" WAIT ; 5000 !! WAIT 5 SECONDS SO MSG CAN BE READ STOP ERRORA: !!ERROR ASSEMBLY ROUTINE!! hx% = errn errfx$ = "" 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 A$=CHR$(THE.SUM%) errfx$ = errfx$ + A$ next s% clears ANDSP% write #ANDSP%;"err=",err," errl=",errl locate #ANDSP%;2,1 write #ANDSP%;"errf=",errf%," errn=",errfx$ wait ;15000 resume end

Shopper Display Driver


There are eight statements and functions you can use to communicate with the shopper display driver (SDISPLAY:). OPEN Statement Use the OPEN statement to gain access to the shopper display driver.
OPEN"SDISPLAY:"ASnumber

number A 2-byte integer or constant with a value ranging from 1 to 99. CLEARS Statement Use the CLEARS statement to clear the shopper display.
CLEARSnumber

number The same 2-byte integer variable or constant assigned to the shopper display in the OPEN statement. WRITE # Statement Use the WRITE # statement to display data and guidance indicators on the shopper display. You can optionally specify a format.string. The number of characters specified in the WRITE # statement cannot exceed 12, the maximum number of digits, commas, and decimal points supported by the shopper display. Each write operation places the data right-adjusted in the display and turns on the appropriate guidance indicators (See 259.)

238

IBM 4680 BASIC: Language Reference

WRITE #number;data.var FORMformat.string; ...,...

format.string A string constant or variable. The number of bytes represented by the string must be 40 or less. number The same 2-byte integer variable or constant assigned to the shopper display in the OPEN statement. data.var A string variable or a constant. GETLONG Function Use the GETLONG function to get status information from the shopper display driver.
i4 = GETLONG ( number )

i4

A 4-byte integer that represents the driver status.

number The same 2-byte integer variable or constant assigned to the shopper display in the OPEN statement. The integer represents information in the form AA000000. AA, 00, 00, and 00 each represent one of the four bytes. The last three bytes, 000000, are reserved for system use. Byte AA represents shopper display guidance indicator information as follows: Bit 0 (X'01') = 0 lower-right guidance indicator off Bit 0 = 1 lower-right guidance indicator on Bit 1 = 0 middle-right guidance indicator off Bit 1 = 1 middle-right guidance indicator on Bit 2 = 0 upper-right guidance indicator off Bit 2 = 1 upper-right guidance indicator on Bit 3 = 0 lower-left guidance indicator off Bit 3 = 1 lower-left guidance indicator on Bit 4 = 0 middle-left guidance indicator off Bit 4 = 1 middle-left guidance indicator on Bit 5 = 0 upper-left guidance indicator off Bit 5 = 1 upper-left guidance indicator on Bit 6 = 0 reserved Bit 7 = 0 reserved PUTLONG Statement Use the PUTLONG statement to specify guidance indicator settings to the shopper display driver.
PUTLONG number , i4

Chapter 8. Using Input and Output Devices and Pipes

239

number The same 2-byte integer variable or constant assigned to the driver in the OPEN statement. i4 A 4-byte integer that represents the requests to the driver.

The integer represents information in the form 000000AA. 00,00, 00, and AA each represent one of four bytes. The first three bytes, 000000, are reserved for system use. Byte AA represents shopper display guidance indicator information as follows: Bit 0 (X'01') = 0 lower-right guidance indicator off Bit 0 = 1 lower-right guidance indicator on Bit 1 = 0 middle-right guidance indicator off Bit 1 = 1 middle-right guidance indicator on Bit 2 = 0 upper-right guidance indicator off Bit 2 = 1 upper-right guidance indicator on Bit 3 = 0 lower-left guidance indicator off Bit 3 = 1 lower-left guidance indicator on Bit 4 = 0 middle-left guidance indicator off Bit 4 = 1 middle-left guidance indicator on Bit 5 = 0 upper-left guidance indicator off Bit 5 = 1 upper-left guidance indicator on Bit 6 = 0 reserved Bit 7 = 0 reserved READ FORM # Statement Use the READ FORM # statement to read data from the shopper display driver.
READ FORMformat.string;#number;data.var .... , .....

format.string A string constant or variable. number The same 2-byte integer variable or constant assigned to the shopper display in the OPEN statement. data.var A string variable. RESUME Statement Use the RESUME statement to recover from an error associated with the shopper display device.
RESUME RETRY label

RETRY Enables the statement that caused the error to execute again. label An IBM 4680 BASIC label local to the program module that identifies a statement to receive control in the event of an error.

240

IBM 4680 BASIC: Language Reference

CLOSE Statement Use the CLOSE statement to end communication with the shopper display driver.
CLOSE number

number The same 2-byte integer variable or constant assigned to the driver in the OPEN statement.

Example
The following program example contains code written to communicate with a shopper display. The program writes data to the display and turns on all guidance indicators.
%ENVIRON T INTEGER*4 LIGHTS DISPLAY1=1 DISPLAY2=2 ON ERROR GOTO ENDPROG ! Open video display. OPEN "VDISPLAY:" AS DISPLAY2 CLEARS DISPLAY2 WRITE FORM "C20"; #DISPLAY2; "video is open" WAIT;500 ! Open shopper display. OPEN "SDISPLAY:" AS DISPLAY1 WRITE FORM "C20"; #DISPLAY2; "shopper is open" WAIT;500 ! Clear shopper display. CLEARS DISPLAY1 WAIT;500 ! Set pointer data. LIGHTS = 00000001h PUTLONG DISPLAY1,LIGHTS ! Write data. WRITE FORM "C6"; #DISPLAY1;"111.11" WAIT;500 ! Set pointer data. LIGHTS = 00000002h PUTLONG DISPLAY1,LIGHTS ! write data WRITE FORM "C10"; #DISPLAY1;"22,222,222" WAIT;500 ! set pointer data LIGHTS = 00000004h PUTLONG DISPLAY1,LIGHTS ! Write data. WRITE FORM C6"; #DISPLAY1;"333.33" WAIT;500 ! Set pointer data. LIGHTS = 00000008h PUTLONG DISPLAY1,LIGHTS ! Write data. WRITE FORM "C6"; #DISPLAY1;"444.44" WAIT;500 ! Set pointer data. LIGHTS = 00000010h PUTLONG DISPLAY1,LIGHTS ! Write data. WRITE FORM "C8"; #DISPLAY1;"5,555,55"

Chapter 8. Using Input and Output Devices and Pipes

241

WAIT;500 ! Set pointer data. LIGHTS = 00000020h PUTLONG DISPLAY1,LIGHTS ! Write data. WRITE FORM "C12"; #DISPLAY1;"66.666.66" ! Clear displays. CLEARS DISPLAY1 CLEARS DISPLAY2 WRITE FORM "C30"; #DISPLAY2;" SHOPPER CLEARED - END TEST " STOP ENDPROG: ! Display error messages and perform appropriate recovery ! and resume steps. STOP END

Serial I/O Communications


You can use eight statements and functions to communicate with the serial communications (SERIAL I/O) driver. You must use the ON ASYNC ERROR CALL statement to handle errors associated with WRITE # operations to this driver. OPEN SERIAL Statement Use the OPEN SERIAL statement to establish an asynchronous communication line for a serial I/O port.
==300== =="E"=== OPEN SERIALn, , , speed parity ===7==== ===1==== , ASline.number data stop =====BUFFSIZE 128====== BUFFSIZE buffersize

n is numeric and specifies which of four serial ports to open. It must be in the range 1 to 4. The value specified for n converts automatically to a 2-byte integer, if necessary.

speed speed is a numeric value that specifies the transmit/receive bit rate in bits per second (bps). Allowed values are 110, 300, 1200, 2400, 4800, and 9600. The default value is 300. parity parity is a string whose leftmost character specifies parity for transmit/receive. The meaningful values are E (for even), O (for odd), and N (for none). The default is E. data stop data is a numeric indicating the number of transmit/receive data bits. The range of meaningful values is 5 to 8. The default is 7. stop is a numeric indicating the number of stop bits. The only meaningful values are 1 and 2. If data is 5, a value of 2 for stop indicates 1.5 stop bits. The default value is 1 unless speed is 110, in which case the default is 2.

242

IBM 4680 BASIC: Language Reference

line.number line.number is a unique identification number you assign to a line. A line.number can be any numeric expression that evaluates to a 2-byte integer ranging from 1 to 99. BUFFSIZE buffsize specifies the size of the I/O buffer in number of bytes. The maximum size is 247 bytes. READ # LINE Statement Use the READ # LINE statement to read data from a serial line. All data is read into a specified string variable. If an overflow error occurs, a full buffer is returned by the READ # LINE statement.
READ#line.number;LINEstring.var

line.number The same 2-byte integer variable or constant assigned to the line in the OPEN SERIAL statement. string.var A string variable to hold the input data. WAIT Statement Use the WAIT statement to wait for data to become available from the serial I/O driver. Use the EVENT% function to retrieve the session number that satisfied the wait.
============= WAITline.number ;timeout.val ,number ...........

line.number The same 2-byte integer variable or constant assigned to the line in the OPEN SERIAL statement. number An I/O session number assigned to another line, driver, or pipe. timeout.val A 4-byte integer variable or constant that specifies the number of milliseconds to wait for data to become available from the line, driver, or pipe. WRITE # Statement Use the WRITE # statement to write data to the SERIAL I/O line. You can optionally specify a format.string. The serial I/O driver buffers all data written to the line. A WRITE # ends successfully when all data in the write buffer has been transmitted. It ends with an error when a condition occurs that prevents the transmission of all data. Your application is responsible for checkpointing, positive response, and error recovery. Do not issue this statement from an ON ASYNC ERROR CALL subprogram.
WRITE #line.number;data.var FORMformat.string; ...,...

Chapter 8. Using Input and Output Devices and Pipes

243

format.string A string constant or string variable representing a value less than or equal to the BUFFSIZE value specified in the OPEN SERIAL statement. line.number The same 2-byte integer variable or constant assigned to the session in the OPEN SERIAL statement. data.var A variable or constant that identifies the data to be written. Numeric values are first converted to ASCII characters. Delimiting quotation marks for string values are not written. The runtime does not insert delimiters. The total length of data written to the SERIAL I/O driver must not exceed the BUFFSIZE value specified in the OPEN SERIAL statement. GETLONG Function Use the GETLONG function to get status information from the SERIAL I/O driver.
i4 = GETLONG ( line.number )

i4

A 4-byte integer that represents the driver status.

line.number The same 2-byte integer variable or constant assigned to the line in the OPEN SERIAL statement. The integer represents information in the form: TTCCS1S2. TT, CC, S1 and S2 each represent one of the four bytes. The definition of the bytes depends on whether this device is attached to a 4683 feature card, 4684, 4693, or 4694 serial port. Byte TT represents the timeout value in milliseconds. (See the following description of PUTLONG). This is the representation of the bytes CCS1S2 if the device is attached to an IBM 4683 feature card. Byte CC represents EIA control lines as follows: bit 0 (hex 01) = 0 Transmit whether DTR is active or not. Bit 0 should be 0 if the interface is defined as a current loop. bit 0 = 0 Do not wait for DTR before transmitting bit 0 = 1 wait for DTR before transmitting bit 1 = 0 DSR inactive bit 1 = 1 DSR active bit 2 = 0 Disable receiver bit 2 = 1 Enable reception from device bit 3 = 0 Reserved bit 4 = 0 Reserved

244

IBM 4680 BASIC: Language Reference

bit 5 = 0 CTS inactive bit 5 = 1 CTS active bit 6 = 1 DTR must be active for a READ or WAIT bit 6 = 0 DTR not required to be active for a READ or WAIT bit 7 = 0 Reserved Byte S1 represents status information as follows: bit 0 (hex 01) = 1 data available to be read bit 0 = 0 no data available to be read. After completion of a WAIT statement for this driver, check this bit to see if data is available or if there was an RTS or DTR status change. bit 1 = 0 No data was lost bit 1 = 1 Data may have been lost bit 2 = 0 Reserved bit 3 = 0 Reserved bit 4 = 0 Reserved bit 5 = 0 Reserved bit 6 = 0 Reserved bit 7 = 0 Reserved Byte S2 represents status information as follows: bit 0 (hex 01) = 0 Reserved bit 1 = 0 DTR inactive bit 1 = 1 DTR control line active bit 2 = 0 RTS inactive bit 2 = 1 RTS control line active bit 3 = 0 No parity error detected
Chapter 8. Using Input and Output Devices and Pipes

245

bit 3 = 1 Parity error from device bit 4 = 0 No framing error detected bit 4 = 1 Framing error from device bit 5 = 0 No break detected from device bit 5 = 1 Break detected from device bit 6 = 0 Reserved bit 7 = 0 Transmit buffer empty bit 7 = 1 Adapter transmit buffer not empty (must be empty to transmit) This is the representation of the bytes CCS1S2 if the device is attached to an IBM 4684, 4693, or 4694 serial port. Byte CC represents EIA control lines as follows: bit 0 (hex 01) = 0 transmit whether DSR is active or not. Bit 0 should be 0 if the interface is defined as a current loop. bit 0 = 0 Do not wait for DSR before transmitting bit 0 = 1 Wait for DSR before transmitting bit 1 = 0 DTR inactive bit 1 = 1 DTR active bit 2 = 0 Disable receiver. bit 2 = 1 Enable reception from device bit 3 = 0 Reserved bit 4 = 0 Reserved bit 5 = 0 RTS inactive bit 5 = 1 RTS active bit 6 = 1 DSR must be active for a READ or WAIT

246

IBM 4680 BASIC: Language Reference

bit 6 = 0 DSR not required to be active for a READ or WAIT bit 7 = 0 Reserved Byte S1 represents status information as follows: bit 0 (hex 01) = 1 data available to be read bit 0 = 0 no data available to be read. After completion of a WAIT statement for this driver, check this bit to see if data is available or if there was a CTS or DSR status change. bit 1 = 0 No data was lost bit 1 = 1 Data may have been lost bit 2 = 0 Reserved bit 3 = 0 Reserved bit 4 = 0 Reserved bit 5 = 0 Reserved bit 6 = 0 Reserved bit 7 = 0 Reserved Byte S2 represents status information as follows: bit 0 (hex 01) = 0 RESERVED bit 1 = 0 DSR inactive bit 1 = 1 DSR control line active bit 2 = 0 CTS inactive bit 2 = 1 CTS control line active bit 3 = 0 Reserved bit 3 = 1 parity error from device bit 4 = 0 Reserved
Chapter 8. Using Input and Output Devices and Pipes

247

bit 4 = 1 framing error from device bit 5 = 0 Reserved bit 5 = 1 break detected from device bit 6 = 0 Reserved bit 7 = 0 transmit buffer empty bit 7 = 1 adapter transmit buffer not empty (must be empty to transmit) PUTLONG Statement Use the PUTLONG statement to set a timeout value and to set the EIA control lines.
PUTLONGline.number,i4

line.number The same 2-byte integer variable or constant assigned to the line in the OPEN SERIAL statement. i4 A 4-byte integer that represents information as follows:

The integer must contain information in the form, 0000TTCC. 00, 00, TT, and CC each represent one of the four bytes. The first two bytes, 0000, are reserved for system use. Byte TT represents the timeout value in milliseconds. Byte CC represents status information as follows: For a device attached to an IBM 4683 or a non-IBM device that emulates a 4683 feature card bit 0 (hex 01) = 0 Transmit whether DTR is active or not. Bit 0 should be 0 if the interface is defined as a current loop. bit 0 = 0 Do not wait for DTR before transmitting bit 0 = 1 Wait for DTR before transmitting bit 1 = 0 DSR inactive bit 1 = 1 DSR active bit 2 = 0 Disable receiver bit 2 = 1 Enable reception from device bit 3 = 0 Do not send a break bit 3 = 1 Send a break to the device bit 4 = 0 Reserved

248

IBM 4680 BASIC: Language Reference

bit 5 = 0 CTS inactive bit 5 = 1 CTS active bit 6 = 0 DTR not required to be active for a READ or WAIT bit 6 = 1 DTR must be active for a READ or WAIT bit 7 = 0 Reserved Byte CC represents status information as follows: For a device attached to an IBM 4684, 4693, or 4694 serial port bit 0 (hex 01) = 0 Transmit whether DSR is active or not. Bit 0 should be 0 if the interface is defined as a current loop. bit 0 = 0 Do not wait for DSR before transmitting. bit 0 = 1 Wait for DSR before transmitting. bit 1 = 0 DTR inactive bit 1 = 1 DTR active bit 2 = 0 Disable receiver. bit 2 = 1 Enable reception from device. bit 3 = 0 Reserved bit 3 = 1 Send a break to the device. bit 4 = 0 Reserved bit 5 = 0 RTS inactive bit 5 = 1 RTS active bit 6 = 0 DSR not required to be active for a READ or WAIT bit 6 = 1 DSR must be active for a READ or WAIT. bit 7 = 0 Reserved. RESUME Statement Use the RESUME statement to recover from an error associated with the SERIAL I/O driver, except for errors associated with writing to the driver (use ON ASYNC ERROR CALL statement).
RESUME RETRY label

Chapter 8. Using Input and Output Devices and Pipes

249

RETRY Enables the statement that caused the error to execute again. label An IBM 4680 BASIC label local to the program module that identifies a statement to receive control in the event of an error.

CLOSE Statement Use the CLOSE statement to end communication with the SERIAL I/O driver.
CLOSE number

number The same 2-byte integer variable or constant assigned to the SERIAL I/O line in the OPEN SERIAL statement.

Example
Serial I/O runs on the RS232-EIA interface. This sample program uses the serial I/O interface to print the following 59-byte character set in a rippled pattern on a serial printer or video display using the RS232-EIA port. ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789&*:;@?,.$=!><()-%+#/ Make the following assumptions: 1. Port 2 = RS232 EIA INTERFACE 2. 9600 BPS Baud Rate 3. ASYNC DATA FORMAT a. NO PARITY b. 8 BIT CODE WITH 1 STOP BIT.
%ENVIRON T INTEGER*4 hx%,sx% INTEGER*2 ANDSP%,EIAP% ANDSP% = 1 EIAP% = 12 !! INDICATE TERMINAL !! DECLARE VARIABLES !! INIT I/O SESSIONS

SUB ASYNC.ERR(RFLAG,OVER) INTEGER*2 RFLAG STRING OVER RFLAG = 0 OVER = "" hx% = errn errfx$ = "" 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 A$=CHR$(THE.SUM%) errfx$ = errfx$ + A$ next s% clears ANDSP% write #ANDSP%;"err=",err," errl=",errl locate #ANDSP%;2,1 write #ANDSP%;"errf=",errf%," errn=",errfx$ wait ;15000 resume END SUB

250

IBM 4680 BASIC: Language Reference

ON ERROR GOTO ERRORA !! SET "ON ERROR" ON ASYNC ERROR CALL ASYNC.ERR !! SET "ON ASYNC ERROR" OPEN "ANDISPLAY:" AS ANDSP% !! OPEN AN DISPLAY CLEARS ANDSP% WRITE #ANDSP% ; "SERIAL I/O SAMPLE " WAIT ; 5000 !! WAIT 5 SECONDS ! -------------! ENABLE PORT 2 (RS232 EIA INTERFACE) AS I/O SESSION 12 ! -------------OPEN SERIAL 2,9600,"N",8,1 AS EIAP% BUFFSIZE 80 LOCATE #ANDSP% ; 2,1 !! LOCATE TO SEC LINE WRITE #ANDSP% ; "SER I/O PORT 2 OPEN" ! -------------! CONSTANT FOR 59 CHAR. RIPPLE PATTERN CHARACTER SET ! -------------BUF1$="ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789&*:;""@?,.$=!><()-%+#/ " BUF2$ = "ABCDEFGHIJKLMNOPQRST" B1$ = BUF1$ + BUF1$ + BUF2$ !!! 59 + 59 + 20 FOR RIPPLE 80 CHARS I% = 1 !!! VARIABLE FOR RIPPLE COUNTER WRITE #ANDSP% ; "START RIPPLE PRINT" EXERCISE: FOR I% = 1 TO 20 C1$ = MID$(B1$,I%,80) WRITE # EIAP%; C1$ NEXT I% CLOSE EIAP% WRITE #ANDSP% ; "END OF SAMPLE" CLOSE ANDSP% STOP ERRORA: !!ERROR ASSEMBLY ROUTINE!! hx% = errn errfx$ = ""

!!! MSG DATA-RIPLE PATRN !!! SEND 1 MSG EACH PASS !! CLOSE SERIAL I/O !! CLOSE AN DISPLAY !! STOP PROGRAM

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 A$=CHR$(THE.SUM%) errfx$ = errfx$ + A$ next s% clears ANDSP% write #ANDSP%;"err=",err," errl=",errl locate #ANDSP%;2,1 write #ANDSP%;"errf=",errf%," errn=",errfx$ wait ;15000 resume end

Tone Driver
You can use four statements to communicate with the tone (TONE:) driver. OPEN Statement Use the OPEN statement to access the tone driver.
OPEN"TONE:"ASnumber

Chapter 8. Using Input and Output Devices and Pipes

251

number A unique number to assign to the tone session (I/O session number). An I/O session number can be any numeric expression that evaluates to an integer ranging from 1 to 99. WRITE FORM # Statement Use the WRITE FORM # statement to sound the tone with a specified frequency and duration.
WRITE FORMformat.string;#number;frequency.var,duration.var

format.string A string constant or variable. The value specified here must be C4, C3. number The I/O session number assigned to the tone in the OPEN statement. frequency.var A string variable or constant with one of the following ASCII values: 750 1000 1800 - 750 Hertz - 1.0 kHertz - 1.8 kHertz

duration.var A string variable or constant with one of the following ASCII values: ON OFF HI LOW ddd Turn the tone on. (Tone remains on until you specify OFF.) Turn the tone off. Set the tone volume to high. Set the tone volume to low. Specifies the duration of the tone in tenths of a second. (Range is from 1 to 255.)

RESUME Statement Use the RESUME statement to recover from an error associated with the tone driver.
RESUME RETRY label

RETRY Enables the statement that caused the error to execute again. label An IBM 4680 BASIC label local to the program module that identifies a statement to receive control in the event of an error.

CLOSE Statement Use the CLOSE statement to end communication with the tone driver.
CLOSE number

252

IBM 4680 BASIC: Language Reference

number The I/O session number assigned to the tone in the OPEN statement.

Example
The following program example contains code written to communicate with the tone driver. The program writes a message to the display, runs a test of the tone device, and then writes another message to the display.
%ENVIRON T ! Declare a two byte integer INTEGER*2 DISPLAY INTEGER*2 TONE DISPLAY = 1 TONE = 2 ON ERROR GOTO ERR.HNDLR ! Open the display OPEN "ANDISPLAY:" AS DISPLAY CLEARS DISPLAY WRITE #DISPLAY; "START TONE TEST" WAIT ; 2000 OPEN "TONE:" AS TONE CLEARS DISPLAY WRITE #DISPLAY; "TONE" WAIT ;2000 WRITE FORM "C4,C3"; #TONE; "0750", "020" WAIT; 250 WRITE FORM "C4,C3"; #TONE; "1000", "020" WAIT; 250 WRITE FORM "C4,C3"; #TONE; "1800", "020" WAIT; 250 CLOSE TONE CLEARS DISPLAY WRITE #DISPLAY; "END TONE SAMPLE" CLOSE DISPLAY STOP ERR.HNDLR: ! prevent recursion ON ERROR GOTO END.PROG ! Determine error type ! and perform appropriate ! recovery and RESUME steps END.PROG: STOP END

Totals Retention Driver


You can use nine statements and functions to communicate with the totals retention driver (TOTRET:). OPEN Statement Use the OPEN statement to access the totals retention driver.
-=====================OPEN"TOTRET:"ASnumber| | |_BUFFSIZE buffersize _|

number A 2-byte integer or constant with a value of 1 to 99. buffersize Optional buffersize in number of bytes (default = 60).
Chapter 8. Using Input and Output Devices and Pipes

253

WRITE FORM # Statement Use the WRITE FORM # statement to write data to the totals retention driver. This statement allows you to access data based on the specified record number. A maximum of 60 bytes of data can be written in each record on a 4683, or a maximum of 1020 bytes can be written in each record on a 4693 or 4694. The driver will add four bytes (length and CRC) to each record. When calculating the next address to write, use the length of the last record written plus the four bytes added by the driver.
WRITE FORMformat.string;#number,address;data.var .... , .....

format.string A string constant or variable. The number of bytes represented by the string must be 60 or less for a 4683 or 4684, or 1020 bytes or less on a 4693 or 4694. number The same 2-byte integer variable or constant assigned to totals retention driver in the OPEN statement. address Specifies the starting location in bytes of where to write the data. You can specify a value ranging from 1 to 1020 (bytes) on a 4683 or 4684. You can specify a value ranging from 1 to 16380 (bytes) on a 4693 or 4694. Writing beyond these limits causes a runtime error. data.var A variable with the same data type as the format.string. The sum of the lengths of all the data variables must equal the number of characters in the format.string. WRITE # Statement Use the WRITE # statement to write data to the totals retention driver. You can write a maximum of 56 bytes of data in each record. The driver adds four bytes (length and CRC) to the record. Data is written to the driver in the same way data is written to a sequential file. The data is written at the location indicated by the totals retention sequential read/write pointer. A four byte end-of-file marker (EOF) is written after the record. The sequential file pointer is updated after each write and points to the EOF marker where the next record will be written.
WRITE#number;string.var

number The same 2-byte integer variable or constant assigned to the line in the OPEN statement. string.var A string variable that identifies the data to be written. The data must be less than or equal to 56 bytes on a 4683 or 4684, or 1016 bytes on a 4693 or 4694. The runtime does not insert delimiters. Therefore, this statement should only specify one string variable. READ FORM # Statement Use the READ FORM # statement to read data from the totals retention driver. The data is read from the driver in the same way data is read from a direct file.

254

IBM 4680 BASIC: Language Reference

READ FORMformat.string;#number,address;data.var .... , .....

format.string A string constant or variable. The number of bytes represented by the string must be 60 or less for a 4683 or 4684, or 1020 bytes or less on a 4693 or 4694. number The same 2-byte integer variable or constant assigned to the totals retention driver in the OPEN statement. address Specifies the starting location in bytes of where to write the data. You can specify a value ranging from 1 to 1020 (bytes) on a 4683 or 4684. You can specify a value ranging from 1 to 16380 (bytes) on a 4693 or 4694. Writing beyond these limits causes a runtime error. data.var A string variable or a constant with a data type that matches the data type of the format.string. READ # LINE Statement Use the READ # LINE statement to read data from the totals retention driver. The data is read from the driver in the same way data is read from a sequential file. The sequential read/write pointer indicates the starting location for the data to be read. The pointer is incremented to the start of the next record or end-of-file (EOF) after the read.
READ#number;LINEstring.var

number The same 2-byte integer variable or constant assigned to the driver in the OPEN statement. string.var A string variable to hold the input data. When the read is completed, the data in the variable is less than or equal to 56 bytes on a 4683 or 4684, or 1016 bytes on a 4693 or 4694. PTRRTN Function Use the PTRRTN function to get the offset of the last record sequentially read from or written to the totals retention driver.
i4 = PTRRTN

i4

A 4-byte integer that contains the offset value

The upper two bytes of the 4-byte integer is reserved for system use. The offset value is in the lower two bytes. The integer must contain information in the form, 0000PPPP. 00, 00, PP, and PP each represent one of the four bytes. The first two bytes, 0000, are reserved for system use. The last two bytes, PPPP, contain the offset value. POINT Statement Use the POINT statement to specify the offset for the next sequential read or write. Each record contains four bytes of overhead for length and CRC checking. You
Chapter 8. Using Input and Output Devices and Pipes

255

must account for these bytes when calculating a POINT offset. If you specify a POINT offset followed by a write operation, a 4-byte EOF marker is always written afterward.
POINTnumber;i4

number The same 2-byte integer variable or constant assigned to the driver in the OPEN statement. i4 A 4-byte integer that specifies the offset for the next sequential read or write.

RESUME Statement Use the RESUME statement to recover from an error associated with the totals retention driver.
RESUME RETRY label

RETRY Enables the statement that caused the error to execute again. label An IBM 4680 BASIC label local to the program module that identifies a statement to receive control in the event of an error.

CLOSE Statement Use the CLOSE statement to end communication with the totals retention driver.
CLOSE number

number The same 2-byte integer variable or constant assigned to the driver in the OPEN statement.

Example
The following program example contains code written to communicate with the totals retention driver. The program writes a message to the display, runs a test of the totals retention device by writing data to it and then reading data from it. It then compares the data that it stored with the original data, writing messages about the results of the comparison to the display.
%ENVIRON T ! Totals Retention sample ! Define the variables INTEGER*2 HARDTOT, DISPLAY,I1,I2 INTEGER*2 J1,J2,OFFSET INTEGER*4 I3,I4,J3,J4,TIME REAL R1,R2 STRING DATA1$,DATA2$,RDMFMT$ ! Set up the error handler ON ERROR GOTO ERROR1 ! Open the Totals Retention Driver, and ! the AN Display for messages HARDTOT = 1 DISPLAY = 2 TIME = 5000

256

IBM 4680 BASIC: Language Reference

OPEN "ANDISPLAY:" AS DISPLAY OPEN "TOTRET:" AS HARDTOT CLEARS DISPLAY WRITE #DISPLAY; "START OF TOTALS RETENTION SAMPLE" WAIT ; TIME ! Initialize the variables OFFSET = 1 R1 = 100.3 I1 = 1 I2 = 2 DATA1$ = "ABCDEFGHIJKLMNOPQRSTUVWXYZ7890" I3 = 35 I4 = 36 RDMFMT$ = "R 2I2 C30 2I4" ! Write the data in the totals retention area of storage. WRITE FORM RDMFMT$;#HARDTOT,OFFSET;R1,I1,I2,DATA1$,I3,I4 CLEARS DISPLAY WRITE #DISPLAY; "WRITE COMPLETE WAIT ;TIME ! Then read the data back, and compare with the original ! data. This portion of the example could be executed ! after a power down situation to demonstrate the Totals ! retention feature. RDMREAD: READ FORM RDMFMT$;#HARDTOT,OFFSET;R2,J1,J2,DATA2$,J3,J4 300 ! Compare The data read with original data. CLEARS DISPLAY IF R1 = R2 THEN \ WRITE # DISPLAY; "REAL DATA COMPARES OK"\ ELSE \ WRITE # DISPLAY; "REAL DATA DOESNT COMPARE OK " WAIT ; TIME CLEARS DISPLAY IF I1 = J1 THEN \ WRITE # DISPLAY;"INTEGER DATA COMPARES OK -1 " \ ELSE \ WRITE # DISPLAY; "INTEGER DATA DOESNTCOMPARE OK -1" WAIT ; TIME CLEARS DISPLAY IF I2 = J2 THEN \ WRITE # DISPLAY;"INTEGER DATA COMPARES OK -2 " \ ELSE \ WRITE # DISPLAY ;"INTEGER DATA DOESNTCOMPARE OK -2" WAIT ; TIME CLEARS DISPLAY IF I3 = J3 THEN \ WRITE # DISPLAY;"INTEGER DATA COMPARES OK -3 " \ ELSE\ WRITE # DISPLAY;"INTEGER DATA DOESNTCOMPARE OK -3" WAIT ; TIME CLEARS DISPLAY IF I4 = J4 THEN \ WRITE # DISPLAY;"INTEGER DATA COMPARES OK -4 " \ ELSE \ WRITE # DISPLAY;"INTEGER DATA DOESNTCOMPARE OK -4" WAIT ; TIME CLEARS DISPLAY IF DATA1$ = DATA2$ THEN \ WRITE # DISPLAY;"CHARACTER DATA COMPARES OK " \ ELSE \ WRITE # DISPLAY:"CHARACTER DATA DOESNT COMPARE OK " WAIT ; TIME CLEANUP: CLOSE HARDTOT
Chapter 8. Using Input and Output Devices and Pipes

257

CLEARS DISPLAY WRITE # DISPLAY;"END OF TOTALS CLOSE DISPLAY STOP ERROR1: ! Prevent recursion ON ERROR GOTO ERROR2 ! Determine error type and ! perform appropriate recovery ! and RESUME steps ERROR2: STOP END

RETENTION SAMPLE

"

Video Display Driver


Use the following statements and functions to communicate with either the VGA video driver, or the Feature A video driver (for 4683 terminals only). Although the application programming interface (API) to these drivers is the same, there are some restrictions when using the Feature A attribute with the VGA video driver. There are extensions to the API for the VGA video driver that overcome these restrictions as well as providing additional function. See the PUTLONG statement for more information. These extensions are available with 4690 OS at level 9620 or higher. Note: If DBCS is enabled, only the VGA attribute can be used. The other extensions are not available. OPEN Statement Use the OPEN statement to gain access to the video display driver.
OPEN"VDISPLAY:"..AS..number..

for the first video display, and


OPEN"VDISPLAY2:"..AS..number..

for the second video display. OPEN sets the current character location to row 1, column 1 (1,1). number A unique number to assign to the video display session (I/O session number). An I/O session number can be any numeric expression that evaluates to an integer ranging from 1 to 99. LOCATE # Statement Use the LOCATE # statement to set the current character location. This is the starting coordinates of where to write to or read from the video display.
LOCATE#number;row.value,column.value ==,ON=== ,OFF

258

IBM 4680 BASIC: Language Reference

number The I/O session number assigned to the video display in the OPEN statement. row column A 2-byte integer or constant that can range from 1 to the maximum number of columns of the current video display format. ON OFF Sets the cursor on (visible). ON is the default. Sets the cursor off (invisible). A 2-byte integer or constant that can range from 1 to the maximum number of rows of the current video display format.

For DBCS error handling: v If the cursor position is located at the second byte of a double-byte character, the cursor will move one position to the right. v If the cursor moves one position to the right and the last character of the string ends on the last column, the cursor is moved to the first column of the next row. v If the cursor moves one position to the right and the last character of the string ends on the last column and last row of the display, the cursor is set to row 1, column 1 (1,1). CLEARS Statement Use the CLEARS statement to clear the video display and set the current character location to row 1, column 1 (1,1).
CLEARSnumber

number The I/O session number assigned to the video display in the OPEN statement. WRITE # Statement Use the WRITE # statement to display data on the video display. You can optionally specify a format string.
WRITE #number;data.var FORMformat.string;

format A string constant or variable that specifies the format of the data to be written. number The I/O session number assigned to the video display in the OPEN statement. data A string variable or constant that contains the data to be written to the video display.

PUTLONG function Use the PUTLONG statement to change the video display format, to control the way data is interpreted on READ FORM # and WRITE statements, to change the character attribute and with VGA extensions to control the type of attribute.

Chapter 8. Using Input and Output Devices and Pipes

259

Note: If DBCS is enabled, only the VGA attribute can be used. The other extensions are not available.
PUTLONG number , i4

number The I/O session number assigned to the video display in the OPEN statement. i4 A 4-byte integer that represents the requests to the video display driver.

The following section details the syntax of the 4-byte request to the video driver.
VVMMCCAA

VV

Controls VGA extensions to the video API Attribute type - bit 0 Controls the format of the attribute byte (byte AA) 0 1 Feature A attribute VGA attribute

Underlining - bit 1 Controls whether or not underlining is enabled for a monochrome display. Attribute type must be VGA (Byte VV, bit 0 = 1). 0 1 Underlining is disabled Underlining is enabled

See Table 23 on page 267 for instructions on how to generate underlined characters when underlining is enabled. Intensify background colors - bit 2 Controls whether or not background intensified colors are enabled Attribute type must be VGA (Byte VV, bit 0 = 1). 0 1 Bits 7-3 Reserved Note: This byte is reserved when using the Feature A video driver. MM This byte is used to select the current video display format (rows x columns). Bits 4-1 are used to select the video display format. The remaining bits are reserved. 0001 (02H) Switch to 12 x 40 0010 (04H) Switch to 16 x 60 Background intensified colors are disabled. Blinking is enabled. Background intensified colors are enabled. Blinking is disabled.

260

IBM 4680 BASIC: Language Reference

Note: When using the VGA video driver this video display format results in a 16 row by 60 column character window centered on a 16 row x 80 column character screen. Character positions 1-10 and 61-80 are blank and not accessible by the application. Accessing character location (1,1) is actually character position (11,1) VGA supports only 40 or 80 columns while in character mode. 0100 (08H) Switch to 25 x 80 1000 (10H) Switch to 16 x 80 Note: (VGA extension). This video display format is not available when using the Feature A video driver. When no video display format is selected, the existing video display format is maintained. Note: With DBCS enabled, display modes other than 25 x 80 are restricted by font size. With these display modes, the display rectangle will be centered on the screen. CC Controls options for subsequent READ FORM # and Write statements. Command stacking - bit 0 Controls the command stacking function. 0 1 Flush stacked commands / Command stacking off Command stacking on

Note: Command stacking is not supported in the VGA video driver. This bit is ignored. Read data - bit 1 Controls whether character or attribute data is returned on subsequent READ FORM # statements. 0 1 Return character data Return attribute data

Attribute update - bit 2 Controls whether or not the attribute is to be updated for each character being written on subsequent WRITE statements. 0 1 Update the attribute for each character written Do not change the attribute when each character is written.

Write data - bit 3 Controls whether character or attribute data is provided on subsequent WRITE statements. 0 1 AA Data provided contains character data Data provided contains attribute data

This byte is used to set the current character attribute. The attribute can be in one of two formats depending upon whether VGA extensions to the video API are used.

Chapter 8. Using Input and Output Devices and Pipes

261

Feature A attribute format When using the Feature A video driver or the VGA video driver with VGA attribute not set (Byte VV bit 0 = 0), the format is: Reverse video - bit 0 Whether the color is for the foreground (the character) or the background. 0 1 Color is for the foreground. The background is black. Color is for the background. The foreground is black.

Blinking - bit 1 Whether the character blinks. 0 1 Character does not blink Character blinks

Blank - bit 2 Whether the character is blank 0 1 Character is not blank Character is blank (both foreground and background color is black)

Intensify color - bit 3 Whether the color is intensified. 0 1 Color is not intensified Color is intensified

Note: The VGA video driver does not support background intensified colors using the Feature A attribute. VGA extensions must be used to get background intensified colors. Underlining - bit 4 Whether the character is underlined. 0 1 Character is not underlined Character is underlined

Note: The VGA video driver does not support underlining using the Feature A attribute. VGA extensions must be used to get underlining. Red Color - bit 5 Whether the color includes red 0 1 Color does not include red Color includes red

Blue color - bit 6 Whether the color includes blue 0 1 Color does not include blue Color includes blue

Green Color - bit 7 Whether the color includes green

262

IBM 4680 BASIC: Language Reference

0 1

Color does not include green Color includes green

Note: If a monochrome Feature A video display is configured, the Feature A video driver sets the green bit on. See Table 24 on page 268 for a description of the color produced using the combinations of color bits and the intensify bit in the Feature A attribute. VGA attribute format When using the VGA video driver and the attribute is a VGA attribute (Byte VV, bit 0 = 1), the format is: Foreground blue or underline - bit 0 Whether the foreground color includes blue If underline is set (Byte VV, bit 1 = 1) and the video display is monochrome (Byte SS, bit 7 = 0 returned from the GETLONG function), then this bit is used to indicate whether or not the character is underlined. No other color bits can be set (in either foreground or background) to get the character underlined. 0 1 Foreground color does not include blue or character is not underlined Foreground color does include blue or character is underlined

Foreground green - bit 1 Whether the foreground color includes green 0 1 Foreground color does not include green Foreground color does include green

Foreground red - bit 2 Whether the foreground color includes red 0 1 Foreground color does not include red Foreground color does include red

Intensify foreground color - bit 3 Whether the foreground color is intensified 0 1 Foreground color is not intensified Foreground color is intensified

Background blue - bit 4 Whether the background color includes blue 0 1 Background color does not include blue Background color does include blue

Background green - bit 5 Whether the background color includes green 0 1 Background color does not include green Background color does include green

Chapter 8. Using Input and Output Devices and Pipes

263

Background red - bit 6 Whether the background color includes red 0 1 Background color does not include red Background color does include red

Blink or intensify background color - bit 7 Whether the character blinks If intensified background colors is set (Byte VV, bit 2 = 1), then this bit is used to indicate whether or not the background color is intensified (blinking is disabled) 0 1 Character is not blinking or background color is not intensified Character is blinking or background color is intensified

See Table 22 on page 266 for a description of the color and underlining produced using the combinations of color bits and the intensify bits in the VGA attribute. GETLONG function Use the GETLONG function to get information from the video display driver.
i4 = GETLONG ( number )

i4

A 4-byte integer that is set to the information from the video display driver in the following format:

The following section describes the syntax of the 4 bytes of information returned from the video driver.
AASSCCRR

AA

Represents the current character attribute. See the PUTLONG Statement for a description of Byte AA.

SS

Represents video display information as follows Cursor visibility - bit 0 Whether the cursor is visible 0 1 Cursor is invisible Cursor is visible

VGA Underlining - bit 1 (VGA extension) Whether underlining is enabled for a VGA monochrome display. 0 1 Underlining is disabled Underlining is enabled

Note: This bit is reserved when using the Feature A video driver. VGA Intensify background colors - bit 2 (VGA extension) Whether background intensified colors are enabled

264

IBM 4680 BASIC: Language Reference

0 1

Background intensified colors are disabled. Blinking is enabled. Background intensified colors are enabled. Blinking is disabled.

Note: This bit is reserved when using the Feature A video driver. Video display format - bits 5-3 Current video display format 000 001 010 25x80 12x40 6x20 Note: Feature A video driver only. 011 100 16x60 16x80

Note: (VGA extension). This video display format is not available when using the Feature A video driver. Attribute type - bit 6 (VGA extension) The format of the attribute byte (AA) 0 1 Feature A attribute VGA attribute

Note: This bit is reserved when using the Feature A video driver. Display type - bit 7 Whether the display is color or monochrome. 0 1 CC RR Display is monochrome Display is color

Represents the column number of the current character location. Represents the row number of the current character location.

number The I/O session number assigned to the video display in the OPEN statement. READ FORM # Statement Use the READ FORM # statement to read data from the video display driver.
READ FORMformat.string;#number;i4

format A string constant or variable that specifies the format of the data to be written. number The I/O session number assigned to the video display in the OPEN statement. data A string variable to contain the data to be read from the video display.
Chapter 8. Using Input and Output Devices and Pipes

265

CLOSE Statement Use the CLOSE statement to end communication with the video display driver.
CLOSE number

number The I/O session number assigned to the video display in the OPEN statement.
Table 22. Identifies the Foreground and Background Colors Generated Using the VGA Attribute on a Color Display. This attribute can only be used with the VGA video driver. For example, the attribute 51H results in blue characters on a magenta background, while 15H results in magenta characters on a blue background. Background intensified colors Background intensified colors are only available when background intensified colors are enabled (Byte VV, bit 2=1 on the PUTLONG Statement). If not, then the background intensity bit is used to specify blinking. Background intensified colors display as non-intensified colors with blinking characters if Byte VV, bit 2=0. For example, the attribute 95H results in blinking magenta characters on a blue background if Byte VV, bit 2=0. The same attribute results in magenta characters on a light blue background (no blinking) if Byte VV, bit 2=1. Intensify 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 Red 0 0 0 0 1 1 1 1 0 0 0 0 1 1 1 1 Green 0 0 1 1 0 0 1 1 0 0 1 1 0 0 1 1 Blue 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1 Attribute nibble 0H 1H 2H 3H 4H 5H 6H 7H 8H 9H AH BH CH DH EH FH Color Displayed Black Blue Green Cyan Red Magenta Brown Light gray Dark gray Light blue Light green Light cyan Light red Light magenta Light brown/yellow White

266

IBM 4680 BASIC: Language Reference

Table 23. Identifies the Foreground and Background Colors Generated Using the VGA Attribute on a Monochrome Display. This attribute can only be used with the VGA video driver. For example, the attribute 51H results in blue characters on a magenta background, while 15H results in magenta characters on a blue background. Background intensified color (White) White is only available in the background when background intensified colors have been enabled. (Byte VV, bit 2=1 on the PUTLONG Statement). If not, then the background intensity bit is used to specify blinking. A White background displays as Gray with blinking characters, if Byte VV, bit 2=0. For example, the attribute F0H results in blinking black characters on a gray background if Byte VV, bit 2=0. The same attribute results in black characters on a white background (no blinking), if Byte VV, bit 2=1. Underlining Setting the blue foreground color bit )with no other color bits set in either the foreground or background mibble) generated underlining when underlining has been enabled. (Byte VV, bit 1=1 on the PUTLONG Statement). The following attributes display underlined, if Byte VV, bit 1=1: v 0x01 v 0x09 v 0x81 v 0x89

Intensify 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1

Red 0 0 0 0 1 1 1 1 0 0 0 0 1 1 1 1

Green 0 0 1 1 0 0 1 1 0 0 1 1 0 0 1 1

Blue 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1

Attribute nibble 0H 1H 2H 3H 4H 5H 6H 7H 8H 9H AH BH CH DH EH FH

Color Displayed Black Gray/Underline Gray Gray Gray Gray Gray Gray Black White/Underline White White White White White White

Chapter 8. Using Input and Output Devices and Pipes

267

Table 24. Identifies Color Generated Using the Feature A Attribute on a Color Display. This attribute can be used with the Feature A or the VGA video driver. Bit 0 of the Feature A attribute determines whether or not the color is for the foreground or the background. The other color is black. For example, the attribute 80H results in green characters on a black background while 81H results in black characters on a green background. Background intensified colors Background intensified colors using the Feature A attribute are available only when using the Feature A driver. Intensified background colors display as non-intensified when using the Feature A attribute with the VGA video driver. Green - bit 7 0 0 0 0 1 1 1 1 0 0 0 0 1 1 1 1 Blue - bit 6 0 0 1 1 0 0 1 1 0 0 1 1 0 0 1 1 Red - bit 5 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1 Intensity - bit 3 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 Attribute 00H 20H 40H 60H 80H A0H C0H E0H 08H 28H 48H 68H 88H A8H C8H E8H Color Displayed Black Red Blue Magenta Green Brown Cyan Light gray Black Light red Light blue Light magenta Light green Light brown/yellow Light cyan White

Table 25. Identifies Color Generated Using the Feature A Attribute on a Monochrome Display. This attribute can be used with the Feature A or the VGA video driver. Bit 0 of the Feature A attribute determines whether the color is for the foreground or the background. The other color is black. For example, the attribute E8H results in white characters on a black background while E9H results in black characters on a white background. Background intensified color (White) A White background using the Feature A attribute is available only when using the Feature A video driver. White background is displayed as Gray when using the Feature A attribute with the VGA video driver. Green - bit 7 0 0 Blue - bit 6 0 0 Red - bit 5 0 1 Intensity - bit 3 0 0 Attribute 00H 20H Color Displayed Black Gray

268

IBM 4680 BASIC: Language Reference

Table 25. Identifies Color Generated Using the Feature A Attribute on a Monochrome Display (continued). This attribute can be used with the Feature A or the VGA video driver. Bit 0 of the Feature A attribute determines whether the color is for the foreground or the background. The other color is black. For example, the attribute E8H results in white characters on a black background while E9H results in black characters on a white background. Background intensified color (White) A White background using the Feature A attribute is available only when using the Feature A video driver. White background is displayed as Gray when using the Feature A attribute with the VGA video driver. Green - bit 7 0 0 1 1 1 1 0 0 0 0 1 1 1 1 Blue - bit 6 1 1 0 0 1 1 0 0 1 1 0 0 1 1 Red - bit 5 0 1 0 1 0 1 0 1 0 1 0 1 0 1 Intensity - bit 3 0 0 0 0 0 0 1 1 1 1 1 1 1 1 Attribute 40H 60H 80H A0H C0H E0H 08H 28H 48H 68H 88H A8H C8H E8H Color Displayed Gray Gray Gray Gray Gray Gray Black White White White White White White White

Example
The following example contains these functions: Writes to the video display using Feature A attributes Determines if the video display is being supported by the VGA or Feature A driver Writes to the video display using VGA attributes if a VGA driver Saves the screen Clears the video display and then restores the screen.
%ENVIRON T INTEGER*4 PUTLDATA INTEGER*2 VDISP, VGADRIVER STRING TSTATUS, CHARS, FAATTRS, VGAATTRS ! ADXSERVE subroutine SUB ADXSERVE (RET,FUNC,PARM1,PARM2) EXTERNAL INTEGER*4 RET INTEGER*2 FUNC,PARM1 STRING PARM2 END SUB

Chapter 8. Using Input and Output Devices and Pipes

269

! Establish an error routine. ON ERROR GOTO ERROR1 ! Open the video display. VDISP = 2 OPEN "VDISPLAY:" AS VDISP ! Change video display format to 25x80, and gray Feature A attribute PUTLDATA = 000800E0H PUTLONG VDISP, PUTLDATA ! Display Feature A attribute examples title line WRITE #VDISP; "Following are examples of Feature A attributes:" ! Set character location to (3,1), set green blinking Feature A attribute ! and display test line LOCATE #VDISP; 3,1,OFF PUTLDATA = 00000082H PUTLONG VDISP, PUTLDATA WRITE #VDISP; "Green blinking characters on black background" ! Set character location to (4,1), set red reverse Feature A attribute ! and display test line LOCATE #VDISP; 4,1,OFF PUTLDATA = 00000021H PUTLONG VDISP, PUTLDATA WRITE #VDISP; "Black characters on red background" ! Set character location to (5,1), set blue Feature A attribute ! and display test line LOCATE #VDISP; 5,1,OFF PUTLDATA = 00000040H PUTLONG VDISP, PUTLDATA WRITE #VDISP; "Blue characters on black background" ! Set character location to (6,1), set magenta Feature A attribute ! and display test line LOCATE #VDISP; 6,1,OFF PUTLDATA = 00000060H PUTLONG VDISP, PUTLDATA WRITE #VDISP; "Magenta characters on black background" ! Set character location to (7,1), set magenta intensified Feature A attribute ! and display test line LOCATE #VDISP; 7,1,OFF PUTLDATA = 00000068H PUTLONG VDISP, PUTLDATA WRITE #VDISP; "Light magenta characters on black background" ! Set character location to (8,1), set white underlined Feature A attribute ! and display test line ! Note: Will not be underlined on VGA video display LOCATE #VDISP; 8,1,OFF PUTLDATA = 000000F0H PUTLONG VDISP, PUTLDATA WRITE #VDISP; "White underlined characters on black background" ! If have a VGA video display then display test lines for some VGA attributes VGADRIVER = 0 CALL ADXSERVE(RET,4,0,TSTATUS) IF (RET = 0) AND (MID$(TSTATUS,48,1) = "1") THEN \ BEGIN ! Set we have a VGA video driver VGADRIVER = 1 ! Set character location (10,1), set gray VGA attribute

270

IBM 4680 BASIC: Language Reference

! and display VGA attribute examples title line LOCATE #VDISP; 10,1,OFF PUTLDATA = 01000007H PUTLONG VDISP, PUTLDATA WRITE FORM "C80"; #VDISP; "Following are examples of VGA attributes:" ! Set character location (12,1), set green foreground and black ! background VGA attribute and display test line LOCATE #VDISP; 12,1,OFF PUTLDATA = 01000002H PUTLONG VDISP, PUTLDATA WRITE FORM "C80"; #VDISP; "Green characters on a black background" ! Set green foreground and brown ! background VGA attribute and display test line PUTLDATA = 01000062H PUTLONG VDISP, PUTLDATA WRITE FORM "C80"; #VDISP; "Green characters on a brown background" ! Set cyan foreground and red background ! VGA attribute and display test line PUTLDATA = 01000043H PUTLONG VDISP, PUTLDATA WRITE FORM "C80"; #VDISP; "Cyan characters on a red background" ! Set blue foreground, gray background, ! blinking VGA attribute and display test line PUTLDATA = 010000F1H PUTLONG VDISP, PUTLDATA WRITE FORM "C80"; #VDISP; "Blue blinking characters on gray background" ! Set magenta background, white foregound ! VGA attribute and display test line PUTLDATA = 0100005FH PUTLONG VDISP, PUTLDATA WRITE FORM "C80"; #VDISP; "White characters on magenta background" ! Set red foreground, green background ! VGA attribute and display test line PUTLDATA = 01000024H PUTLONG VDISP, PUTLDATA WRITE FORM "C80"; #VDISP; "Red characters on green background" ! Announce about to enable background intensified colors WRITE FORM "C80"; #VDISP; "About to enable background intensified colors" ! Wait 5 seconds WAIT; 5000 ! Set character location to (18,1), set light red foreground, ! yellow background VGA attribute, enable intensify background colors ! and display test lines LOCATE #VDISP; 18,1,OFF PUTLDATA = 050000ECH PUTLONG VDISP, PUTLDATA WRITE FORM "C80"; #VDISP; "Background intensified colors enabled and blinking disabled" WRITE FORM "C80"; #VDISP; " for entire screen - light red characters on yellow background" ! Announce about to enable underlining WRITE FORM "C80"; #VDISP; "About to enable underlining" ! Wait 5 seconds WAIT; 5000 ! Set character location to (20,1), set light blue foreground, gray background ! VGA attribute, enable intensify background colors and underlining ! and display test lines
Chapter 8. Using Input and Output Devices and Pipes

271

! Note: Will be light blue characters without underlining on color display LOCATE #VDISP; 20,1,OFF PUTLDATA = 07000079H PUTLONG VDISP, PUTLDATA WRITE FORM "C80"; #VDISP; "Underlining enabled for entire screen -" WRITE FORM "C80"; #VDISP; " white underlined characters on gray background" ! Announce about to disable underlining and background intensified colors WRITE FORM "C80"; #VDISP; "About to disable underlining and background intensified colors" ! Wait 5 seconds WAIT; 5000 ! Set character location to (22,1), set light magenta foreground, ! blue background VGA attribute, disable intensify background colors ! and underlining and display test lines LOCATE #VDISP; 22,1,OFF PUTLDATA = 0100001DH PUTLONG VDISP, PUTLDATA WRITE FORM "C80"; #VDISP; "Background intensified colors disabled, blinking enabled, WRITE FORM "C80"; #VDISP; " and underlining disabled for entire screen - " WRITE FORM "C80"; #VDISP; " light magenta characters on blue background" ENDIF ! Set gray Feature A attribute ! and display about to clear the screen LOCATE #VDISP; 25,1,OFF PUTLDATA = 000000E0H PUTLONG VDISP, PUTLDATA WRITE FORM "C80"; #VDISP; "Now lets clear the screen" !********************************************************************* ! Save the screen for restoring later !********************************************************************* ! Read characters from video display LOCATE #VDISP; 1,1,OFF READ FORM "C2000"; #VDISP; CHARS ! Set read mode to read Feature A attributes, set character location ! to (1,1) and read the attributes PUTLDATA = 000002E0H PUTLONG VDISP, PUTLDATA LOCATE #VDISP; 1,1,OFF READ FORM "C720"; #VDISP; FAATTRS ! If have a VGA driver then save VGA attributes IF (VGADRIVER = 1) THEN \ BEGIN ! Set read mode to read VGA attributes then read PUTLDATA = 01000207H PUTLONG VDISP, PUTLDATA LOCATE #VDISP; 10,1,OFF READ FORM "C1200"; #VDISP; VGAATTRS ENDIF ! Wait 5 seconds then clear WAIT; 5000 CLEARS VDISP !********************************************************************* ! Restore the screen !********************************************************************* LOCATE #VDISP; 1,1,OFF

"

272

IBM 4680 BASIC: Language Reference

WRITE FORM "C80"; #VDISP; "Now lets restore the screen" ! Wait 3 seconds WAIT; 3000 ! Set write mode to write Feature A attributes then write them PUTLDATA = 000008E0H PUTLONG VDISP, PUTLDATA LOCATE #VDISP; 1,1,OFF WRITE FORM "C720"; #VDISP; FAATTRS ! If have a VGA driver then restore VGA attributes IF (VGADRIVER = 1) THEN \ BEGIN ! Set write mode to write VGA attributes then write them PUTLDATA = 01000807H PUTLONG VDISP, PUTLDATA LOCATE #VDISP; 10,1,OFF WRITE FORM "C1200"; #VDISP; VGAATTRS ENDIF ! Wait 2 seconds WAIT; 2000 ! Set write mode to write characters without updating attribute, ! set gray Feature A attribute PUTLDATA = 000004E0H PUTLONG VDISP, PUTLDATA LOCATE #VDISP; 1,1,OFF WRITE FORM "C2000"; #VDISP; CHARS ! Wait 2 seconds WAIT; 2000 ! Set character location to (25,1) and display test end line LOCATE #VDISP; 25,1,OFF WRITE FORM "C80"; #VDISP; "End of Video display sample program CLOSE VDISP STOP ERROR1: ! Prevent recursion. ON ERROR GOTO END.PROG ! Determine error type and perform appropriate recovery ! and resume steps. END.PROG: STOP END

"

Chapter 8. Using Input and Output Devices and Pipes

273

274

IBM 4680 BASIC: Language Reference

Chapter 9. IBM 4680 BASIC Compiler Operation


This chapter explains how the compiler takes an IBM 4680 BASIC source program and creates an object module. The command line invokes the compiler, specifies the source file to compile, and passes special directives to the compiler in the form of command line options. A command line cannot exceed 128 characters. Write compiler command lines using the following format:
BASIC source-file-name [options]

Compiler Versions
This document describes the operation of two versions of the compiler: Version 1, Release 2, dated July 8, 1991 or later and Version 3, dated July 8, 1991 or later. Note: Version 1, Release 2 actually displays a banner when executed, showing Version 2.4 or greater and is available only for execution on the 4680 Operating System. Version 3 provides two compiler modules. BASIC.286 executes on the 4680 Operating System. BASIC.EXE executes on either the DOS or OS/2 Operating System. Version 3 provides two additional features -- the ability to compile terminal big memory model and the debug option. The compiler assumes a .BAS filetype unless you specify otherwise.

How the Compiler Operates


The compiler creates an object (.OBJ) file. In addition, the compiler optionally creates a listing (.LST) file or a cross-reference (.XRF) file. The compiler creates temporary work files with file extensions of .CIL, and .CYM. If the compilation is not successful, these temporary files are listed in the disk directory. The compiler erases the files automatically when compilation is complete. The size of a temporary file varies with the size of your source program. The total amount of temporary disk work space required during compilation is approximately one-third to one-half the size of your source file or much more if a listing is being generated. If you do not have enough work space on the disk for the compiler, you can separate large programs into modules and compile each module separately or you can use a command line option to specify another drive for the temporary files. During compilation, the compiler displays a variety of messages on the display screen that shows you the compilation process. The following example shows the compiler output produced by the short demonstration program An IBM 4680 BASIC Demonstration on page 2.
BASIC TEST -------------------------------------------------IBM 4680 BASIC Compiler mm/dd/yy Version x.x
Copyright IBM Corp. 1985, 2003

275

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: 0063H (99 bytes) ---------------------------------------------

Following the heading banner, the compiler indicates the completion of the first two passes with the end of pass messages. The message Large Memory Model Controller Code Generation indicates a successful completion of the compile operation. It also indicates the controller environment was specified within the BASIC source module or that the default controller environment was used.

Setting Paths for Source, Include, and Object Files


Several options are available to allow for flexibility in the location of files used or generated during the compile step. These options are identified as follows:

Source Files
Paths for source files are searched in the following order: 1. You can specify a full path for a source file on the command line. Example:
BASIC C:\DIRECTRY\TEST.BAS

Note: If the file is not found, no additional paths are searched. 2. The current working directory 3. The subdirectory(s) specified by the BASSRC logical name definition (4680 or 4690)) or the path(s) specified by the BASSRC environment variable (DOS or OS/2). Note: You must define (or set) this variable from the Operating System command line prior to the compilation. Example:
define bassrc=c:\direct1 c:\direct2 or set bassrc=c:\direct1;c:\direct2 (4680 or 4690) (DOS or OS/2)

Include Files
Paths for include files are searched in the following order: 1. The drive and path for the include file may be specified in the source file. Note: If the file is not found, the search is aborted. Example (within a source or include file):
%include a:\foo\test.inc

276

IBM 4680 BASIC: Language Reference

2. The drive and/or path may be identified in the command line using the C option. Example 1 (The default directory on the A: drive)
BASIC test [C(a)]

Example 2 (Subdirectory directb on drive A:)


BASIC test [C(a:\directb)]

3. The current working directory 4. The subdirectory(s) specified by the BASINC logical name definition (4680 or 4690) or the path(s) specified by the BASINC environment variable (DOS or OS/2). Note: You must define (or set) this variable from the Operating System command line prior to the compilation. Example:
define BASINC=C:\DIRECT2 C:\DIRECT3 or set BASINC=C:\DIRECT2;C:\DIRECT3 (4680 or 4690) (DOS or OS/2)

Object Files
You can specify OBJ destination subdirectories as follows: 1. You can specify either a disk drive or a subdirectory on the command line using the R option. Example 1 (specifies diskette drive A:)
BASIC test.bas [r(a)]

Example 2 (specifies subdirectory DIRECTC on drive c:)


BASIC test.bas [r(a:\directc)]

2. The subdirectory(s) specified by the BASOBJ logical name definition (4680 or 4690) or the path(s) specified by the BASOBJ environment variable (DOS or OS/2) Note: This variable must be defined (or set) from the Operating System command line prior to the compilation. Example:
define BASOBJ=c:\objdir or set BASOBJ=c:\objdir (4680 or 4690) (DOS or OS/2)

3. The current working directory.

Compiler Directives
Compiler directives are special instructions to the compiler. There are two different types of compiler directives in IBM 4680 BASIC, command-line options and source-code directives.

Command-Line Options
Command-line options are single-letter compiler directives that you specify in the compiler command line instead of in the source program. See Table 26 on page 278 for a summary of the IBM 4680 compiler command-line options. Once an option is set, it remains set through the entire compilation process. However, the %DEBUG source-code directive can change the I, N, and V options during compilation. (See %DEBUG on page 281.)
Chapter 9. IBM 4680 BASIC Compiler Operation

277

To specify a command line option, the reserved option letter must be enclosed in brackets following the file specified in the command line. Letters can be uppercase or lowercase. Certain options require an additional parameter enclosed in parentheses. The following examples show several ways to specify command line options:
BASIC TEST BASIC TEST.BAS [P,S] BASIC FILE.DAT [PW(72)] BASIC CALCS.PRG [N] [O] [P] BASIC DATA.OVL [ p o n ]

If you enter conflicting options, such as O and R, the last one read takes effect. This means an option can override the preceding option in the command line.
Table 26. Compiler Command-line Options Option C D F G I L M N O P R S T U V W X Z Instruction Change the default %INCLUDE file disk or subdirectory. Generate additional BASIC variable diagnostic information in the .OBJ file (Version 3 only). Send the source listing to a disk (.LST) file. Generate source code line numbers in the .LIN file. Line numbers are omitted for %INCLUDE files. Interlist. Generate assembly code with the source listing. Set the page length for printed listings. Set the memory model (terminal and Version 3 only). Generate code for line numbers. Suppress the generation of the object (.OBJ) file. List the source file on the printer. Change the disk or subdirectory to which the object (.OBJ) file is written. Include symbol name information in the object (.OBJ) file. List the symbol table and cross-reference to a disk file (.XRF). Generate an error message for any undeclared variables. Generate source code line numbers in the .LIN files. Set the page width for printed listings. Change the disk used for the temporary files. Add a comment string to the .OBJ file.

C option The C option specifies the default drive or subdirectory or an include file. Enclose the new drive or subdirectory specification in parentheses following the C option. If a drive has been specified in the %INCLUDE directive, the C option has no effect.

278

IBM 4680 BASIC: Language Reference

BASIC TEST [C(D)] or BASIC TEST [C(C:\includes)]

D option (Version 3 only) The D option generates additional BASIC variable diagnostic information in the .OBJ file. See the IBM 4680 Application Debugger Users Guide for more information on the use of this option. F option The F option tells the compiler to file the compiler-created source listing in the current working directory. The source listing file has the same file name as the original source file, but an .LST filetype. The source listing file contains the usual printer control characters, so you can print the file from disk. G option The G option generates source code line numbers in the .OBJ for all code statements that are not statements in an INCLUDE file. The linker options (DBI or LIN) places these line numbers in the LIN file. See the IBM 4680 Application Debugger Users Guide for more information on the use of this option. I option The I option lists compiler-generated assembly code with the original source statements in an .LST file in the current working directory. L option The L option is used to set the number of print lines when the listing is sent to the printer. The default is continuous printing. Enclose the number of print lines value in parentheses after the L option. The value must be an unsigned integer.
BASIC TEST [PL(66)]

This option is recognized only when the P option is used. M option (Version 3 only) M(B) causes the compiler to generate code for the terminal big memory model. M(M) causes the compiler to generate code for the terminal medium memory model. This option is not valid for code compiled for the store controller. If this option is not specified, the default is M(M). N option The N option creates code to save the current line number for each physical line in a source program. The code enables the ERRL function to return the line number when an execution error occurs. The N option increases the size of the object file 7 to 9 bytes per statement. O option The O option tells the compiler not to generate a relocatable object (.OBJ) file.

Chapter 9. IBM 4680 BASIC Compiler Operation

279

P option The P option prints the program listing on the printer. The compiler sends enough line feed characters to start the printing on a new page before printing the first page. R option The R option specifies on which drive or subdirectory to write the object (.OBJ) file. Specify the drive or subdirectory enclosed in parentheses after the R option.
BASIC TEST [R(D)] or BASIC TEST [R(C:\source)]

S option The S option places symbol information for local variables and procedures into the object file. The link editor uses the information to generate a .SYM file. T option The T option lists the symbol table and cross reference information onto a file. This listing file has the same file name as the original source file, but its file type is .XRF. U option The U option generates an error message if a variable name does not appear in an INTEGER, REAL, or STRING declaration. Use the U option to locate misspelled identifiers. V option The V option places source code line numbers for all code statements into the .LIN file. The linker option, DBI, or LIN causes the line numbers to be placed in the .LIN file. See the IBM 4680 Application Debugger Users Guide for more information. W option The W option changes the page width for a listing directed to a printer. Initially, the width is set to 80 columns. Enclose the new width value in parentheses after the W option. The width value must be an unsigned integer. This option is recognized only when the P option is used.
BASIC TEST [PW(70)]

X option The X option specifies a drive for the temporary work files. Normally, the compiler places the temporary files on the same drive as the source file. Enclose the new drive specification in parentheses after the X option. The drive specification must be a single upper-case or lower-case letter.
BASIC TEST [X(D)]

Z option

280

IBM 4680 BASIC: Language Reference

Z(xxxxxx) causes the string, xxxxxx to be placed within the .OBJ file. This option is useful for placing a copyright statement in the .OBJ file.

Source-Code Compiler Directives


Source-code compiler directives do not translate into code. You cannot place spaces between the percent sign and the rest of the reserved word. Only spaces and tab characters can precede a directive. The source-code directive must be the only thing on the line except for comments. The compiler supports the following seven source-code compiler directives: v %INCLUDE v %DEBUG v %ENVIRON v %NOLIST v %LIST v %EJECT v %PAGE. %INCLUDE The %INCLUDE directive instructs the compiler to include the code from a specified source program file with the program being compiled. The source program file is incorporated into the original program immediately following the %INCLUDE. You can specify the file name, file type, and disk drive after the %INCLUDE directive as shown in the following examples: Note: The compiler assumes the default drive and a .BAS filetype if you do not specify otherwise.
%INCLUDE CONDEF %INCLUDE CONDEF.INC %INCLUDE D:CONDEF.INC

You can nest included files six deep. %DEBUG The %DEBUG directive enables you to turn the command line options I, N, and V on or off from within the source program code. To turn a command line option on, place the option letter after the %DEBUG directive. To turn an option off, place the option letter preceded by a minus sign after the %DEBUG directive. The following examples show variations of the %DEBUG directive.
%DEBUG I %DEBUG -I %DEBUG INV %DEBUG -I-N-V

%ENVIRON Some statement and function reserved words are designed for use with only the store controller or terminal (see Statements and Functions on page 36).

Chapter 9. IBM 4680 BASIC Compiler Operation

281

The %ENVIRON directive enables you to specify compilation for either the store controller or terminal. You can specify the letter C for store controller or T for terminal after the %ENVIRON reserved words. If you do not specify store controller or terminal, the default is store controller. The compiler issues error messages for any statement and function reserved words compiled for the wrong machine type. The terminal program is compiled as either medium or big model and the controller program is compiled as large model. See Memory Models on page 285 for additional information on models. Note: The %ENVIRON directive must be preceded by blank lines or comments or it is ignored. The following example specifies compilation for terminal:
%ENVIRON T

%NOLIST and %LIST These directives work when P, F, or I are turned on. The %NOLIST directive tells the compiler not to list anything that follows the %NOLIST in the source program. The %LIST directive tells the compiler to resume the listing. You can use %NOLIST and %LIST directives any number of times in a program. %EJECT The %EJECT directive works only when you direct the source listing to a printer. %EJECT instructs the compiler to continue the program listing at the top of the next page. The compiler ignores %EJECT if the %NOLIST directive is in effect or if you direct the program listing to the a disk file. %PAGE The %PAGE directive sets the page length for a program listing that is directed to a printer. The page length you specify must be an unsigned integer placed after the %PAGE directive. If no page length is specified, the default is continuous printing. The following example specifies a page length of 40 lines:
%PAGE 40

Compiler Errors
The compiler reports three types of errors: compilation errors, file system and memory space errors, and internal compiler failures.

Compilation Errors
Compilation errors are user lexical and syntax errors. If one of these occurs, compilation continues to completion or until 95 errors are detected. However, an object file is not generated. To help you find and correct errors in your program, diagnostic messages are displayed on screen when compilation errors are detected. If the [F] option is selected, these errors are also flagged in the listing (.LST) file at the location of the error. If the [P] option is selected, this listing file is sent to the printer instead of to disk.

282

IBM 4680 BASIC: Language Reference

The diagnostic messages sent to the screen identify the source file and the line and column within the file where the error was detected. They also give the error number and a description of the error as documented in Appendix A, Compiler Error Messages, on page 307. (For certain types of errors the filename, line, and column have no useful meaning and are not displayed.) Compilation error messages sent to the screen have the following format:
filename line# col#: error nnn: message

Screen output may be redirected to a file or to the printer for ease in debugging multiple errors:
BASIC TEST > test.err

Here is an example of a program that attempts to assign a string constant to an integer variable. The name of the source file is TEST.BAS.
%ENVIRON C INTEGER*2 I% I% = "October 15, 1991" END

Enter the following command to compile this program:


BASIC TEST.BAS [F]

The compiler sends the following to the screen:


BASIC TEST [F] -------------------------------------------------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 TEST.BAS 3 24: error 27: The mixture of data types in this expression is not permitted. end of pass 2 End of Compilation 1 Error(s) Detected

The diagnostic message tells you that error 27 was detected on line 3, column 24 in source file TEST.BAS. The message text that corresponds to error 27 is The mixture of data types in this expression is not permitted. Invoking the compiler with the F option, BASIC TEST.BAS [F], causes it to generate the following listing in file TEST.LST:
1: %ENVIRON C 2: INTEGER*2 I% 3: I% = "October 15, 1991" *** error ^27 4: END End of Compilation

In this listing the compiler prints a caret and an error number to indicate the occurrence of a compilation error. Error numbers and the corresponding descriptions are documented in Appendix A, Compiler Error Messages, on page 307. A similar listing is sent to the printer if you use the P option instead of the F option.
Chapter 9. IBM 4680 BASIC Compiler Operation

283

File System and Memory Space Errors


File system and memory space errors, such as invalid command lines, file I/O errors, and out-of-memory conditions, are fatal errors that cause the compiler to abort. Diagnostic messages for this type of error have the following format:
filename line# col#: FATAL ERROR nnn: message

For certain types of errors the filename, line and column have no useful meaning and will not be displayed. File I/O errors occur most often when the compiler tries to open a non-existent source file, or when it tries to write to a file and the disk is full. Memory space errors occur when there is too little memory to compile your program.

Internal Compiler Failures


Internal compiler failures are unexpected errors caused by a design flaw within the compiler itself. If an internal compiler failure occurs during the compilation of your program, see Appendix A, Compiler Error Messages, on page 307 for more information on how to report this problem to your service representative.

284

IBM 4680 BASIC: Language Reference

Chapter 10. Memory Allocation


The 80286 microprocessor can address up to 16 million bytes of memory in segments of up to 64K bytes each. Every segment that is used by a program falls into one of the following three categories: v Program code v Data v Stack For each of these categories, the 80286 has a segment base register that points to the base address of the corresponding area in memory: v The code segment register (CS) points to the CS register base of the current program code segment. v The data segment register (DS) points to the base of the current data segment. v The stack segment register (SS) points to the base of the stack segment. LINK86 creates command files with a filetype of .286. An IBM 4680 BASIC command file contains a header record and the program memory image. IBM 4680 BASIC defines a separate DGROUP (data group) and CGROUP (code group) in the memory image portion of each command file. LINK86 places all segments belonging to the code group in the code section of the .286 file, and all segments belonging to the data group in the data section of the .286 file.

Memory Models
IBM 4680 BASIC supports three different memory models: v Medium v Big (Version 3 only) v Large In the large memory model, a program can have multiple code segments, multiple data segments, and one stack segment. In the big memory model, a program can have multiple code segments and multiple heap segments, but only one root data segment, one common data segment, and one stack segment. A program in the medium memory model may also have multiple code segments, but is limited to a single segment for data and stack combined. Thus, a medium memory model program is limited to 64K bytes (the maximum size of a single segment) of combined data and stack. IBM 4680 BASIC programs for the store controller are always compiled in large memory model. Programs for the terminal can be compiled as either big memory model or medium memory model.

Controller Large Memory Model


The large memory model can support programs that require a data group larger than 64K bytes. The code and data groups in the large memory model consist of individual segments, each limited to 64K bytes, as shown in Figure 10 on page 286. Because each group may contain multiple segments, the total amount of code and
Copyright IBM Corp. 1985, 2003

285

data is limited only by the amount of memory available, up to one megabyte per group. Since only one stack segment is allowed, the stack may be no larger than 64K bytes.
High Memory DATA SEGMENT DATA SEGMENT DATA SEGMENT CODE SEGMENT CODE SEGMENT CODE SEGMENT OPERATING SYSTEM DGROUP (Maximum Available Memory) CGROUP (Maximum Available Memory Up to 1 Megabyte)

Low Memory

Figure 10. Large Memory Model

Figure 11 shows the memory allocation for a root program and one overlay in a large memory model. The code areas (ROOT CODE, OVERLAY CODE) contain the actual program instructions.
High Memory HEAP STACK OVERLAY DATA (optional) ROOT DATA COMMON DATA SRTL DATA OVERLAY CODE (optional) ROOT CODE

64K DGROUP (Maximum Available Memory)

CGROUP (Maximum Available Memory Up to 1 Megabyte)

Low Memory

Figure 11. Large Memory Model Runtime Organization

Data Areas
The data areas (ROOT DATA, COMMON DATA, OVERLAY DATA) contain static data, such as integers and real numbers. Static data is data that does not vary in size. Root data is used only by the root program. Common data is shared between the root and the overlay. Overlay data is used only by the overlay.

286

IBM 4680 BASIC: Language Reference

SRTL data is used by a shared runtime library. The store controller SRTL data is about 3.0K bytes.

The Heap
The heap is the dynamic data storage area. It is for data storage that is allocated at runtime, especially data that can vary in size, such as strings and arrays. The large model heap starts with no space and allocates additional storage in 8K blocks as needed.

The Stack
The stack is used to store local variables for recursive procedures, parameters being passed from one procedure to another, and return addresses for procedure calls. The stack is also used for temporary variables, which if they are string variables, can be quite large. The amount of stack being used at any given time depends on the degree of procedure nesting and the number of parameters being passed. The default size for the large model stack segment depends on the version of LINK86 you are using; but it may be changed using the LINK86 stack options. Small stack sizes run the risk of overflowing if there are several nested procedure calls. A full 64K segment for your stack is not recommended. Table 27 shows the approximation of your applications stack requirements.
Table 27. Controller Large Memory Model Stack Usage Minimum stack size required Overhead per nested subprogram or function call or invocation Overhead per parameter passed to nested subprogram Overhead per parameter passed to nested function: 2048 bytes 4 bytes 4 bytes Real data type 10 bytes 4-byte integer data type 4 bytes 1- or 2-byte integer data type 2 bytes 4 bytes 6 bytes + string length

String data type Overhead for largest temporary string *

A temporary string is the value of a string-type function before being assigned to the function name; the result of a concatenation of two string variables before being assigned to a variable; the value of a string expression that is passed to a function. For example:
PRINT LEFT$ (ABC$, 12)

The example above creates a temporary string that is 12 bytes long and is passed to the PRINT function.

Terminal Medium Memory Model


The medium memory model is used only for the terminal. To specify medium memory terminal compilation, use the %ENVIRON T compiler option and use the M(M) option on the compile step. See Chapter 9, IBM 4680 BASIC Compiler Operation for more information on the %ENVIRON option. The medium memory model defines a separate data group and code group as shown in Figure 12.

Chapter 10. Memory Allocation

287

High Memory

Low Memory

DATA SEGMENT CODE SEGMENT CODE SEGMENT CODE SEGMENT OPERATING SYSTEM

DGROUP (64K Maximum) CGROUP (Maximum Available Memory)

Figure 12. Terminal Medium Memory Model

The data group cannot exceed 64K bytes, the size of a single segment. The code group may contain multiple segments, and hence is limited only to the total memory available that is not occupied by the data group and the operating system. The default maximum size of the medium memory model DGROUP is 65520 bytes. It can be changed at link-time using the data option of LINK86. For example:
link86 prog [data[max[0ffe]]]

creates a data segment that is 65,504 bytes. A full 64K segment is not recommended. Figure 13 shows memory allocation for the medium memory model for the terminal.
High Memory HEAP ROOT DATA RTSL DATA STACK ROOT CODE DGROUP (64K Maximum) CGROUP (Maximum Available Memory)

Low Memory

Figure 13. Terminal Medium Model Runtime Organization

Data Areas
The root data area contains all static data, such as integers and real numbers. Static data is data that does not vary in size, and is allocated when the program is compiled. RTSL data is used by the runtime library. The terminal RTSL data is about 3.5K bytes. The CODE AREA contains the program instructions.

288

IBM 4680 BASIC: Language Reference

The Heap
The heap is the dynamic data storage area used to store data that can vary in size, such as strings and arrays.

The Stack
The stack is used to store local variables for recursive procedures and return addresses for procedures. The maximum stack size is fixed at 2048 bytes. The depth of stack usage by an application depends on the degree of procedure nesting and can be approximated using Table 28.
Table 28. Medium Model Stack Usage Minimum stack size required Overhead per nested subprogram or function call or invocation Overhead per parameter passed to nested subprogram Overhead per parameter passed to nested function: 1024 bytes 4 bytes 2 bytes Real data type 10 bytes 4-byte integer data type 4 bytes 1- or 2-byte integer data type 2 bytes 2 bytes 4 bytes + string length

String data type Overhead for largest temporary string *

A temporary string is the value of a string-type function before being assigned to the function name; the result of a concatenation of two string variables before being assigned to a variable; the value of a string expression that is passed to a function. For example:
PRINT LEFT$ (ABC$, 12)

creates a temporary string that is 12 bytes long and is passed to the PRINT function. The size of the medium model stack for the terminal is 2K bytes. The Linker stack option cannot change this size.

Terminal Big Memory Model (Version 3 only)


To specify a terminal big memory model compilation, use the %ENVIRON T compiler option and the M(B) option on the command line. The terminal big memory model can support programs that require a data group larger than 64K bytes. The code and data groups in the big memory model consist of individual segments, each limited to 64K bytes, as shown in Figure 14 on page 290. Because each group may contain multiple segments, the total amount of code and data is limited only by the amount of memory available, up to one megabyte per group. Since only one stack segment is allowed, the stack may be no larger than 64K bytes.

Chapter 10. Memory Allocation

289

High Memory

Low Memory

DATA SEGMENT DATA SEGMENT DATA SEGMENT CODE SEGMENT CODE SEGMENT CODE SEGMENT OPERATING SYSTEM

DGROUP (Maximum Available Memory) CGROUP (Maximum Available Memory Up to 1 Megabyte)

Figure 14. Terminal Big Memory Model

Figure 15 shows the memory allocation in a big memory model.


High Memory HEAP STACK RTSL DATA COMMON DATA ROOT DATA ROOT CODE (Maximum Available Memory) 64K DGROUP CGROUP (Maximum Available Memory up to 1 Megabyte)

Low Memory

Figure 15. Terminal Big Memory Model Runtime Organization

Data Areas
The data areas (ROOT DATA, RTSL DATA, and COMMON DATA) contain all static data, such as integers and real numbers. Static data is data that does not vary in size. There is only one static data segment. Multiple heap segments can be allocated. The code area contains the actual program instructions.

The Heap
The heap is the dynamic data storage area. It is for data storage that is allocated at runtime, especially data that can vary in size, such as strings and arrays. The big model heap starts with no space and allocates additional storage in 8K blocks as needed.

The Stack
The stack is used to store local variables for recursive procedures, parameters being passed from one procedure to another, and return addresses for procedure calls. The amount of stack being used at any given time depends on the degree of procedure nesting and the number of parameters being passed. The stack is also

290

IBM 4680 BASIC: Language Reference

used for temporary variables, which if they are string variables, can be quite large. The size of the big model stack segment may be changed using the LINK86 stack option. A full 64K segment for your stack is not recommended. Small stack sizes run the risk of overflowing if there are several nested procedure calls. Table 29 shows the approximation of your applications stack requirements.
Table 29. Terminal Big Memory Model Stack Usage Minimum stack size required Overhead per nested subprogram or function call or invocation Overhead per parameter passed to nested subprogram Overhead per parameter passed to nested function: 2048 bytes 4 bytes 4 bytes Real data type 10 bytes 4-byte integer data type 4 bytes 1- or 2-byte integer data type 2 bytes 4 bytes 6 bytes + string length

String data type Overhead for largest temporary string *

A temporary string is the value of a string-type function before being assigned to the function name; the result of a concatenation of two string variables before being assigned to a variable; the value of a string expression that is passed to a function. For example:
PRINT LEFT$ (ABC$, 12)

The example above creates a temporary string that is 12 bytes long and is passed to the PRINT function.

Chapter 10. Memory Allocation

291

292

IBM 4680 BASIC: Language Reference

Chapter 11. Data Representation in Memory


Knowledge of how data is represented in memory is useful when you want to interface IBM 4680 BASIC programs with assembly language routines, and routines in the runtime subroutine library.

Integer Storage In Memory


Integers can occupy 1, 2, or 4 bytes of memory space. The amount of storage IBM 4680 BASIC uses for a given integer depends on the precision you declare in the program. IBM 4680 BASIC represents all negative integer data in twos complement binary form. Table 30 shows the range of values each size integer can represent.
Table 30. Value Ranges for Integers Stored in Memory Precision INTEGER*1 INTEGER*2 INTEGER*4 Storage Required 1 byte 2 bytes 4 bytes Range of Values -128 to +127 -32,768 to +32,767 -2,147,483,648 to +2,147,483,647

Figure 16, Figure 17, and Figure 18 show the formats for the storage of 1, 2, and 4 byte integers in memory.
X X X X X X X X 7 6 5 4 3 2 1 0 sign bit

Figure 16. 1-byte Integer Memory Format X% = 4010 10 LOW ORDER BYTE STORED FIRST 0 0 0 1 0 0 0 0 7 6 5 4 3 2 1 0 40 HIGH ORDER BYTE 0 1 0 0 0 0 0 0 15 14 13 12 11 10 9 8 sign bit

-----Low Memory--------------------High Memory---

Figure 17. 2-byte Integer Memory Format and Example

Copyright IBM Corp. 1985, 2003

293

X% = 80204010H 10 40 LOW WORD LOW BYTE HIGH BYTE 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 0 7 0 15 8 20 80 HIGH WORD LOW BYTE HIGH BYTE 0 0 1 0 0 0 0 0 1 0 0 0 0 0 0 0 24 16 32 25 sign bit

-----Low Memory----------------------------------------------------------------------High Memory---------

Figure 18. 4-byte Integer Memory Format and Example

IBM 4680 BASIC allocates storage space in the data memory area for integers. Data area refers to the static data area, not the heap. See Memory Models on page 285 for more information on data areas.

Real Number Storage in Memory


Real numbers are stored in binary coded decimal (BCD) floating-point form. Each real number occupies ten bytes of memory, as shown in Figure 19. The high-order bit in the first byte (byte 0) contains the sign of the number. The remaining seven bits in byte 0 contain a decimal exponent. The exponent is a binary number representing a power of ten. The number is biased by 40H. Therefore, an exponent value of 42H represents an actual exponent of 2. Bytes 1 through 9 contain the mantissa. Two BCD digits occupy each of the nine bytes in the mantissa. The most significant digit of the number is stored in byte 9, (farthest from the exponent). The floating decimal point is always situated to the left of the most significant digit.
18 BCD DIGIT Mantissa XX XX XX XX XX XX XX XX XX 1 2 3 4 5 6 7 8 9

XX BYTES 0 EXPONENT X X X X X X X X BITS 7 6 5 4 3 2 1 0 numbers sign bit

------Low Memory-----------------High Memory--------

Figure 19. Real Number Storage in Memory

294

IBM 4680 BASIC: Language Reference

String Storage in Memory


Strings are stored in memory as a sequence of ASCII characters. Figure 20 shows the layout of the string for the terminal big memory model or the controller. Figure 21 on page 296 shows the layout of the string for the terminal medium memory model. The layout is the same for a string variable or array element string. IBM 4680 BASIC allocates memory space in the heap for strings. The heap is the dynamic storage area for memory. A pointer in the program static data area is the address of the actual string in the heap.
String Length 2 Bytes XX XX Maximum Length String Pointer Points Here

2 Bytes 4 Bytes XX XX XXXX XXXY Other Information

Data in String XX XX XX XX XX XX XX XX XX XX 0 1 2 3 4 5 6.....n Current Length of Data

Multiple of 16 Bytes in controller Multiple of 12 Bytes in terminal

Figure 20. String Storage in Memory in Controller or Big Memory Model Terminal

When a string variable is loaded with a smaller string, the same amount of space is retained. Only the current length field of the string is updated; the maximum length field is unchanged. When a string variable is set to a null string, the memory space used by the string is freed. As strings are freed, adjacent blocks are combined as free space. When a string or an element of a string array is initialized, the amount of memory allocated for the string is enough memory for the string header and string plus enough memory to make the string a multiple of 16 bytes in the controller, 12 bytes in the Big Memory Model Terminal, and 8 bytes in the Medium Memory Model Terminal. When the string is concatenated with additional data, the additional data is added to the end of the original string if enough space is available. Otherwise, a new block of memory is obtained that is large enough for both strings and the original string space is released.

Chapter 11. Data Representation in Memory

295

X% = 80204010H

LOW WORD LOW BYTE 0 0 0 1 0 0 0 0 7 0 HIGH BYTE 0 1 0 0 0 0 0 0 15 8 LOW BYTE

HIGH WORD HIGH BYTE 1 0 0 0 0 0 0 0 32 25 sign bit

0 0 1 0 0 0 0 0 24 16

Low Memory

High Memory

Figure 21. String Storage in Memory in Medium Memory Model Terminal

Array Storage
Arrays, both numeric and string, are allocated memory space in the heap, as required. Four bytes are reserved for each element of a 4-byte integer array, two bytes for each element of an 2-byte integer array, and one byte for each element of a 1-byte integer array. Ten bytes are reserved for each element of an array containing real numbers. Four bytes are initially reserved for each element of a string array in a large or big memory model program. In a medium memory model program, each element of a string array reserves an initial two bytes. However, this is the minimum memory space reserved for string array elements with no assigned string data (null strings). Each array in IBM 4680 BASIC requires some memory overhead to store an array descriptor. The descriptor, stored in the heap, contains information about the array, such as the data type and the upper and lower array bounds. The descriptor of an array in a large or big memory model program requires an initial eight bytes of overhead plus six bytes for each dimension in the array. In medium memory model programs, the array descriptor requires an initial six bytes of memory overhead plus six bytes for each dimension. Memory space is allocated in the heap when the DIM statement is executed. Array heap space can only be freed when an array is redimensioned to a different size. See Memory Models on page 285 for information about the heap. When an element of any array is loaded with a smaller string ( for example, a 20-byte string is loaded into an element of an array that contains a string of 420 bytes) the same 420 bytes of memory is used to hold the 20-byte string. When an element of an array is set to a null string, the memory space used by the element is freed.

296

IBM 4680 BASIC: Language Reference

When the element is concatenated with additional data, the additional data is added to the end of the original string if enough space is available. Otherwise, a new block of memory is obtained that is large enough for both strings and the original string space is released. String arrays use much more memory than numeric arrays, as shown in the following example for the controller:
Fixed Header Pointer or Data B% Data 0 0 0 1 0 2

DIM DIM A $ A $ A $ B % B % B %

A B (0) (1) (2) (0) (1) (2)

$ % = = = = = =

(2) (2) "0" "1" "2" 0 1 2

#0 16 bytes String Data #1 16 bytes String Data #2 16 bytes String Data A $ Pointer 0 1 2 In the controller, 54 more bytes of memory are required for A $ than for B %; therefore, 1000 string elements would require 18,000 more bytes of memory.

Figure 22. Memory Usage of String Arrays

Chapter 11. Data Representation in Memory

297

298

IBM 4680 BASIC: Language Reference

Chapter 12. Interfacing IBM 4680 BASIC with Assembly Language


This chapter defines the conventions and guidelines you must observe to interface IBM 4680 BASIC modules with assembly language routines that are written using Intel 80286 or 8086/8088 microprocessor assembly language. This chapter uses RASM86 to demonstrate the interfacing procedures. RASM86 is a relocatable assembler for 8086/8088 assembly language developed by Digital Research Inc., (DRI). RASM86 creates relocatable object files in the Intel object file format. These files can be linked using LINK86.

Calling an Assembly Routine from an IBM 4680 BASIC Module


Three steps are required to call an assembly language routine from an IBM 4680 BASIC module. 1. Declare the name of the assembly routine in the IBM 4680 BASIC source code using an EXTERNAL function or subprogram definition. Note: In IBM 4680 BASIC, external names are significant up to 31 characters. IBM 4680 BASIC converts all characters to uppercase. RASM86 also converts all characters to uppercase, unless you use the $NC option. Therefore, if you use the $NC option with RASM, you should declare the names of functions and subprograms in the RASM assembly language program in uppercase. For example, the following IBM 4680 BASIC declarations specify ASSEMBLY1 and ASSEMBLY2 as external procedures:
FUNCTION ASSEMBLY1 EXTERNAL END FUNCTION SUB ASSEMBLY2 END SUB EXTERNAL

2. In the RASM86 source code, declare the assembly routine names public using the RASM86 PUBLIC directive.
PUBLIC PUBLIC ASSEMBLY1 ASSEMBLY2

3. You can now reference the assembly routine from the IBM 4680 BASIC module. Use a CALL statement to reference a subprogram or function. You can also reference a function in an expression.

Passing Arguments
The following conventions apply when passing arguments in IBM 4680 BASIC: v IBM 4680 BASIC functions and subprograms pass arguments on the stack rather than in registers. v The compiler places each argument on the stack, reading the argument list from right to left. v IBM 4680 BASIC subprograms pass arguments by reference; functions pass arguments by value, except for string arguments which are always passed by reference. Each argument is pushed onto the stack. As an example, see the following hypothetical assembly language function:
Copyright IBM Corp. 1985, 2003

299

X = TESTFUNC(var.a, var.b, var.c, var.d, var.e, "greetings")

TESTFUNC is a real function that requires six arguments, with the variables var.a through var.e having the following type definitions.
INTEGER*2 var.a INTEGER*4 var.b STRING var.c REAL var.d INTEGER*1 var.e

The sixth argument is the literal string greetings. Like the string represented by var.c, a pointer to a copy of greetings is passed, rather than the string itself. IBM 4680 BASIC string pointers point to the length bytes that precede the actual string text. The BASIC program should contain the following external declaration for TESTFUNC:
FUNCTION testfunc(a,b,c,d,e,f) INTEGER*2 a INTEGER*4 b STRING c REAL d INTEGER*1 e STRING f END FUNCTION EXTERNAL

Figure 23 and Figure 24 show the stack when TESTFUNC is entered. Figure 23 shows the stack for the medium memory model, and Figure 24 shows the stack for the large memory model.
Size (in bytes) 4 2 4 2 10 2 2 2 Offset from SP Return address 0 Value of var. a +4 Value of var. b +6 Address of var. c +10 Value of var. d +12 Value of var. e +22 Address of "greetings" +24 Address of real return value +26

Figure 23. Function Stack for Medium Memory Model

300

IBM 4680 BASIC: Language Reference

Size (in bytes) 4 2 4 4 10 2 4 4

Offset from SP Return address 0 Value of var. a +4 Value of var. b +6 Address of var. c +10 Value of var. d +14 Value of var. e +24 Address of "greetings" +26 Address of real return value +30

Figure 24. Function Stack for Large or Big Memory Model

The compiler statically allocates space for the string constant greetings, and passes a descriptor to the static location. The descriptor contains a pointer to the string and its size. As another example, consider the difference in how the arguments are passed if TESTFUNC is declared to be a subprogram instead of a function. Subprogram arguments are passed by reference, instead of by value. Figure 25 and Figure 26 show the stack on entry to subprogram TESTFUNC, for medium and large memory models.
Size (in bytes) 4 2 2 2 2 2 2 2 Offset from SP Return address 0 Address of var. a +4 Address of var. b +6 Pointer to Address of var. c +8 Address of var. d +10 Address of var. e +12 Pointer to Address of "greetings" +14 Address of real return value +16

Figure 25. Medium Memory Model Subprogram Stack

Chapter 12. Interfacing IBM 4680 BASIC with Assembly Language

301

Size (in bytes) 4 4 4 4 4 4 4 4

Offset from SP Return address 0 Address of var. a +4 Address of var. b +8 Pointer to Address of var. c +12 Address of var. d +16 Address of var. e +20 Pointer to Address of "greetings" +24 Address of real return value +28

Figure 26. Large or Big Memory Model Subprogram Stack

The calling IBM 4680 BASIC routine removes the arguments from the stack after returning from the called routine. The compiler creates an ADD SP,nnn instruction in the IBM 4680 BASIC program, immediately following the call to the assembly routine. The value nnn is the number of bytes pushed onto the stack. The instruction modifies the stack pointer, removing the arguments. Note: For subprograms definitions, a pointer to the pointer to a string is passed, rather than a pointer to a string.

Return Values
Integer values that a function returns are passed back to the calling program in certain registers. Table 31 shows which registers contain the return values for the IBM BASIC 4680 INTEGER data type.
Table 31. Integer Return Value Registers Data Type INTEGER*1 or LOGICAL INTEGER*2 INTEGER*4 Registers AL AX High word in BX, Low word in AX

Real return values are handled somewhat differently than integer values. The calling routine of a real function must allocate space for the 10-byte return value (usually in its own stack) and pass a pointer to this 10-byte space to the called function. This pointer is pushed on the stack before any of the arguments. String return values use another technique. The calling module does not allocate space. The called function pushes the entire string onto the stack, followed by a string pointer. This means the caller has no way of knowing how much space to allocate in advance. Instead, the called function lifts off the return address, pushes the string itself (always an even number of bytes plus the length bytes), and then pushes a pointer to the string. String pointers must always point to the length word that precedes the actual string. See Figure 27.

302

IBM 4680 BASIC: Language Reference

BP Return Address Arguments Stack on entry to function. Return Address String Pointer String Arguments Stack prior to exit from called function. String Pointer String Arguments Stack on return to calling module.

Figure 27. Returning a String From a Function

Register Usage
When you write an assembly language module that is to be called from an IBM 4680 BASIC module, you must preserve the values in the BP, DS, and SS registers. In the medium memory model, you must also preserve the value in ES. All other registers are available for use in the called routine.

Program Example
The following example shows how IBM 4680 BASIC and Assembly Language interface. The example consists of a BASIC routine, or program, and an assembler language subroutine. The program and subroutine must be linked by LINK86. The BASIC routine will call the assembler language subroutine. It then passes a string to the subroutine, along with either 2 or 4 bytes of data and an offset. This data is inserted into the string (at the offset passed to the subroutine) and overlays the existing bytes at the designated place.

BASIC Routine
INTEGER*4 hx%,sx%,s%,THE.SUM% INTEGER*2 INTVAR%,OFFSET% INTEGER*4 LONGINTVAR%
Chapter 12. Interfacing IBM 4680 BASIC with Assembly Language

303

STRING BSTRING$,A$,errfx$ SUB INSERT2(BSTRING$, OFFSET%, INTVAR%) EXTERNAL INTEGER*2 INTVAR%,OFFSET% STRING BSTRING$ END SUB SUB INSERT4(BSTRING$, OFFSET%, LONGINTVAR%) EXTERNAL INTEGER*2 OFFSET% INTEGER*4 LONGINTVAR% STRING BSTRING$ END SUB ON ERROR GOTO ERRORA CLEARS !CLEAR SCREEN BSTRING$ = "1234567890" !LOAD STRING OFFSET% = 3 !LOAD OFFSET INTO STRING INTVAR% = 3334H !LOAD VARIABLE TO INSERT LONGINTVAR% = 33343536H !LOAD LONG VARIABLE TO INSERT PRINT "INTVAR% IS ", INTVAR% PRINT "LONGINTVAR% IS ", LONGINTVAR% PRINT "ORIGINAL STRING ", BSTRING$ !PRINT ORIGINAL STRING CALL INSERT2(BSTRING$,OFFSET%,INTVAR%) PRINT "MODIFIED STRING ", BSTRING$ !PRINT STRING BSTRING$ = "1234567890" !RE-INITIALIZE STRING !CALL INSERT4 TO OVERLAY 4 BYTES CALL INSERT4(BSTRING$,OFFSET%,LONGINTVAR%) PRINT "MODIFIED STRING ", BSTRING$ !PRINT STRING STOP !STOP ROUTINE !!ERROR ROUTINE!! ERRORA: HX% = ERRN ERRFX$ = " 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 A$=CHR$(THE.SUM%) ERRFX$ = ERRFX$ + A$ NEXT S% PRINT "ERR=",ERR," ERRL=",ERRL PRINT "ERRF=",ERRF%," ERRN=",ERRFX$ WAIT ;15000 RESUME END

Assembler Subroutine
To link the BASIC program and the assembler subroutine, use the following statement:
LINK86 BSAMPLE,ASAMPLE ; public INSERT2, INSERT4 cseg ; ; ; ; ; Subroutine, callable from IBM 4680 BASIC (large model,CONTROLLER ONLY) ; to insert a 2- or 4-byte integer into a string. ; ; usage: INSERT2( string, offset, intvar ) ; or: INSERT4( string, offset, longintvar ) ; ; where: string is the string variable, which must be long enough

304

IBM 4680 BASIC: Language Reference

; to insert (overlay) a 2 byte or 4 byte integer ; offset is the subscript in the string of the first byte ; (minimum value is 1, for the beginning of the string) ; intvar is the 2-byte integer to be inserted ; longintvar is like intvar, but 4 bytes long ; ; Note that "inserting" does not change the length of ; the string -- the indicated bytes are simply overwritten. ; ; Note that for offset, intvar, and longintvar, the address of ; the value is pushed onto the stack (rightmost parameter first), and ; for string, the address of the address of the string is pushed. ; ; ;The stack looks like this upon entry to any of these routines: ; ; -- high mem -; | | ; | pointer to ---|-------------->intvar or longintvar ; |----------------| ; | pointer to ---|-------------->offset ; |----------------| +--------------+ ; | pointer to ---|----------->|pointer to ---|---->string ; |----------------| +--------------+ ; sp | return address | ; |----------------| ; ; string consists of a 16-bit length followed by the first ; character of the string, then the second character, etc.. A bounds ; check is performed on offset for INSERT2 and INSERT4. If offset ; is out-of-range, nothing is done. ; ; Note that all pointers and the return address are 4 bytes each ; ; INSERT2: push bp mov bp,sp les si,10[bp] mov bx,es:[si] les si,14[bp] mov ax,es:[si] les si,6[bp] les si,es:[si] mov es:1[bx+si],ax pop bp retf ; INSERT4: push bp mov bp,sp les si,10[bp] mov bx,es:[si] les si,14[bp] mov ax,es:[si] mov dx,es:2[si] les si,6[bp] les si,es:[si] mov es:1[bx+si],ax mov es:3[bx+si],dx pop bp retf ; end ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; sub routine start save bp get stack pointer the data pointer es:si point to offset bx is the desired offset es:si point to intvar ax is intvar es:si point to pointer to string es:si point to string store the two byte integer retrieve the base pointer return to the calling routine subroutine start save bp make the stack pointer the data pointer es:si point to offset bx is the desired offset es:si point to longintvar ax is low half of longintvar dx is high half of longintvar es:si point to pointer to string es:si point to string store low half store high half retrieve bp return to the calling routine

Chapter 12. Interfacing IBM 4680 BASIC with Assembly Language

305

Results of Example
The results of running the executable (.286) module are as follows:
INTVAR% IS 13108 LONGINTVAR% IS 859059510 ORIGINAL STRING IS 1234567890 MODIFIED STRING IS 1243567890 MODIFIED STRING IS 1265437890 (Decimal value of 2-byte integer) (Decimal value of 4-byte integer) (2-byte integer inserted) (4-byte integer inserted)

Notice that the 34 in the original string has been overlayed by 43 in the first modified string. The second modified string shows that 3456 has been overlayed by 6543.

306

IBM 4680 BASIC: Language Reference

Appendix A. Compiler Error Messages


The compiler reports the following types of compiler errors: v File-system, memory space, and compilation errors v Internal failures

File System, Memory Space, and Compilation Errors


File system and memory space errors include mistakes such as read errors, missing include files, and out of memory conditions. Compilation errors include errors in the syntax of the IBM 4680 BASIC language, such as invalid characters, improper data type specifications, and missing delimiters. The compiler prints a caret and an error number in the listing of the source program to indicate the occurrence of a compilation error. The numbers correspond to the error descriptions. Both types of errors are reported to the screen using one of the following formats:
Normal error message: filename line column: error nnn: message

Note: The compiler continues compilation.


Fatal error message: filename line column: FATAL ERROR nnn: message

Notes: 1. The compiler aborts compilation. 2. For certain types of errors, the filename, line, and column information has no useful meaning and is not displayed. Generally, the errors detected by the compiler can be found by editing the filename shown by the error message. The location of the error within that file is at the line number and column number shown on the error message. If there is a significant number of errors listed, the user may want to redirect the screen output to a file for reference.

Copyright IBM Corp. 1985, 2003

307

Error Code 1

Description Explanation: An invalid character is in the source program. The compiler ignores the character. Remove or correct the invalid character in the source program.

Compiler Action: User Response: 2 Explanation:

Invalid string constant. The string is too long or contains a carriage return.

Compiler Action: The compiler truncates the string at the carriage return and assumes the remainder is a new statement. User Response: 3 Explanation: Correct the string constant in the source program.

Invalid numeric constant. The compiler assumes an integer constant of zero. Correct the numeric constant in the source program.

Compiler Action: User Response: 4 Explanation:

Undefined compiler directive. The source line is ignored.

Compiler Action:

User Response: Remove or correct the invalid compiler directive and specify a valid directive in the source program. 5 Explanation: The %INCLUDE directive is missing a filename. The source line is ignored.

Compiler Action:

User Response: Specify a proper filename for the %INCLUDE directive or remove the %INCLUDE from the source program. 6 Explanation: Statements are found in the main program after an END. The statements are ignored.

Compiler Action:

User Response: Remove the extraneous statements from the source program or move the END statement to the proper place. 7 Explanation: Constant division by zero (0). The compiler ignores the expression. Correct the expression in the source program to avoid any division by A variable is used without being defined, and the U toggle is used during

Compiler Action: User Response: zero. 8 Explanation: compilation.

Compiler Action: The compiler assumes the default data type for the variable ($ for string, % for integer). User Response: Remove the undefined variable from the source program or define the variable before using it. 9 Explanation: An unexpected parameter or an unexpected mix or order of parameters was encountered in a DEF, FUNCTION, or SUB statement. Compiler Action: User Response: The statement is ignored. Correct the parameter list in the source program.

308

IBM 4680 BASIC: Language Reference

Error Code 10

Description Explanation: A right parenthesis is missing from the parameter list. The compiler assumes a right parenthesis exists. Enter the right parenthesis in the source program. A comma is missing in the parameter list. The compiler assumes a comma exists. Enter the comma in the source program. An identifier is missing in the parameter list. The statement is ignored. Correct the parameter list in the source program. The same identifier is used twice in a parameter list. The statement is ignored. Correct the parameter list in the source program. A DEF, FUNCTION, or SUB statement occurs within a multiline function or The statement is ignored.

Compiler Action: User Response: 11 Explanation:

Compiler Action: User Response: 12 Explanation:

Compiler Action: User Response: 13 Explanation:

Compiler Action: User Response: 14 Explanation: subprogram.

Compiler Action:

User Response: Correct the source program structure. Multiline functions and subprograms cannot be nested. 15 Explanation: A variable is missing. The statement is ignored. Enter the missing variable in the source code.

Compiler Action: User Response: 16

Explanation: The function or subprogram name is missing following the keyword DEF, FUNCTION, or SUB. Compiler Action: User Response: The statement is ignored. Enter a proper name after the keyword. The function or subprogram name is used previously. The new subroutine or function definition overrides the earlier one. User Response: Choose another name for the function or subprogram.

17

Explanation:

Compiler Action: User Response: 18 Explanation:

A FEND, END FUNCTION, or END SUB statement is missing.

Compiler Action: The compiler assumes an END FUNCTION, FEND, or END SUB statement exists as required. User Response: 19 Enter the proper statement in the source program.

Explanation: Too many parameters are specified in a multiline function or subprogram. The maximum number allowed is 15. Compiler Action: User Response: The statement is ignored. Correct the parameter list in the source program.

Appendix A. Compiler Error Messages

309

Error Code 20

Description Explanation: Inconsistent identifier usage. An identifier cannot be used as both a label and a variable. Compiler Action: User Response: The identifier references are ignored. Select differing identifiers for the label and the variable. Additional data exists in the source file following an END statement.

21

Explanation:

Compiler Action: The statements following the END are ignored. The END statement is the logical conclusion of the program. User Response: 22 Explanation: Response: Remove all statements following the END statement.

More than one DATA statement is on the same line. The second DATA statement on the same line is treated as a remark. Place all DATA statements on separate lines.

Compiler Action: User Response: 23

Explanation: There are no variables or function names in a declaration statement, or a reserved word appears in the list of identifiers. Compiler Action: User Response: The statement is ignored. Correct the list of variables in the source program.

24

Explanation: A function or subprogram name appears in a declaration within a function or subprogram other than the one being defined. Compiler Action: User Response: The duplicate declaration is ignored. Correct the declarations for the function or subprogram that are in error. A function or subprogram call has an incorrect number of parameters. The statement is ignored. Correct the parameter list in the source program. A left parenthesis is missing. The compiler assumes a left parenthesis exists. Enter the left parenthesis in the source program.

25

Explanation:

Compiler Action: User Response: 26 Explanation:

Compiler Action: User Response: 27

Explanation: Invalid mixed mode. The mixture of data types in this expression is not permitted. For example, you cannot add a string and an integer. Compiler Action: User Response: The expression is ignored. Correct the data type discrepancy in the source program. A unary operator cannot be used with this expression. The expression is ignored. Correct the operator or the expression in the source program. A function or subprogram call has improper type of parameters. The statement is ignored.

28

Explanation:

Compiler Action: User Response: 29 Explanation:

Compiler Action:

User Response: Correct the data type discrepancy in the source program. Ensure that the data types of the parameters match those of the function or subprogram declaration.

310

IBM 4680 BASIC: Language Reference

Error Code 30

Description Explanation: An invalid symbol follows a variable, constant, or function reference. The symbol is ignored. Remove or correct the invalid symbol in the source program. This symbol cannot occur at this location in an expression. The symbol is ignored. Remove or correct the symbol in the source program. An operator is missing.

Compiler Action: User Response: 31 Explanation:

Compiler Action: User Response: 32 Explanation:

Compiler Action: The compiler assumes a multiplication operator is missing. This might be the cause of additional errors in the program. User Response: 33 Explanation: parameter. Enter the proper operator in the source program. An expression contains an invalid symbol, misplaced keyword, or missing The invalid symbols are ignored.

Compiler Action:

User Response: Remove or correct invalid symbols, or enter any missing keywords and parameters in the source program. 34 Explanation: A right parenthesis is missing. The compiler assumes a right parenthesis exists. Enter the right parenthesis in the source program. A subscripted variable is used with the incorrect number of subscripts. The incorrect subscripted variable is ignored. Enter the correct number of subscripts for the variable.

Compiler Action: User Response: 35 Explanation:

Compiler Action: User Response: 36

Explanation: An identifier is used as a simple variable, but was previously used as a subscripted variable. Compiler Action: User Response: The incorrect variable reference is ignored. Choose a new identifier for one of the variables.

37

Explanation: An identifier is used as a subscripted variable, but was previously used as an unsubscripted variable. Compiler Action: User Response: The incorrect variable reference is ignored. Choose a new identifier for one of the variables. A string expression is used as a subscript in an array reference. The array reference is ignored.

38

Explanation:

Compiler Action:

User Response: Specify a proper subscript for the array reference. Subscripts must be integers or reals. 39 Explanation: A constant is missing. The statement or expression is ignored. Enter the missing constant in the source program.

Compiler Action: User Response:

Appendix A. Compiler Error Messages

311

Error Code 40

Description Explanation: Invalid symbol found in declaration list. The symbol is ignored. Remove or correct the invalid symbol in the declaration list. A carriage return is missing in a declaration statement. The compiler assumes the carriage return exists as required. Enter the carriage return in the source program. A comma is missing in a declaration list. The compiler assumes a comma exists. Enter the comma in the source program.

Compiler Action: User Response: 41 Explanation:

Compiler Action: User Response: 42 Explanation:

Compiler Action: User Response: 43

Explanation: A COMMON or GLOBAL declaration is specified in a multiline function or subprogram definition.. Compiler Action: The declaration statement is ignored.

User Response: Correct the declaration statement in the source program or move it to precede the function or subprogram definition. You cannot specify COMMON or GLOBAL declarations in multiline functions or subprograms. 44 Explanation: An identifier is specified twice in a declaration statement for the main program or for a multiline function or subprogram. Compiler Action: User Response: 45 Explanation: The declaration statement is ignored. Correct the declaration statement in the source program. The number of dimensions specified for an array exceeds 15.

Compiler Action: The compiler assumes a value of one dimension. This might be the cause of additional errors in the program. User Response: range. 46 Explanation: declaration. Specify a number of dimensions for the array within the allowable A right parenthesis is missing in an array dimension specification within a The compiler assumes a right parenthesis exists. Enter the right parenthesis in the source program. The same identifier is placed in a COMMON declaration twice. The declaration statement is ignored.

Compiler Action: User Response: 47 Explanation:

Compiler Action:

User Response: Correct the declaration statement in the source program. Each identifier can appear only once in a COMMON declaration. 48 Explanation: An invalid subscripted variable reference is encountered in a declaration statement. An integer constant is required. Compiler Action: The compiler assumes a subscript value of 1. This might be the cause of additional errors in the program. User Response: Specify a proper subscript value in the source program.

312

IBM 4680 BASIC: Language Reference

Error Code 49

Description Explanation: An invalid symbol is found following a declaration, or the symbol in the first statement in the program is invalid. Compiler Action: User Response: The compiler ignores the invalid symbol. Remove or correct the invalid symbol in the source program.

50

Explanation: An invalid symbol is encountered at the beginning of a statement or following a label. This error will also be generated if a declaration statement follows an executable statement. Compiler Action: User Response: The compiler ignores the invalid symbol. Remove or correct the invalid symbol in the source program. An equal sign is missing in an assignment statement. The compiler assumes an equal sign exists. Enter the equal sign in the source program.

51

Explanation:

Compiler Action: User Response: 52

Explanation: An identifier is used as a label, but was previously used at this level as either a label or variable. Compiler Action: User Response: The incorrect label reference is ignored. Choose another identifier for one of the labels. An unexpected symbol follows a simple statement. The compiler ignores the symbol. Remove or correct the symbol in the source program.

53

Explanation:

Compiler Action: User Response: 54

Explanation: A statement is not terminated with a carriage return. Text is ignored until the next carriage return. An unbalanced pair of BEGIN ENDIF Statements could also cause this error. Compiler Action: All subsequent text in the source program is ignored until the compiler detects a carriage return. User Response: Enter the carriage return in the source program.

55

Explanation: A function name is used in the left part of an assignment statement outside of a multiline function. Only within the function definition can its name appear on the left of an assignment statement. Compiler Action: User Response: The compiler ignores the assignment statement. Correct the assignment statement in the source program. A predefined function name is used as the left part of an assignment The compiler ignores the assignment statement. Correct the assignment statement in the source program. The THEN keyword is missing in an IF statement. The compiler assumes the THEN exists where appropriate. Enter the THEN in the source program.

56

Explanation: statement.

Compiler Action: User Response: 57 Explanation:

Compiler Action: User Response:

Appendix A. Compiler Error Messages

313

Error Code 58

Description Explanation: A WEND statement is missing. The compiler assumes the WEND statement exists. Enter the WEND statement in the source program. Missing carriage return or colon at the end of a WHILE loop header. The compiler assumes the carriage return or colon exists. Enter the carriage return or colon in the source program. Index variable specification is missing in a FOR statement. The compiler ignores the FOR statement. Specify an appropriate index variable in the FOR statement. The TO keyword is missing in a FOR statement. The compiler assumes the TO exists. Enter the TO in the source program. An equal sign is missing in a FOR loop header assignment. The compiler assumes an equal sign exists. Enter the equal sign in the source program. A carriage return or colon is missing at the end of a FOR statement. The compiler assumes the carriage return or colon exists. Enter the carriage return or colon in the source program.

Compiler Action: User Response: 59 Explanation:

Compiler Action: User Response: 60 Explanation:

Compiler Action: User Response: 61 Explanation:

Compiler Action: User Response: 62 Explanation:

Compiler Action: User Response: 63 Explanation:

Compiler Action: User Response: 64

Explanation: A NEXT statement is missing. Each FOR loop must be terminated with a NEXT statement Compiler Action: User Response: The compiler assumes the NEXT statement exists. Enter the NEXT statement in the source program.

65

Explanation: Characters precede a compiler directive on the same line. Nothing should precede a compiler directive on the same line. Compiler Action: User Response: a line by itself. The compiler ignores the directive. Remove the characters that precede the directive or place the directive on The variable in the NEXT statement does not match the FOR loop index The compiler ignores the erroneous variable. Specify a variable in the NEXT statement that matches the FOR statement NEXT statement encountered without a corresponding FOR loop header. The compiler ignores the NEXT statement.

66

Explanation: variable.

Compiler Action: User Response: index variable. 67 Explanation:

Compiler Action:

User Response: Remove the NEXT statement from the source program or enter a corresponding FOR loop header.

314

IBM 4680 BASIC: Language Reference

Error Code 68

Description Explanation: header. WEND statement encountered without a corresponding WHILE loop The compiler ignores the WEND statement.

Compiler Action:

User Response: Remove the WEND statement from the source program or enter a corresponding WHILE loop header. 69 Explanation: END FUNCTION, FEND, or END SUB statement encountered without a corresponding FUNCTION, DEF, or SUB statement. Compiler Action: The compiler ignores the statement.

User Response: Correct the function or subprogram definition, or remove the END FUNCTION, FEND, or END SUB statement from the source program. 70 Explanation: The PRINT USING string is not of type string. The compiler ignores the PRINT USING statement. Correct the data type of the PRINT USING string. A delimiter is missing in a PRINT statement. The compiler assumes a comma exists as a delimiter. Enter a comma or a semicolon as a delimiter in the source program.

Compiler Action: User Response: 71 Explanation:

Compiler Action: User Response: 72

Explanation: A semicolon is missing in an INPUT prompt string. The prompt string must end with a semicolon. Compiler Action: User Response: The compiler assumes a semicolon exists. Enter the semicolon in the source program. A delimiter is missing in an INPUT statement. The compiler assumes a comma exists as a delimiter. Enter a comma or a semicolon in the source program. A semicolon is missing following a file reference. The compiler assumes a semicolon exists. Enter a semicolon in the source program. The prompt string in an INPUT statement is not of type string. The compiler ignores the statement. Correct the data type of the prompt string in the source program.

73

Explanation:

Compiler Action: User Response: 74 Explanation:

Compiler Action: User Response: 75 Explanation:

Compiler Action: User Response: 76

Explanation: In an INPUT LINE statement, the variable following the keyword LINE is not a string variable. Compiler Action: User Response: The compiler ignores the statement. Correct the data type of the variable in the source program. In an INPUT statement, a comma is missing between variables. The compiler assumes a comma exists. Enter a comma in the source program.

77

Explanation:

Compiler Action: User Response:

Appendix A. Compiler Error Messages

315

Error Code 78

Description Explanation: The keyword AS is missing in an OPEN or CREATE statement. The compiler assumes the AS keyword exists. Enter the AS keyword in the source program. The filename in an OPEN or CREATE statement is not a string expression. The compiler ignores the statement. Correct the data type of the filename in the source. A delimiter is missing in a READ statement. The compiler assumes the delimiter exists. Enter an appropriate delimiter in the source program. The label might be an identifier previously used as a variable. The compiler ignores the statement. Enter the missing label in the source program. The label in a GOTO, GOSUB, or RESUME statement is not defined. The compiler ignores the statement.

Compiler Action: User Response: 79 Explanation:

Compiler Action: User Response: 80 Explanation:

Compiler Action: User Response: 81 Explanation:

Compiler Action: User Response: 82 Explanation:

Compiler Action:

User Response: Define the label in the source program. If the label is used in a function or subprogram, it must be defined in that function or subprogram. 83 Explanation: A delimiter is missing in a READ # statement. The compiler assumes a comma exists as a delimiter. Enter an appropriate delimiter in the source program.

Compiler Action: User Response: 84

Explanation: In a READ LINE statement, the variable following the keyword LINE is not a string variable. Compiler Action: User Response: The compiler ignores the statement. Correct the data type of the variable in the source program. The label in an IF END statement is not defined. The compiler ignores the statement. Define the label in the source program. A pound sign, #, is missing in an IF END statement. The compiler assumes the pound sign exists. Enter the pound sign in the source program. The THEN keyword is missing in an IF END statement. The compiler ignores the statement. Enter the THEN in the source program.

85

Explanation:

Compiler Action: User Response: 86 Explanation:

Compiler Action: User Response: 87 Explanation:

Compiler Action: User Response:

316

IBM 4680 BASIC: Language Reference

Error Code 88

Description Explanation: In a PRINT, READ, or WRITE statement, the semicolon is missing following a USING or FORM string or an expression was used for the USING or FORM string. Compiler Action: User Response: The compiler assumes the semicolon exists. Enter the semicolon in the source program. In an ON statement, a GOTO or GOSUB is missing. The compiler assumes the GOTO or GOSUB exists. Enter the appropriate keyword in the source program. The index variable in a FOR statement is of type string. The compiler ignores the statement.

89

Explanation:

Compiler Action: User Response: 90 Explanation:

Compiler Action:

User Response: The index variable must be an integer or real number. Correct the data type of the index variable in the source program. 91 Explanation: string. The expression following the keyword TO in a FOR statement is of type The compiler ignores the statement.

Compiler Action:

User Response: The expression must be an integer or real number. Correct the data type of the expression in the source program. 92 Explanation: string. The expression following the keyword STEP in a FOR statement is of type The compiler ignores the statement.

Compiler Action:

User Response: The expression must be an integer or real number. Correct the data type of the expression in the source program. 93 Explanation: variable. A variable in a DIM statement is defined as other than a subscripted The compiler ignores the statement. Correct the variable definition in the source program. An identifier is missing as an array name in a DIM statement. The compiler ignores the statement. Enter an appropriate array name in the source program. A left parenthesis is missing in a DIM statement. The compiler assumes a left parenthesis exists. Enter the left parenthesis in the source program. A right parenthesis is missing in a DIM statement. The compiler assumes a right parenthesis exists. Enter a right parenthesis in the source program.

Compiler Action: User Response: 94 Explanation:

Compiler Action: User Response: 95 Explanation:

Compiler Action: User Response: 96 Explanation:

Compiler Action: User Response:

Appendix A. Compiler Error Messages

317

Error Code 97

Description Explanation: exceeded. The maximum number of dimensions allowed for a subscripted variable is The compiler ignores the subscripted variable reference. Correct the subscripted variable reference in the source program. A comma is missing in a POKE statement. The compiler assumes the comma exists. Enter the comma in the source program. The index variable in a FOR statement is not a simple variable. The compiler ignores the statement.

Compiler Action: User Response: 98 Explanation:

Compiler Action: User Response: 99 Explanation:

Compiler Action:

User Response: Correct the index variable in the source program. It must be a nonsubscripted real or integer variable. 100 Explanation: statement. The name of a multiline function or subprogram is missing in a CALL The compiler ignores the statement. Enter the appropriate name in the CALL statement. A PRINT # statement is terminated with a comma or semicolon. The compiler ignores the statement.

Compiler Action: User Response: 101 Explanation:

Compiler Action:

User Response: Correct the statement in the source program. The PRINT # statement must end with an expression. 102 Explanation: A DIM statement is missing for a subscripted variable reference. Any subscripted variable must be dimensioned prior to its first use. Compiler Action: The compiler ignores the subscripted variable reference.

User Response: Enter an appropriate DIM statement or delete the variable reference from the source program. 103 Explanation: statement. A comma is missing in the label list of an ON GOTO or ON GOSUB The compiler assumes the comma exists. Enter the comma in the source program. The GOTO keyword is missing in an ON ERROR statement. The compiler assumes the GOTO keyword exists. Enter the GOTO in the source program. A comma is missing in a PUT or PUTLONG statement. The compiler assumes a comma exists. Enter the comma in the source program. The expression in an IF statement is of type string. The compiler ignores the statement.

Compiler Action: User Response: 104 Explanation:

Compiler Action: User Response: 105 Explanation:

Compiler Action: User Response: 106 Explanation:

Compiler Action:

User Response: The expression must be an integer or real number. Correct the data type of the expression in the source program.

318

IBM 4680 BASIC: Language Reference

Error Code 107

Description Explanation: The expression in a WHILE loop header is of type string. The compiler ignores the statement.

Compiler Action:

User Response: The expression must be an integer or real number. Correct the data type of the expression in the source program. 108 Explanation: In an OPEN or CREATE statement, the filename is missing. The compiler ignores the expression. Enter an appropriate filename in the statement.

Compiler Action: User Response: 109

Explanation: In an OPEN or CREATE statement, the expression following the reserved word AS is missing. Compiler Action: User Response: The compiler ignores the statement. Enter an appropriate expression in the statement. A nonrecursive multiline function or subprogram calls itself. The compiler ignores the function or subprogram. Correct the function or subprogram definition, or remove the incorrect

110

Explanation:

Compiler Action: User Response: call. 111

Explanation: A semicolon separates expressions in a PRINT # statement. A comma is substituted for the semicolon. Compiler Action: User Response: The compiler assumes the semicolons are commas. Change the semicolons to commas in the source program. A PRINT # statement does not have an expression list. The compiler ignores the statement. Enter an appropriate expression list in the source program. A TAB function is used in a PRINT # statement expression list. The compiler ignores the statement. Remove the TAB function from the expression list. A label is used as a variable in a list of expressions. The compiler ignores the label as a variable. Remove the label from the list of expressions. A GO not followed by a TO or SUB. The compiler assumes the GOTO keyword exists. Enter the appropriate keyword in the source program. Array parameters not allowed in a subprogram or function. The compiler ignores the statement.

112

Explanation:

Compiler Action: User Response: 113 Explanation:

Compiler Action: User Response: 114 Explanation:

Compiler Action: User Response: 115 Explanation:

Compiler Action: User Response: 116 Explanation:

Compiler Action:

User Response: Pass only simple string or numeric variables as formal parameters. To access an array within a function or subprogram, declare the array as either a global or local variable.

Appendix A. Compiler Error Messages

319

Error Code 117

Description Explanation: The code size of this module exceeds 64K. The compiler aborts compilation. Break the module into smaller components that have a code size that is Compiler has reached limit of 1024 internal labels. The compiler aborts compilation.

Compiler Action: User Response: less than 64K. 118 Explanation:

Compiler Action:

User Response: Reduce the size of the module or break it into smaller components. IF and ON GOSUB statements generate many internal labels. 119 Explanation: Too many open files: Check config.sys. The compiler aborts compilation.

Compiler Action:

User Response: This is a DOS or OS2-only message. Add the statement FILES=20 to the CONFIG.SYS file that is used to boot up the system and then reboot. 120 Explanation: Out of Memory The compiler aborts compilation.

Compiler Action:

User Response: Execute the compilation on a machine that has more memory or break the module into smaller components for compilation. 121 Explanation: Error closing .LST file The compiler aborts compilation.

Compiler Action:

User Response: Clear the unused files from the disk drive in order to provide the required disk space. 122 Explanation: Error writing to or closing .OBJ file The compiler aborts compilation.

Compiler Action:

User Response: Clear the unused files from the disk drive in order to provide the required disk space. 123 Explanation: RETURN incorrectly used. Use EXIT SUB or EXIT FUNCTION statement. The compiler ignores the statement.

Compiler Action:

User Response: Replace the RETURN statement with an EXIT SUB or EXIT FUNCTION statement, as appropriate. 124-128 182-224 Explanation: Explanation: 124 through 128 are not used. A reserved word has been used as an identifier. The compiler ignores the statement. Change the reserved word to another identifier. 225 through 299 are not used. Missing pound sign (#) in WRITE # statement. The compiler assumes the pound sign (#) exists. Enter the pound sign (#) in the source program.

Compiler Action: User Response: 225-299 300 Explanation: Explanation:

Compiler Action: User Response:

320

IBM 4680 BASIC: Language Reference

Error Code 301

Description Explanation: FORM keyword not allowed in READ data statement. The compiler ignores the statement. Remove the FORM keyword from the READ statement in the source Missing variable in WRITE statement. The compiler ignores the statement. Enter an appropriate variable in the source program.

Compiler Action: User Response: program. 302 Explanation:

Compiler Action: User Response: 303

Explanation: The format string in a READ FORM or WRITE FORM statement is not of string data type. Compiler Action: User Response: The compiler ignores the statement. Correct the data type of the format string in the source program. FORM keyword not allowed in READ data or READ LINE statement. The compiler ignores the statement. Remove the FORM keyword from the statement in the source program.

304

Explanation:

Compiler Action: User Response: 305

Explanation: The syntax of the ACCESS statement is incorrect. A comma could be missing or a reserved word could be spelled incorrectly. Compiler Action: User Response: The compiler ignores the statement. Correct the statement in the source program. Pathname is not a string in CHDIR, MKDIR, or RMDIR statement. The compiler ignores the statement. Correct the data type of the pathname in the source program. A right parenthesis cannot immediately follow a left parenthesis. The compiler ignores the expression. Correct the expression in the source program. An ENDIF statement is missing. The compiler assumes the ENDIF statement exists. nter the ENDIF statement in the source program. 309 through 319 are not used. Missing comma in ASSIGNKEY statement. The compiler assumes the comma exists. Enter the comma in the source program. Keyword ON or OFF is missing from the FUNCTIONKEY statement. The compiler ignores the statement. Enter the appropriate keyword in the source program.

306

Explanation:

Compiler Action: User Response: 307 Explanation:

Compiler Action: User Response: 308 Explanation:

Compiler Action: User Response: 309319 320 Explanation: Explanation:

Compiler Action: User Response: 321 Explanation:

Compiler Action: User Response:

Appendix A. Compiler Error Messages

321

Error Code 322

Description Explanation: A comma or semicolon is missing from the LOCATE statement. The compiler assumes a comma exists. Enter the appropriate delimiter in the source program. Keyword OFF or ON is missing from the LOCATE statement. The compiler ignores the statement. Enter the appropriate keyword in the source program. READ FORM statement cannot read DATA statement data. The compiler ignores the READ FORM statement. You must use a READ statement to read the data in a DATA statement. 325 through 327 are not used ASSIGNKEY keystring is not a string. The compiler ignores the statement. Correct the data type of the keystring in the source program. OPTION statement expression is not a string. The compiler ignores the statement. Correct the data type of the OPTION statement expression in the source This combination of attributes is not allowed. The compiler ignores the statement. Enter the appropriate attribute keywords in the source program.

Compiler Action: User Response: 323 Explanation:

Compiler Action: User Response: 306 Explanation:

Compiler Action: User Response: 325-327 328 Explanation: Explanation:

Compiler Action: User Response: 329 Explanation:

Compiler Action: User Response: program. 330 Explanation:

Compiler Action: User Response: 331

Explanation: EXIT FUNCTION or EXIT SUB statement is outside of function or subprogram definition. Compiler Action: The compiler ignores the statement.

User Response: Remove the EXIT FUNCTION or EXIT SUB statement, or correct the function or subprogram definition. 332 Explanation: FUNCTION or SUB keyword does not follow the EXIT keyword. The compiler ignores the statement. Enter the appropriate keyword after EXIT in the source program. A subprogram cannot return a value. The compiler ignores the invalid statements in the subprogram.

Compiler Action: User Response: 333 Explanation:

Compiler Action:

User Response: Correct the subprogram logic in the source program. Only a function can return a value to the calling program. 334-399 400 Explanation: 334 through 399 are not used.

Explanation: AUTOLOCK is only allowed for a READ statement when you specify a record number or KEY. Compiler Action: The compiler ignores the READ statement.

User Response: Remove the AUTOLOCK keyword from the READ statement or specify an appropriate record number or KEY in the READ statement.

322

IBM 4680 BASIC: Language Reference

Error Code 401

Description Explanation: Number of records specification is missing in a CREATE POSFILE RANDOM/DIRECT or CREATE POSFILE KEYED statement. Compiler Action: User Response: program. The compiler ignores the statement. Enter an appropriate number of records specification in the source Missing comma in a CREATE POSFILE statement. The compiler assumes the comma exists. Enter the comma in the source program. Missing record length specification in a CREATE POSFILE statement. The compiler ignores the statement. Enter the record length specification in the source program. More than 31 devices are specified in a WAIT statement. The compiler ignores the statement. Remove any device specifications in excess of the 31 allowed in a WAIT Missing ATCLOSE or PERUPDATE keyword in a CREATE POSFILE The compiler ignores the statement. Enter the appropriate keyword in the source program. Keyword ON is missing from an OPEN SESSION statement. The compiler assumes the keyword exists. Enter the keyword in the source program. Link number is missing from an OPEN SESSION statement. The compiler ignores the statement. Enter an appropriate link number in the source program. Record identification is missing from an OPEN LINK statement. The compiler ignores the statement. Enter an appropriate record identification in the source program. Host identification is not allowed in an OPEN LINK ASYNC statement. The compiler ignores the statement.

402

Explanation:

Compiler Action: User Response: 403 Explanation:

Compiler Action: User Response: 404 Explanation:

Compiler Action: User Response: statement. 405 Explanation: statement.

Compiler Action: User Response: 406 Explanation:

Compiler Action: User Response: 407 Explanation:

Compiler Action: User Response: 408 Explanation:

Compiler Action: User Response: 409 Explanation:

Compiler Action:

User Response: Correct the OPEN LINK statement in the source program by removing the ASYNC keyword or specifying proper link information. 410-411 412 Explanation: Explanation: 410 and 411 are not used. The bind variable in an OPEN SESSION statement is not a string variable. The compiler ignores the statement. Enter an appropriate string variable for the statement in the source

Compiler Action: User Response: program.

Appendix A. Compiler Error Messages

323

Error Code 413

Description Explanation: string. A required string parameter for an OPEN LINK statement is not of type The compiler ignores the statement. Enter an appropriate string parameter in the source program. The BINDVAR keyword is missing from an OPEN SESSION statement. The compiler ignores the statement. Enter the keyword in the source program. The POSFILE keyword is missing from a CREATE POSFILE KEYED The compiler ignores the KEYED keyword in the CREATE KEYED

Compiler Action: User Response: 414 Explanation:

Compiler Action: User Response: 415 Explanation: statement.

Compiler Action: specification.

User Response: Enter the POSFILE keyword in the source program. The statement should be CREATE POSFILE KEYED. 416 Explanation: KEYED and DIRECT keyword only allowed in an OPEN statement when a record length is specified. Compiler Action: The compiler ignores the statement.

User Response: Remove the DIRECT or KEYED keyword, or specify an appropriate record length in the source program. 417 Explanation: statement. I/O session number is missing in a WRITE LOGO or WRITE MATRIX The compiler ignores the statement. Enter an appropriate I/O session number in the source program. Missing comma in a WRITE MATRIX statement. The compiler assumes the comma exists. Enter the comma in the source program.

Compiler Action: User Response: 418 Explanation:

Compiler Action: User Response: 419

Explanation: First argument of a WRITE MATRIX statement is not a one-dimensional string array element. Compiler Action: User Response: The compiler ignores the statement. Correct the argument specifications in the source program.

420

Explanation: An attempt was made to compile a READ KEY statement with a key value that is not of type string. Compiler Action: User Response: The compiler ignores the key value specification. Change the key value specification to a string. Keyvalue is not of type string in a DELREC statement. The compiler ignores the statement. Change the data type of the keyvalue in the source program.

421

Explanation:

Compiler Action: User Response:

324

IBM 4680 BASIC: Language Reference

Error Code 422

Description Explanation: Filename is not of type string in a LOAD statement. The compiler ignores the statement. Change the data type of the filename in the source program. Missing semicolon in a WAIT statement. The compiler assumes the semicolon exists. Enter the semicolon in the source program. I/O session number in a WAIT statement cannot be a string. The compiler ignores the statement. Change the data type of the I/O session number in the WAIT statement. Missing comma in an UNLOCKDEV statement. The compiler assumes the comma exists. Enter the comma in the source program. Missing semicolon in a POINT statement. The compiler assumes the semicolon exists. Enter the semicolon in the source program. Missing semicolon in a DELREC statement. The compiler assumes the semicolon exists. Enter the semicolon in the source program. Missing comma in an OPEN SERIAL statement. The compiler assumes the comma exists. Enter the comma in the source program. Missing AS keyword in an OPEN SERIAL statement. The compiler assumes the AS keyword exists. Enter the keyword in the source program. Comma is not followed by PURGE in a LOCKDEV statement. The compiler assumes the PURGE keyword exists. Enter the keyword in the source program. Comma is not followed by PRIORITY in an UNLOCKDEV statement. The compiler assumes the PRIORITY keyword exists. Enter the keyword in the source program. The subroutine specified in an ON ASYNC ERROR statement cannot be The compiler ignores the statement. Make the ON ASYNC ERROR subroutine internal to the module.

Compiler Action: User Response: 423 Explanation:

Compiler Action: User Response: 424 Explanation:

Compiler Action: User Response: 425 Explanation:

Compiler Action: User Response: 426 Explanation:

Compiler Action: User Response: 427 Explanation:

Compiler Action: User Response: 428 Explanation:

Compiler Action: User Response: 429 Explanation:

Compiler Action: User Response: 430 Explanation:

Compiler Action: User Response: 431 Explanation:

Compiler Action: User Response: 432 Explanation: external.

Compiler Action: User Response:

Appendix A. Compiler Error Messages

325

Error Code 433

Description Explanation: statement. Buffer size specification is allowed only in an OPEN LINK ASYNC The compiler ignores the statement.

Compiler Action:

User Response: Remove the buffer size specification or enter the ASYNC keyword as appropriate in the source program. 434 Explanation: Argument in a WRITE LOGO statement is not a 1-byte integer one-dimensional array element. Compiler Action: User Response: program. 435 Explanation: The compiler ignores the statement. Correct the arguments to the WRITE LOGO statement in the source Flag specification following %ENVIRON directive is incorrect or missing. The compiler ignores the directive.

Compiler Action:

User Response: Specify the appropriate flag after the %ENVIRON directive in the source program (either T or C). 436 Explanation: Keyword is not allowed in this environment. The compiler ignores the keyword.

Compiler Action:

User Response: Remove the keyword from the source program or compile the program for the other environment. 437 Explanation: The %ENVIRON directive has already been specified. The compiler ignores the extraneous %ENVIRON directive. Remove the extraneous %ENVIRON directive from the source program. Link specification is missing or incorrect in an OPEN LINK statement. The compiler ignores the statement. Enter an appropriate link specification in the source program. A direct or keyed file cannot be opened in APPEND mode. The compiler ignores the OPEN statement. Remove the APPEND keyword from the source program. The keyword ERROR is missing from an ON ASYNC ERROR statement. The compiler assumes the ERROR keyword exists. Enter the keyword in the source program. The keyword CALL is missing from an ON ASYNC ERROR statement. The compiler assumes the CALL keyword exists. Enter the keyword in the source program.

Compiler Action: User Response: 438 Explanation:

Compiler Action: User Response: 439 Explanation:

Compiler Action: User Response: 440 Explanation:

Compiler Action: User Response: 441 Explanation:

Compiler Action: User Response: 442

Explanation: The identifier specified in an ON ASYNC ERROR statement is not the name of a subprogram with the correct parameters. Compiler Action: User Response: The compiler ignores the statement. Enter an appropriate identifier in the source program.

326

IBM 4680 BASIC: Language Reference

Error Code 443

Description Explanation: An I/O session number must be specified in the CLEARS statement in the 4683 Point of Sale environment. Compiler Action: User Response: The compiler ignores the statement. Enter an appropriate I/O session number in the source program. 444 is not used. Could not open file: filename.ext. The compiler aborts compilation.

444 445

Explanation: Explanation:

Compiler Action:

User Response: This error is often generated when a file is not found. Make sure the named file is available to the compiler and spelled correctly in the source file before attempting to re-compile. 446 Explanation: Invalid filename: filename.ext. The compiler aborts compilation. Filename used must meet filename syntax requirements. 447 is not used. More than 65,535 functions and subprograms. The compiler aborts compilation.

Compiler Action: User Response: 447 448 Explanation: Explanation:

Compiler Action:

User Response: Break the module into components that contain fewer than 65,535 functions and subprograms. 449 Explanation: Could not create: filename.ext. The compiler aborts compilation.

Compiler Action:

User Response: Several possibilities exist: The specified path may not be valid, the machine may be out of disk space, or a file to be written is opened by another process. 450 451 Explanation: Explanation: 450 is not used. Disk full. The compiler aborts compilation.

Compiler Action:

User Response: Clear the unused files from the disk to allow enough room to execute the compilation and store the object file. You may possibly bypass this error by redirecting the compiler work files to another drive using the x option on the compiler. 452-453 454 Explanation: Explanation: 452 and 453 are not used. Close or delete error on file: filename.ext. The compiler aborts compilation. Check to see if diskette has been removed. 455 and 456 are not used. Expression overflow -- The expression is too complex. The compiler aborts compilation. Reduce the complexity of the flagged statement.

Compiler Action: User Response: 455-456 457 Explanation: Explanation:

Compiler Action: User Response:

Appendix A. Compiler Error Messages

327

Error Code 458

Description Explanation: Includes nested too deep. The compiler aborts compilation. Restructure the include files to reduce the level of include file nesting. 459 is not used. Missing source filename. The compiler aborts compilation. Specify source filename. 461 through 463 is not used. The size of the DATA statement exceeds 64K. The compiler aborts compilation.

Compiler Action: User Response: 459 460 Explanation: Explanation:

Compiler Action: User Response: 461-463 464 Explanation: Explanation:

Compiler Action:

User Response: The number and size of variable declarations must be reduced to fit within a 64K data space.

Internal Failures
Internal failures represent a serious compiler error. The compiler indicates an internal failure with the following type of message sent to the computer screen:
filename line column: INTERNAL COMPILER FAILURE --nnn where --nnn is a negative number.

Note: In certain cases, the filename, line, and column may not be listed. This manual lists none of the internal compiler errors that you might receive because none of them have a recovery. If an internal failure occurs during compilation of your application program, copy your application program and any necessary include files onto a diskette. Recompile your application with the same compiler toggle settings and add the following to the command line, preceded by a single blank space:
>filename.ext

This creates a file with the same compiler-generated output information that is usually sent to the screen. Copy this file onto the diskette that has your application program and other files. For example, the following compiler command line produces a file called MYPROG.ERR that would contain the internal compiler failure information.
C>BASIC MYPROG >MYPROG.ERR

Contact your service representative when you have gathered this information.

328

IBM 4680 BASIC: Language Reference

Appendix B. Runtime Error Messages


Runtime errors are detected in a program during execution. IBM 4680 BASIC provides the four following functions that enable you to identify the runtime error and its cause: v ERR v ERRN v ERRF% v ERRL. The ERR function returns a two-character string signifying the last runtime error to occur in a program. This appendix lists all the two-character runtime error codes and their descriptions. 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 can generate a specific ERR code. Refer to the IBM 4680 Store System: Messages Guide or the IBM 4690 Store System: Messages Guide for return codes not found in this appendix. Here is an example of how ERR and ERRN work. An application program attempts to write data to the alphanumeric display, but the device is not physically connected to the system. The alphanumeric display driver returns the error code 80A00005 (hex). During runtime, the application can obtain that value using the ERRN function. The error code 80A00005 corresponds to the two-character runtime error code DO. The application can obtain the string DO using the ERR function. Use the ERRF% function to return the I/O session number associated with an I/O runtime error. The ERRL function returns the compiler generated line number in which the last runtime error occurred (only if the application program was compiled with the N toggle). See Chapter 7, Statements and Language-Defined Functions for more details on each of the runtime error functions.

Synchronous Error Recovery


The RESUME statement allows recovery from runtime errors that are not due to faulty program logic and that are not handled by the IF END statement. There are three different forms of the RESUME statement, each valid for a different category of error. Each error listed in this appendix is identified as RESUME only, RESUME label, or RESUME RETRY.

RESUME only
For RESUME only errors, the RESUME statement can be used either by itself or with a label. If no label is specified, the runtime resumes execution with the next statement following the statement in which the error was encountered. If a label is specified, the runtime resumes execution at the address specified by the label.

Copyright IBM Corp. 1985, 2003

329

RESUME label
For RESUME label errors, the RESUME statement must specify a label at which execution is to resume. You can use RESUME label in any situation to recover from an error.

RESUME RETRY
For RESUME RETRY errors, the RESUME statement can be used with the RETRY option. The RETRY option specifies that the runtime must retry the operation in which the error was encountered.

Asynchronous Error Recovery


See the ON ASYNC ERROR CALL statement in Chapter 7, Statements and Language-Defined Functions for information on recovering from asynchronous errors.

Additional Information Storage Considerations


To conserve storage, resume operations to the next consecutive statement are valid only for I/O errors. This includes the RESUME and RESUME RETRY forms of the RESUME statement. There is a certain amount of storage overhead associated with every level of a nested error handling situation. If an error is detected during the processing of a preceding error, control immediately jumps to the beginning of the ON ERROR routine. Recovery from an out-of memory error (ERR = OM) is extremely difficult because the program needs to free some storage. To prevent your application from getting into an infinite loop due to an OM error, the first statement in your ON ERROR routine should test if ERR = OM. If it is, do not attempt to initialize or increase the size of a string variable. Such an attempt can cause the runtime library to try to obtain more storage, which results in another OM error. If, in attempting to recover from a runtime error, your application gets in a series of runtime errors, your application will run out of stack space and will cause a stack exception to occur. For example, if your application is executing as a background application and it tries to write to the display, it will get a runtime error since it has no virtual console to write to. If you try to display the error, or a message, while in your ON ERROR routine, you will get another WRITE error (and this will continue until you use up all of your stack). This will cause your application to be terminated and may cause the executing machine to re-IPL, depending on your configuration option.

I/O Operations
When a runtime error occurs during an I/O operation, that I/O session number should not be closed in the ON ERROR code. Closing it before resuming from the error leaves runtime data pertaining to that session number in an indeterminate state. If a file, pipe, device or communication link must be closed because of an error, the ON ERROR code should set a flag to be checked in the mainline code, where the I/O session can be safely closed.

330

IBM 4680 BASIC: Language Reference

Multiple ON ERROR Routines


Consider a program consisting of two subprograms, Mod1 and Mod2. Mod1 has an ON ERROR statement transferring control to label ABC within Mod1 and a CALL statement transferring control to Mod2. Mod2 has an ON ERROR statement transferring control to a label XYZ within Mod2. When the Mod2 END SUB statement transfers control back to Mod1, the original ON ERROR GOTO ABC is restored when control returns to Mod1.

No ON ERROR Routine Specified


If a runtime error occurs in the terminal and no ON ERROR routine is in effect, the application will be terminated and the default application will be loaded. The application loader will log an error and will display an error code. See the following paragraph for a description of the error code format. If the default application was the application terminated, the application loader will display W100 (the application cannot be loaded). If a runtime error occurs in the store controller and no ON ERROR routine is in effect, the application will be terminated and the following message will be displayed: ??? Runtime Error: xx where xx is the ERR code of the error. If the application is started from Command Mode, an additional error is written to the display. The following is an example of error code format:
80F4yyyy

where yyyy is the ASCII representation of the ERR code. In addition, an ERR=OE will result in an error code of 80F44F45. Notes: 1. A program terminates if a runtime error occurs with no ON ERROR statement in effect. 2. Every time you enter an ON ERROR routine, important runtime subroutine library state data is saved. Therefore, it is imperative that you issue a RESUME statement for each entry into the ON ERROR routine. For example, the following error handling sequence is not correct and produces unpredictable results: a. A WRITE # statement is issued in the mainline code and an error is returned. b. In the ON ERROR routine, another error occurs and the application issues a RESUME label statement. The label is back in the mainline (not in the ON ERROR routine) code. In the example above, the ON ERROR routine was entered twice, but only exited once (via the RESUME label). To ensure proper error handling, you may want to increment a counter every time your ON ERROR routine is entered and decrement it before a RESUME or RESUME RETRY statement is executed. The value should be decremented and tested (to be equal to zero) before issuing a RESUME label statement that directs program execution outside the ON ERROR routine. If the counter has a value greater than zero, you can issue a RESUME label to within the ON ERROR routine and perform the decrement and test again. 3. Software interrupts are disabled during synchronous I/O operations. Therefore, code each ON ERROR routine to execute no more than 20 asynchronous I/O operations. Executing more than 20 can cause your application to halt. 4. Software interrupts are enabled only on Resume.
Appendix B. Runtime Error Messages

331

5. Failure to do Resumes results in a hang after 31 asynchronous events occur.


ERR Code AC ERRN Code 00000002 Description Explanation: The argument to an ASC function is a null string. Program terminates unless you have an ON

Runtime Subroutine Library (RTSL) Action: ERROR routine in effect.

User Response: RESUME label - Modify your source program to ensure that the argument passed to the ASC function is not null. AE 00000004 Explanation: An attempt was made to access an array element before the array DIM statement was made. RTSL Action: Program terminates unless you have an ON ERROR routine in effect. User Response: RESUME label - Modify your source program to ensure that the argument passed to the ASC function is not null. AK 000000B0 Explanation: A bad parameter was passed to the ASSIGN key statement. RTSL Action: Program aborts unless you have an ON ERROR routine in effect. User Response: RESUME only/RESUME label AS 80B20607 Explanation: RTSL Action: User Response: AS 80B20608 Explanation: RTSL Action: User Response: AY 000000A2 Explanation: RTSL Action: Host Communication - SNA session already in use. Program aborts unless you have an ON ERROR routine in effect. RESUME label/RESUME label/RESUME RETRY

Host Communication - SNA session already active. Program aborts unless you have an ON ERROR routine in effect. RESUME label/RESUME label/RESUME RETRY

Asynchronous error detected, but no asynchronous error routine in effect. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - You must use an ON ASYNC ERROR CALL statement and define the required subprogram to process the asynchronous error. AZ 0000009C Explanation: The program tried to create an array whose size cannot be handled by run-time (i.e., its size is over 64K). RTSL Action: User Response: Program terminates unless you have an ON ERROR routine in effect. RESUME label - Change the DIM statement to create a smaller array.

332

IBM 4680 BASIC: Language Reference

ERR Code BB

ERRN Code

Description

80F206A5 Explanation: Shared I/O Access Method - Received a read request that contained a negative value for the number of bytes to read. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

BB

80F206A6 Explanation: Shared I/O Access Method - SIOAM received a remote pipe read/write request or a pipe routing service write request with count less than 0 or greater than 120 bytes to read. RTSL Action: Program aborts unless you have an ON ERROR routine in effect.

User Response: RESUME only/RESUME label - Modify your source program to request a valid number of bytes to read or write. BB 80F206A7 Explanation: Shared I/O Access Method - File write request for byte count exceeding maximum of 512 bytes. RTSL Action: User Response: BD 808304A4 Explanation: RTSL Action: User Response: BD 80A30561 Explanation: RTSL Action: User Response: BD Program aborts unless you have an ON ERROR routine in effect. RESUME label

Totals Retention - Internal CRC error. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

Scale - Read error. A scale error was detected while trying to read the scale. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

80A30562 Explanation: Scale - Data value error. A scale error was detected or an incompatible scale was attached. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

BD

80A30563 Explanation: RTSL Action:

Scale - Scale in motion, not connected, over/under capacity Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

User Response: BD 80A30564 Explanation: RTSL Action: User Response: BD 80B00661 Explanation: RTSL Action: User Response: BD 80B00662 Explanation: RTSL Action: User Response:

Scale - Scale reads zero. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

Host Communication - Async read byte is bad. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY.

Host Communication - Async read bytes are bad. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY.

Appendix B. Runtime Error Messages

333

ERR Code BD

ERRN Code

Description Host Communication - Async read buffer wrapped. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY.

80B00664 Explanation: RTSL Action:

User Response: BD 80B00668 Explanation: RTSL Action: User Response: BD 80B00669 Explanation: RTSL Action: User Response: BI 80B20613 Explanation: RTSL Action: User Response: BN 00000006

Host Communication - Async read record bad, parity error. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY.

Host Communication - Async read record bad, overrun error. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY.

Host Communication - SNA host BIND data error. Program aborts unless you have an ON ERROR routine in effect. RESUME label

Explanation: The value following the BUFF option in an OPEN or CREATE statement is less than 0 or greater than 128. RTSL Action: Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to ensure that the BUFF value is in the proper range. BO 808404C1 Explanation: RTSL Action: User Response: BO 808404C7 Explanation: RTSL Action: User Response: BO 808404CA Explanation: RTSL Action: User Response: BO 808404CD Explanation: RTSL Action: I/O Processor - Keyboard buffer overrun. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

I/O Processor - OCR device or magnetic wand buffer overrun. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

I/O Processor - Scanner buffer overrun. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

I/O Processor - Callers buffer overflow. Program aborts unless you have an ON ERROR routine in effect.

User Response: RESUME label. The data received by the I/O Processor exceeded the size of the buffer from the application. The application programmer can flush the buffer and continue or change the application to define a larger buffer. BO 808404CE Explanation: RTSL Action: User Response: I/O Processor - Alphanumeric keyboard buffer overrun. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

334

IBM 4680 BASIC: Language Reference

ERR Code BO

ERRN Code

Description I/O Processor - Matrix keyboard buffer overrun. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

808404D1 Explanation: RTSL Action:

User Response: BO 8090052F Explanation: RTSL Action:

Journal Buffer Exceeded. Program aborts unless you have ON ASNYNC ERROR routine in effect.

User Response: Eject document and display error message. Using Terminal Configuration Utility, change the Journal Buffer Size in the appropriate terminal device group. BO 80980582 Explanation: RTSL Action: User Response: BO 80A5000B Explanation: RTSL Action: User Response: BO Serial I/O - Buffer overrun. Program aborts unless you have an ON ERROR routine in effect. RESUME label. Data was lost, take appropriate recovery procedures.

MSR - Too much or too little data received from the card. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY.

80B0000E Explanation: Host Communication - Async record received larger than read buffer. Next read will return rest of the data. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY.

BO

80B1000E Explanation: Host Communication - Bisync record received larger than read buffer. Next read will return rest of the data. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY.

BO

80B20610 Explanation: Host Communication - SNA received data blocksize greater than the application blocksize. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME label

BW

80840017

Explanation: RTSL Action:

IOPROC - Trying to read data and driver is locked. Program aborts unless you have an ON ERROR routine in effect. RESUME label.

User Response: BW 80A50017 Explanation: RTSL Action: User Response: BZ 80B20002 Explanation: RTSL Action: User Response:

MSR - Trying to read data and device is locked. Program aborts unless you have an ON ERROR routine in effect. RESUME label.

Host Communication - Error recovery in process. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY.

Appendix B. Runtime Error Messages

335

ERR Code BZ

ERRN Code

Description Host Communication - Adapter is busy. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY.

80B205E2 Explanation: RTSL Action:

User Response: BZ 80B305E2 Explanation: RTSL Action: User Response: CC 80860464 Explanation: RTSL Action: User Response: CD 00000090 Explanation: RTSL Action: User Response: exists. CE 00000008 Explanation: RTSL Action:

Host Communication - Adapter is busy. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY.

Cash Drawer - Requested Cash Drawer is not connected. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

The directory specified in the CHDIR function call does not exist. Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program to ensure that the directory

The file being closed cannot be found in the directory. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME only/RESUME label - Modify your source program to ensure that you do not delete a file and then try to close it. CM 0000000A Explanation: directory. RTSL Action: The file specified in a CHAIN statement cannot be found in the selected Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Either modify your source program to specify the correct file, or add the file to the selected directory. CM 80F00406 Explanation: found. RTSL Action: User Response: CP 80A00006 Explanation: RTSL Action: User Response: CP 80A10006 Explanation: RTSL Action: User Response: CP 80AA0006 Explanation: RTSL Action: User Response: Application Loader - Program specified in a CHAIN statement could not be Program aborts unless you have an ON ERROR routine in effect. RESUME label

First alphanumeric or operator display - Invalid cursor position found. Program aborts unless you have an ON ERROR routine in effect. RESUME label

First video Display - Invalid cursor position found. Program aborts unless you have an ON ERROR routine in effect. RESUME label

Second alphanumeric or operator display - Invalid cursor position found. Program aborts unless you have an ON ERROR routine in effect. RESUME label

336

IBM 4680 BASIC: Language Reference

ERR Code CP

ERRN Code

Description Second video Display - Invalid cursor position found. Program aborts unless you have an ON ERROR routine in effect. RESUME label

80AB0006 Explanation: RTSL Action:

User Response: CR

80B20603 Explanation: Host Communication - SNA SSCP ID or XID from host does not match configured ID. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME label

CR

80B20617 Explanation: RTSL Action:

Host Communication - SNA Session not configured. Program aborts unless you have an ON ERROR routine in effect. RESUME label

User Response: CR 80B305E3 Explanation: RTSL Action: User Response: CT 0000000C Explanation: RTSL Action: User Response: .286 files. CU 0000000E Explanation: RTSL Action:

Host Communication - Configuration record error. Program aborts unless you have an ON ERROR routine in effect. RESUME label

The filetype of the file specified in a CHAIN statement is not OVR or 286. Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program to chain only to .OVR or

A CLOSE statement specifies a file identification number that is not active. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME only/RESUME label - Modify your source program to close the proper file or remove the CLOSE statement from the source program. CX 00000010 Explanation: RTSL Action: Overlay does not fit in overlay area. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - The program might be chaining to an invalid overlay file or to the wrong version of an overlay. Ensure that the overlay file was generated at the same time as the root program. CY 00000012 Explanation: RTSL Action: User Response: overlay file. DISK read error during loading of overlay. Program terminates unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY - Try regenerating the

Appendix B. Runtime Error Messages

337

ERR Code *D

ERRN Code variable

Description Explanation: RTSL Action: The IBM 4860 Operating System returned an unexpected error code. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Use the ERRN function to determine the precise error code. Copy the following files onto a diskette: v The executable load module (.286 file that was created) with the following linker options: [MAP[ALL],LI,LO] v The symbols file (.SYM file) v The map file (.MAP file) v The shared runtime library (.SRL file), if applicable v The appropriate version of the .L86 file Contact your service representative when you have gathered the above information. DE 000000A8 Explanation: RTSL Action: Invalid disable, enable sequence. All disables must have one matching enable. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Ensure that each DISABLE statement is followed by a matching ENABLE statement. DF 00000014 Explanation: An OPEN or CREATE statement uses a file identification number that is already used. RTSL Action: Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME only/RESUME label - Modify your source program to use a different I/O session number. DI 80900527 Explanation: RTSL Action: Document Insert Station - Improper DI throat position. Program aborts unless you have an ON ASYNC ERROR routine in effect.

User Response: RETRYFLAG may be set on or off. If set on, the OVERLAYSTR may be set to a value. A message should be displayed and then retry. DI 80900528 Explanation: RTSL Action: Document Insert Station - Document missing in DI. Program aborts unless you have an ON ASYNC ERROR routine in effect.

User Response: RETRYFLAG may be set on or off. If set on, the OVERLAYSTR may be set to a value. A message should be displayed and then retry. DI 80900529 Explanation: RTSL Action: Document Insert Station - Document not allowed in DI. Program aborts unless you have an ON ASYNC ERROR routine in effect.

User Response: RETRYFLAG may be set on or off. If set on, the OVERLAYSTR may be set to a value. A message should be displayed and then retry. DK 000003F2 Explanation: RTSL Action: An attempt was made to delete a record from a non-keyed file. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to use the correct I/O session number. DO 80830005 Explanation: RTSL Action: User Response: Total Retention device offline. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

338

IBM 4680 BASIC: Language Reference

ERR Code DO

ERRN Code 80830007

Description Explanation: RTSL Action: User Response: Totals Retention - Device failure. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY.

DO

808404C3 Explanation: RTSL Action:

I/O Processor - Keyboard failure. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

User Response: DO 808404C4 Explanation: RTSL Action: User Response: DO 808404C5 Explanation: RTSL Action: User Response: DO 808404C6 Explanation: RTSL Action: User Response: DO 808404C8 Explanation: RTSL Action: User Response: DO 808404C9 Explanation: RTSL Action: User Response: DO 808404CF Explanation: RTSL Action: User Response: DO 808404D0 Explanation: RTSL Action: User Response: DO 808404D2 Explanation: RTSL Action: User Response: DO 808404D3 Explanation: RTSL Action: User Response:

I/O Processor - Keyboard offline. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

I/O Processor - OCR device or magnetic wand failure. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

I/O Processor - OCR device or magnetic wand offline. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

I/O Processor - Scanner failure. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

I/O Processor - Scanner offline. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

I/O Processor - Alphanumeric keyboard failure. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

I/O Processor - Alphanumeric keyboard offline. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

I/O Processor - Matrix keyboard failure. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

I/O Processor - Matrix keyboard offline. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

Appendix B. Runtime Error Messages

339

ERR Code DO

ERRN Code 80850005

Description Explanation: RTSL Action: User Response: Tone - Device offline. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

DO

80860005

Explanation: RTSL Action:

Cash Drawer - Device offline. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

User Response: DO 80860007 Explanation: RTSL Action: User Response: DO 80900005 Explanation: RTSL Action:

Cash Drawer - Device failure. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

Printer Stations - Device offline. Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME only/RESUME label/RESUME RETRY. If the error is associated with a WRITE, you may set the RETRYFLAG on or off. If on, you may specify a value for OVERLAYSTR. DO 80900521 Explanation: RTSL Action: User Response: DO 80900522 Explanation: RTSL Action: Printer Stations - Printer communication problem. Program aborts unless you have an ON ERROR routine in effect. RETRYFLAG or RETRYFLAG and OVERLAY string.

Printer Stations - Printer cover open, line in error. Program aborts unless you have an ON ERROR routine in effect.

User Response: RETRYFLAG may be set on or off. If set on, the OVERLAYSTR may be set to a value. A message should be displayed and then retry. DO 80900525 Explanation: RTSL Action: Printer Stations - Paper path error. Program aborts unless you have an ON ERROR routine in effect.

User Response: RETRYFLAG may be set on or off. If set on, the OVERLAYSTR may be set to a value. A message should be displayed and then retry. DO 80900526 Explanation: Printer Stations - Printer Key error. Key on the printer has been held down while trying to print. RTSL Action: Program aborts unless you have an ON ERROR routine in effect.

User Response: RETRYFLAG may be set on or off. If set on, the OVERLAYSTR may be set to a value. A message should be displayed and then retry. DO 8090052D Explanation: RTSL Action: User Response: Printer stations -- Cover open, print line completed. Program aborts unless you have an ON ASYNC ERROR routine in effect. Display Cover Open message. Do not retry.

340

IBM 4680 BASIC: Language Reference

ERR Code DO

ERRN Code 80980007

Description Explanation: RTSL Action: Serial I/O - Feature card hardware error. Program aborts unless you have an ON ERROR routine in effect.

User Response: If error is associated with a synchronous operation, use RESUME only/RESUME label/RESUME RETRY. If error is associated with a WRITE, you may set the RETRYFLAG on or off. DO 80980005 Explanation: RTSL Action: Serial I/O - Feature card offline. Program aborts unless you have an ON ERROR routine in effect.

User Response: If error is associated with a synchronous operation, use RESUME only/RESUME label/RESUME RETRY. If error is associated with a WRITE, you may set the RETRYFLAG on or off. DO 80A00005 Explanation: RTSL Action: User Response: DO 80A10005 Explanation: RTSL Action: User Response: DO 80A20005 Explanation: RTSL Action: First alphanumeric or operator display - Device offline. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

First video display - Device offline. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

Coin Dispenser - Device offline. Program aborts unless you have an ON ERROR routine in effect.

User Response: ASYNC ERROR - RETRYFLAG should be off. The RTSLs will ignore the RETRYFLAG for this COIN error and will return to the next statement in the application. DO 80A20007 Explanation: RTSL Action: Coin Dispenser - Device failure. Program aborts unless you have an ON ERROR routine in effect.

User Response: ASYNC ERROR - RETRYFLAG should be off. The RTSLs will ignore the RETRYFLAG for this COIN error and will return to the next statement in the application. DO 80A30005 Explanation: RTSL Action: User Response: DO 80A30007 Explanation: RTSL Action: User Response: DO 80A50005 Explanation: RTSL Action: User Response: DO 80A90005 Explanation: RTSL Action: User Response: Scale - Device offline. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

Scale - Device failure. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

MSR - Device offline. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

Shopper display - Device offline. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

Appendix B. Runtime Error Messages

341

ERR Code DO

ERRN Code

Description Second alphanumeric or operator display - Device offline. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

80AA0005 Explanation: RTSL Action:

User Response: DO 80AB0005 Explanation: RTSL Action: User Response: DO 80B0000D Explanation: RTSL Action: User Response: DO 80B0000F Explanation: RTSL Action: User Response: DO 80B00010 Explanation: RTSL Action: User Response: DO 80B00663 Explanation: RTSL Action:

Second video display - Device offline. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

Host Communication - Async read timeout. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY.

Host Communication - Async line could not be opened. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY.

Host Communication - Async hardware error. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY.

Host Communication - Async Host transmission delayed. Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME only/RESUME RETRY/RESUME label. If the error is associated with a WRITE, you may set RETRYFLAG on or off. DO 80B00665 Explanation: RTSL Action: Host Communication - Async DSR not received. Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME only/RESUME RETRY/RESUME label. If the error is associated with a WRITE, you may set RETRYFLAG on or off. DO 80B00666 Explanation: RTSL Action: Host Communication - Async CTS not received. Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME only/RESUME RETRY/RESUME label. If the error is associated with a WRITE, you may set RETRYFLAG on or off. DO 80B00667 Explanation: RTSL Action: User Response: Host Communication - Async RLSD not received. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY.

342

IBM 4680 BASIC: Language Reference

ERR Code DO

ERRN Code

Description Host Communication - Bisync device failure. Program aborts unless you have an ON ERROR routine in effect.

80B10007 Explanation: RTSL Action:

User Response: If the error is associated with a synchronous operation, use RESUME only/RESUME RETRY/RESUME label. If the error is associated with a WRITE, you may set RETRYFLAG on or off. DO 80B1000D Explanation: RTSL Action: User Response: DO 80B1000F Explanation: RTSL Action: User Response: DO 80B10010 Explanation: RTSL Action: Host Communication - Bisync read timeout. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY.

Host Communication - Bisync line could not be opened. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY.

Host Communication - Bisync hardware error. Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME only/RESUME RETRY/RESUME label. If the error is associated with a WRITE, you may set RETRYFLAG on or off. DO 80B2000D Explanation: RTSL Action: User Response: DO Host Communication - SNA read timeout. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY.

80B20615 Explanation: Host Communication - SNA transmission error. Data cannot be sent or received. Session is active from the host. The session must be closed. RTSL Action: Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME only/RESUME RETRY/RESUME label. If the error is associated with a WRITE, you may set RETRYFLAG on or off. If the error is associated with a synchronous operation, use RESUME label. If the error is associated with a WRITE, set RETRYFLAG off. DO 80B305E6 Explanation: RTSL Action: Host Communication - Communications adapter error. Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME only/RESUME RETRY/RESUME label. If the error is associated with a WRITE, you may set RETRYFLAG on or off. DO 80B305EA Explanation: RTSL Action: Host Communication - Adapter hardware error. Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME only/RESUME RETRY/RESUME label. If the error is associated with a WRITE, you may set RETRYFLAG on or off.

Appendix B. Runtime Error Messages

343

ERR Code DO

ERRN Code

Description Host Communications - SDLC read timeout. Program aborts unless you have an ON ERROR routine in effect.

80B40637 Explanation: RTSL Action:

User Response: If the error is associated with a synchronous operation, use RESUME only/RESUME RETRY/RESUME label. If the error is associated with a WRITE, you may set RETRYFLAG on or off. DO 80B40638 Explanation: RTSL Action: Host Communications - SDLC device failure. Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME only/RESUME RETRY/RESUME label. If the error is associated with a WRITE, you may set RETRYFLAG on or off. DO 80B40639 Explanation: RTSL Action: Host Communications - SDLC detected Data Set Ready dropped. Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME only/RESUME RETRY/RESUME label. If the error is associated with a WRITE, you may set RETRYFLAG on or off. DO 80B4063C Explanation: RTSL Action: Host Communications - SDLC detected Clear To Send error. Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME only/RESUME RETRY/RESUME label. If the error is associated with a WRITE, you may set RETRYFLAG on or off. DU 00000016 Explanation: RTSL Action: A DELETE statement specifies a file identification number that is not active. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME only/RESUME label - Modify your source program to ensure that the DELETE statement only applies to a valid (file) I/O session number. DV 80980583 Explanation: RTSL Action: Serial I/O - Device communication error. Program aborts unless you have an ON ERROR routine in effect.

User Response: If error is associated with a synchronous operation, use RESUME only/RESUME label/RESUME RETRY. If error is associated with a WRITE, you may set the RETRYFLAG on or off. DW 80204300 Explanation: The operating system reports that there is no disk or directory space available for the file being written to, and no IF END statement is in effect for the I/O session number. RTSL Action: User Response: DW 808304A8 Explanation: RTSL Action: User Response: DW 80F306CE Explanation: RTSL Action: User Response: Program terminates unless you have an ON ERROR routine in effect. RESUME only/RESUME RETRY/RESUME label

Totals Retention - Data exceeds space available on a write Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME RETRY/RESUME label

Keyed File Services - Keyed file full. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME RETRY/RESUME label

344

IBM 4680 BASIC: Language Reference

ERR Code DZ

ERRN Code

Description Division by zero is attempted. Program terminates unless you have an ON ERROR routine in effect. RESUME label - Do not attempt division by zero.

0000001A Explanation: RTSL Action:

User Response: *E

000000A0 Explanation: Asynchronous error - invalid EVENT MASK. This is an internal failure of the runtime library. RTSL Action: Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Copy the following files onto a diskette: v the executable load module (.286 file that was created with the following linker options: [MAP[ALL],LI,LO] v the symbols file (.SYM file) v the map file (.MAP file) v the shared runtime library (.SRL file), if applicable v the appropriate version of the .L86 file. Contact your service representative when you have gathered the above information. EC 000000AA Explanation: End of file on console input. <ctr> Z was entered from the keyboard for an input statement. RTSL Action: User Response: EF Program terminates unless you have an ON ERROR routine in effect. RESUME label.

0000001C Explanation: (1) Attempt to read past the end-of-file, and no IF END statement is in effect for the I/O session number. (2) No record found in a keyed, random, or direct file. RTSL Action: User Response: Program terminates unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

EF

808304A5 Explanation: RTSL Action:

Totals Retention - Read at EOF. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

User Response: EF 80F306C8 Explanation: RTSL Action: User Response: ER

Keyed File Services. Application tried to delete a record which was not found. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label

0000001E Explanation: Attempt to write a record of length greater than the maximum record size specified in the OPEN or CREATE statement for this file. RTSL Action: User Response: occur. Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program to ensure that this does not

Appendix B. Runtime Error Messages

345

ERR Code *F

ERRN Code 00000078

Description Explanation: Attempt to free a random block in the runtime library. This is an internal failure of the runtime library. RTSL Action: Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Copy the following files onto a diskette: v the executable load module (.286 file that was created with the following linker options: [MAP[ALL],LI,LO] v the symbols file (.SYM file) v the map file (.MAP file) v the shared runtime library (.SRL file), if applicable v the appropriate version of the .L86 file. Contact your service representative when you have gathered the above information. FL 80F00401 Explanation: The filename specified in the CHAIN or LOAD statement in the terminal must be 40 bytes or less. RTSL Action: User Response: correct length. FR 00000020 Explanation: RTSL Action: Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program to specify a filename of the

Attempt to rename a file to a filename that already exists. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME only/RESUME label - Modify your source program to ensure this does not occur. FU 00000022 Explanation: RTSL Action: Attempt to access a file that was not open. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME only/RESUME RETRY/RESUME label - Modify your source program to ensure that all files are opened before attempted access occurs. *H 00000080 Explanation: RTSL Action: Collapsed heap. This is an internal failure of the runtime library. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Copy the following files onto a diskette: v the executable load module (.286 file that was created with the following linker options: [MAP[ALL],LI,LO] v the symbols file (.SYM file) v the map file (.MAP file) v the shared runtime library (.SRL file), if applicable v the appropriate version of the .L86 file. Contact your service representative when you have gathered the above information. HC 80B20602 Explanation: Host Communication - SNA ACTPU received from host session, host session must be closed and restarted. RTSL Action: Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME label. If the error is associated with a WRITE, you must set RETRYFLAG off.

346

IBM 4680 BASIC: Language Reference

ERR Code HC

ERRN Code

Description Host Communication - SNA DACTPU received from host - must close session Program aborts unless you have an ON ERROR routine in effect.

80B20604 Explanation: and link. RTSL Action:

User Response: If the error is associated with a synchronous operation, use RESUME label. If the error is associated with a WRITE, you must set RETRYFLAG off. HC 80B20605 Explanation: Host Communication - SNA ACTLU received from host session must be closed and restarted. RTSL Action: Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME label. If the error is associated with a WRITE, you must set RETRYFLAG off. HC 80B20606 Explanation: be closed. RTSL Action: Host Communication - SNA DACTLU received from host. The session must Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME label. If the error is associated with a WRITE, you must set RETRYFLAG off. HC 80B20609 Explanation: RTSL Action: effect. User Response: HC A negative response was received from the host for a non-negotiable bind. Program terminates unless you have an ON ASYNC ERROR routine in RETRYFLAG may be set on or off.

80B2060A Explanation: Host Communications - The application is trying to send a SNA request to the host system while it has data from the host system available to be read. The write request will not be processed. RTSL Action: User Response: Program aborts unless you have an ON ASYNC ERROR routine in effect. Set RETRYFLAG off.

HC

80B20611 Explanation: RTSL Action:

Host Communication - SNA UNBIND request received. Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME label. If the error is associated with a WRITE, you must set RETRYFLAG off. HC 80B20614 Explanation: INIT_SELF. RTSL Action: Host Communications - SNA driver received a negative response to an Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME label. If the error is associated with a WRITE, you must set RETRYFLAG off. HC 80B20619 Explanation: be received. RTSL Action: Host Communication - SNA CLOSE is now the only valid command that can Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME label. If the error is associated with a WRITE, you must set RETRYFLAG off.

Appendix B. Runtime Error Messages

347

ERR Code HC

ERRN Code

Description

80B20621 Explanation: Host Communications - The number of TTDs specified in the BSC line configuration has been exceeded. (SNA services using BSC protocol). RTSL Action: Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME label. If the error is associated with a WRITE, you must set RETRYFLAG off. HC 80B20622 Explanation: Host Communications - The number of WACKs specified in the BSC line configuration has been exceeded. (SNA services using BSC protocol). RTSL Action: Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME label. If the error is associated with a WRITE, you must set RETRYFLAG off. HC 80B20623 Explanation: Host Communications - The number of NACKs specified in the BSC line configuration has been exceeded. (SNA services using BSC protocol). RTSL Action: Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME label. If the error is associated with a WRITE, you must set RETRYFLAG off. HC 80B20624 Explanation: Host Communications - A disconnect command was received from the host and communications are terminated. (SNA services using BSC protocol). RTSL Action: Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME label. If the error is associated with a WRITE, you must set RETRYFLAG off. HC 80B20625 Explanation: Host Communications - A data format control byte error was detected. (SNA services using BSC protocol). RTSL Action: Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME label. If the error is associated with a WRITE, you must set RETRYFLAG off. HC 80B20626 Explanation: Host Communications - No data has been sent or received over the BSC line for a configuration specified period of time. The line is considered inoperative. (SNA services using BSC protocol). RTSL Action: Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME label. If the error is associated with a WRITE, you must set RETRYFLAG off. HC 80B20627 Explanation: Host Communications - General BSC error has been detected. (SNA services using BSC protocol). RTSL Action: Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME label. If the error is associated with a WRITE, you must set RETRYFLAG off. HC 80B20628 Explanation: Host Communications - An abort was received from the host system. (SNA services using BSC protocol). RTSL Action: Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME label. If the error is associated with a WRITE, you must set RETRYFLAG off.

348

IBM 4680 BASIC: Language Reference

ERR Code HC

ERRN Code

Description

80B20629 Explanation: Host Communications - Text overflowed buffer - longer than configured block size. (SNA services using BSC protocol). RTSL Action: Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME label. If the error is associated with a WRITE, you must set RETRYFLAG off. HC 80B40632 Explanation: Host Communications - A disconnect command was received from the host by the SDLC driver. RTSL Action: Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME label. If the error is associated with a WRITE, you must set RETRYFLAG off. HC 80B40635 Explanation: RTSL Action: Host Communications - A duplicate read has been issued to the SDLC driver. Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME label. If the error is associated with a WRITE, you must set RETRYFLAG off. HC 80B4063A Explanation: Host Communications - SDLC driver received an invalid record size from the host or the application passed more than 515 bytes of data to the driver. RTSL Action: Program aborts unless you have an ON ERROR routine in effect.

User Response: If the error is associated with a synchronous operation, use RESUME label. If the error is associated with a WRITE, you must set RETRYFLAG off. *I variable Explanation: RTSL Action: A device or communications driver returned an unexpected error code. Program aborts unless you have an ON ERROR routine in effect.

User Response: RESUME only/RESUME label/RESUME RETRY. Use the ERRN function to determine the error code. Copy the following files onto a diskette: v the executable load module (.286 file that was created with the following linker options: [MAP[ALL],LI,LO] v the symbols file (.SYM file) v the map file (.MAP file) v the shared runtime library (.SRL file), if applicable v the appropriate version of the .L86 file. Contact your service representative when you have gathered the above information. IA 00000040 Explanation: A format string in a WRITE FORM statement contains a repeat count before the format character A. A repeat count is not allowed before A. RTSL Action: User Response: IC 00000026 Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program to correct the format string.

Explanation: The format string of a READ FORM or WRITE FORM statement contains an invalid format character. The allowed characters are PIC(), I, R, T, C, and A. RTSL Action: User Response: Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program to correct the format string.

Appendix B. Runtime Error Messages

349

ERR Code ID

ERRN Code 80850008

Description Explanation: RTSL Action: Tone - Command/Data invalid. Program aborts unless you have an ON ERROR routine in effect.

User Response: RESUME label. The application programmer should change the application to send the correct command/data. ID 80860008 Explanation: RTSL Action: User Response: ID 80900052 Explanation: RTSL Action: User Response: to the printer. ID 8090052A Explanation: RTSL Action: User Response: ID 8090052B Explanation: RTSL Action: User Response: ID 80980008 Explanation: RTSL Action: User Response: ID 80A10008 Explanation: RTSL Action: User Response: ID 80A20008 Explanation: RTSL Action: Cash Drawer - Command/Data invalid. Program aborts unless you have an ON ERROR routine in effect. RESUME label

Illegal data passed to printer driver. Program aborts unless you have an ON ERROR routine in effect. Display error and issue RESUME. Correct application to pass proper data

Document Insert Station - Invalid DI mode setting. Program aborts unless you have an ON ERROR routine in effect. RESUME label

Terminal Printer Stations - Invalid data specified in OVERLAYSTR. Program aborts unless you have an ON ASYNC ERROR routine in effect. ASYNC ERROR - RETRYFLAG should be set off. Correct the application.

Serial I/O - Invalid command or data specified on OPEN SERIAL statement. Program aborts unless you have an ON ERROR routine in effect. RESUME label/RESUME only.

VIDEO DISPLAY -- Invalid bit combination in PUTLONG. Program terminates unless you have an ON ERROR routine in effect. Display error and resume. Correct the application program.

Coin Dispenser - Invalid command or data. Program aborts unless you have an ON ERROR routine in effect.

User Response: ASYNC ERROR - RETRYFLAG should be off. The RTSLs will ignore the RETRYFLAG for this error and will return to the next statement in the application. Application programmer should correct program. ID 80B10008 Explanation: Host Communication - Bisync invalid command, invalid write control byte, or message longer than configured limit. RTSL Action: User Response: ID 80B10641 Explanation: a write. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY.

Host Communications - BSC application must issue a read before it can issue Program aborts unless you have an ON ERROR routine in effect. Resume RETRY/Resume only/Resume label

350

IBM 4680 BASIC: Language Reference

ERR Code ID

ERRN Code

Description

80B10642 Explanation: Host Communications - BSC application must write the rest of a partially written message. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. Resume RETRY/Resume only/Resume label

ID

80B40631 Explanation: RTSL Action:

Host Communications - SDLC driver received invalid data. Program aborts unless you have an ON ERROR routine in effect. Resume RETRY/Resume only/Resume label

User Response: IE 00000028

Explanation: The format string of a READ FORM or WRITE FORM statement does not have a closing double quote. RTSL Action: User Response: Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program to correct the format string.

IF

8020400F Explanation: Filename in an OPEN or CREATE statement, or with the RENAME function, is invalid for the operating system. RTSL Action: User Response: for file names. Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program to use only valid characters

IH

00000094

Explanation: RTSL Action:

Illegal characters encountered in INPUT, READ #, or VAL statement. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME only/RESUME label/RESUME RETRY - Ensure that data types in INPUT and READ # statements match those entered or read by the program. For the VAL function, ensure that the string contains only ASCII digits, an optional preceding plus or minus sign, and an optional decimal point symbol. II 0000002C Explanation: The format string for a WRITE FORM statement contains the format specification PIC( with no closing parenthesis. RTSL Action: User Response: IN 000000AE Explanation: RTSL Action: Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program to correct the format string.

Error on input. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME only/RESUME RETRY/RESUME label Note: RESUME RETRY does not display the prompt again. The operator needs to enter the date again. IO 00000096 Explanation: Integer overflow detected in an INPUT or READ # statement or in a 4-byte integer assignment statement. RTSL Action: User Response: IP 0000002E Explanation: RTSL Action: User Response: Program terminates unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

Invalid picture string encountered in a WRITE FORM statement. Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program to correct the format string.

Appendix B. Runtime Error Messages

351

ERR Code IR

ERRN Code 00000030

Description Explanation: statement. RTSL Action: A record number of zero is specified in a READ #, PRINT # or WRITE # Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to ensure that all record numbers are in the correct range. IS 00000032 Explanation: RTSL Action: Invalid cursor position specified. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to ensure the cursor position is between 1 and 255. IT 00000406 Explanation: Invalid repeat count specified before T in the format string of a WRITE FORM statement. RTSL Action: Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to correct the format string by removing the repeat count. IV 00000036 Explanation: Invalid Integer specification found in the format string of a WRITE FORM or READ FORM statement. RTSL Action: Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to correct the format string by specifying either I1, I2, or I4. IX 00000038 Explanation: While processing a WRITE FORM statement, a real specification was found, yet the corresponding variable or expression was of type integer. RTSL Action: Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to ensure that the format string matches the variable being written. KF 80F30004 Explanation: KEYED FILE SERVICES. The record length of the file doesnt match the record length of the session number. RTSL Action: Program aborts unless you have an ON ERROR routine in effect.

User Response: RESUME only/RESUME label - User should correct the record length of the file or the record length in the OPEN statement. KF 80F306C1 Explanation: Keyed File Services - Invalid record length specified. The file was opened with a record length different than the record length used to create the file. RTSL Action: User Response: KF 80F306C2 Explanation: RTSL Action: User Response: KF Program aborts unless you have an ON ERROR routine in effect. RESUME label

Keyed File Services - Invalid KEY length specified. Program aborts unless you have an ON ERROR routine in effect. RESUME label

80F306C4 Explanation: Keyed File Services - Invalid randomizing divisor specified in CREATE POSFILE. Specified as equal 0 or greater than the number of sectors allocated to file. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME label

352

IBM 4680 BASIC: Language Reference

ERR Code KF

ERRN Code

Description

80F306C4 Explanation: Keyed File Services - Invalid chain exists because an I/O error occurred during keyed record chain operation. NOTE: This return code is given for ALL subsequent keyed file requests. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME label

KF

80F306C7 Explanation: Keyed File Services - Invalid attributes on an OPEN to Keyed file and sector zero can not be validated. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME label

KF

80F306C9 Explanation: Autolock. RTSL Action:

Invalid key specified. Write Autolock used different key than the Read Program aborts unless you have an ON ERROR routine in effect. RESUME label

User Response: KF

80F306CA Explanation: Keyed File Services - Invalid command sequence. Write Autolock used different key than the Read Autolock. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME label

KF

80F306CD Explanation: RTSL Action:

Keyed File Services - Null KEY specified. Program aborts unless you have an ON ERROR routine in effect. RESUME label

User Response: KF 80F306CF Explanation: RTSL Action: User Response: KF 80F306D0 Explanation: RTSL Action: User Response: KF 80F306D3 Explanation: RTSL Action: User Response: KF

Keyed File Services - Keyed file Access rights violation. Program aborts unless you have an ON ERROR routine in effect. RESUME label

Keyed File Services - Chain threshold exceeded. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME RETRY/RESUME label.

Keyed File Services - Sector zero of file is zero. An error occurred on creation. Program aborts unless you have an ON ERROR routine in effect. RESUME label. Erase the file (there is not data in it), and create a new one.

80F306D5 Explanation: Keyed File Services - Invalid write to sector 0 of a keyed file. (Not in Messages, Symptoms...) RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME label - Modify your program to correct the error.

LD

000003FC Explanation: RTSL Action:

Neither ISTBL, FMTTBL, nor MODTBL was specified in the LOAD statement. Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program to ensure that at least one is

User Response: specified.

Appendix B. Runtime Error Messages

353

ERR Code LE

ERRN Code

Description An attempt was made to lock a device that cannot be locked. Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program to avoid attempts to lock

000003F6 Explanation: RTSL Action:

User Response: this device. LI 80900523 Explanation: Station. RTSL Action:

Printer Stations - WRITE LOGO not supported on the Summary Journal Program aborts unless you have an ON ASYNC ERROR routine in effect.

User Response: Specify RETRYFLG off. Change the application so it does not attempt to the Summary Journal Station for LOGO printing. LN 80624440 Explanation: RTSL Action: User Response: LN Local area network request timed out. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

80F306E0 Explanation: Local Area Net - Tried to lock a Distributed file. A distributed file must be used unlocked or read only. RTSL Action: Program aborts unless you have an ON ERRR routine in effect.

User Response: RESUME label. Correct the application. a Distributed file must be used unlocked or read only. LN 80F306E1 Explanation: Local Area Net - Tried to OPEN an IMAGE copy file with write capability. An IMAGE copy file must be opened nowrite, nodel. Use master (ADXLXAAN:: or ADXLXACN::). RTSL Action: Program aborts unless you have an ON ERROR routine in effect.

User Response: RESUME label. Correct the application. An IMAGE copy file can only be opened with nowrite and nodel. LN 80F306E3 Explanation: Local Area Net. Tried to create a distributed file on an invalid node (not on the Master or File Server store controller). RTSL Action: Program aborts unless you have an ON ERROR routine in effect.

User Response: RESUME label. A Mirrored or Compound file can only be created on a Master or File Server store controller. LN 80F306E5 Explanation: Local Area Net. Tried to open a Distribute On Close file on a node other than the Master or File Server store controller RTSL Action: Program aborts unless you have an ON ERROR routine in effect.

User Response: RESUME label. Correct the application to open Distribute On Close files on the Master store controller (ADXLXAAN::) or the File Server store controller (ADXLXACN::) only. ME variable Explanation: The operating system reports an error during an attempt to create or extend a file or to create a subdirectory. RTSL Action: User Response: Program terminates unless you have an ON ERROR routine in effect. RESUME only/RESUME RETRY/RESUME label

354

IBM 4680 BASIC: Language Reference

ERR Code ML

ERRN Code

Description I/O Processor - Input State Table not loaded. Program aborts unless you have an ON ERROR routine in effect.

808404CB Explanation: RTSL Action:

User Response: RESUME label. Change the application to load an Input State Table before opening the I/O processor. MP 0000003E Explanation: RTSL Action: The third parameter in a MATCH function is zero or negative. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to ensure that the MATCH function receives the correct parameters. NB 80F00403 Explanation: RTSL Action: User Response: NB 80F00407 Explanation: RTSL Action: User Response: NC 00000040 Application Loader - Requested I/O Processor table was not found. Program aborts unless you have an ON ERROR routine in effect. RESUME label

Application Loader - Invalid table requested on LOAD statement. Program aborts unless you have an ON ERROR routine in effect. RESUME label

Explanation: In a WRITE FORM statement, the format string specified a C without a <value> following it. RTSL Action: User Response: Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program to correct the format string.

ND

00000034

Explanation: RTSL Action:

Could not delete the file. Program terminates unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

User Response: NE 00000042 Explanation: RTSL Action: User Response: NF 00000044

A negative value is specified for the operand to the left of the power operator. Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program to correct the error

Explanation: An I/O session number is less than 1 or greater than 99.RTSL Action: Program terminates unless you have an ON ERROR routine in effect. User Response: RESUME label - Modify your source program to ensure that all file identification numbers are in the proper range.

NK

80F00402 Explanation: You cannot CHAIN KEEP to an application and have it CHAIN KEEP to another application. RTSL Action: Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Change one of CHAIN KEEP statements to a simple CHAIN statement. NL variable Explanation: RTSL Action: User Response: An error occurred while closing a file. The file was closed. Program terminates unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

Appendix B. Runtime Error Messages

355

ERR Code NN

ERRN Code 00000046

Description Explanation: An attempt to print a numeric expression with a WRITE FORM or PRINT USING statement fails because there is no numeric field in the string. RTSL Action: Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to correct the format string by adding one or more numeric fields. NP variable Explanation: CHAIN. RTSL Action: A USE statement was encountered, but no parameters were passed on the Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Either modify the chaining program to pass parameters or remove the USE statement from the program being chained to. NR variable Explanation: The operating system returned failure on an attempt to read from a device or file. Check the ERRN value to find out why. RTSL Action: User Response: NS Program terminates unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

0000004A Explanation: An attempt to print a string expression with a PRINT USING statement fails because there is no string field in the USING string. RTSL Action: Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to correct the format string by adding one or more string fields. NT 0000004C Explanation: In a WRITE FORM statement, the format string specified a T without a <value> following it. RTSL Action: User Response: NV 00000402 Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program to correct the format string.

Explanation: In a WRITE FORM statement, the format string specified an A without a <value> following it. RTSL Action: User Response: Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program to correct the format string.

NX

0000004E Explanation: In a WRITE FORM format string, a C specification was found, yet the corresponding variable or expression was not of type string. RTSL Action: Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to ensure that the format string matches the variables to be written. OD 00000050 Explanation: A READ statement is executed, but there are no DATA statements in the program, or all data items in all the DATA statements have been read. RTSL Action: User Response: statements. OE 00000052 Explanation: RTSL Action: User Response: Program terminates unless you have an ON ERROR routine in effect. RESUME only/RESUME label - Modify your logic or add DATA

A SIZE was attempted on a non-existent file. Program terminates unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

356

IBM 4680 BASIC: Language Reference

ERR Code OE

ERRN Code 80104010

Description Explanation: Attempted to OPEN a pipe that does not exist and there is no IF END statement in effect. RTSL Action: User Response: Program terminates unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

OE

8020400C Explanation: Attempted to OPEN a file in LOCKED mode, and the file is already open by another program. RTSL Action: User Response: Program terminates unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

OE

80204010

Explanation: 1) Attempted to OPEN a file that does not exist, and for which no IF END statement is in effect. 2) The file specified in a SIZE function could not be found (ERRF% = 0). RTSL Action: User Response: Program terminates unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

OE

806043A1 Explanation: RTSL Action:

Local area network cannot connect to node. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

User Response: OE 80624440 Explanation: RTSL Action: User Response: OE 808404CC Explanation: RTSL Action: User Response: OE 80980009 Explanation: RTSL Action: User Response: OE 80A20009 Explanation: RTSL Action: User Response: OE 80A30009 Explanation: RTSL Action: User Response: OE 80A50009 Explanation: RTSL Action: User Response:

Local area network request timed out. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

I/O Processor - I/O Processor has already been opened by the program. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

Serial I/O - Feature card not attached. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

Coin Dispenser - Feature card not attached. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

Scale - Feature Card not attached. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

MSR - Keyboard not attached. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

Appendix B. Runtime Error Messages

357

ERR Code OE

ERRN Code

Description MSR - Device not attached to keyboard. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

80A5000A Explanation: RTSL Action:

User Response: DO 80A50016 Explanation: RTSL Action: User Response: OE

MSR - MSR has already been opened by the application. Program aborts unless you have an ON ERROR routine in effect. RESUME RETRY/RESUME only/RESUME label

80B305E4 Explanation: Host communication - Host communication OPEN error. SNA driver is in the process of shutdown because of hardware error, link error, or normal shutdown from host. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME RETRY/RESUME label

OE

80B00013 Explanation: Host Communications - ASYNC driver - out of system event flags. Cannot complete open. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME RETRY/RESUME only/RESUME label

OE

80B10009 Explanation: RTSL Action:

Host Communications - BSC driver does not support autodial. Program aborts unless you have an ON ERROR routine in effect. Resume label

User Response: OE

80B10013 Explanation: Host Communications - BSC driver - out of system event flags. Cannot complete open. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. Resume RETRY/Resume only/Resume label

OE

80B10016 Explanation: RTSL Action:

Host Communications - BSC driver - application already has BSC driver open. Program aborts unless you have an ON ERROR routine in effect. Resume label/RESUME only/RESUME RETRY

User Response: OE

80B10643 Explanation: Host Communications - Attempt to start a BSC link timed out while waiting on phone connection. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. Resume RETRY/Resume only/Resume label

OE

80B10644 Explanation: Host Communications - Attempt to start a BSC link failed because initial ID exchange failed. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. Resume RETRY/Resume only/Resume label

OE

80B205EF Explanation: Host Communication - There were not enough system flags available to install the SNA driver. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME RETRY/RESUME only/RESUME label.

358

IBM 4680 BASIC: Language Reference

ERR Code OE

ERRN Code

Description

80B30002 Explanation: Host Communication - OPEN failure because of an access conflict or an outstanding CLOSE request. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

OE

80B305E5 Explanation: RTSL Action:

Host Communication - Adapter not found. Program aborts unless you have an ON ERROR routine in effect. RESUME label

User Response: OE 80B305E7 Explanation: RTSL Action: User Response: OE 80B305ED Explanation: RTSL Action: User Response: OE 80B305EE Explanation: RTSL Action: User Response: OE 80B305EF Explanation: SNA driver. RTSL Action: User Response: OE

Host Communication - Subdriver install error. Program aborts unless you have an ON ERROR routine in effect. RESUME label

Host Communications - Interrupt level already in use. Program aborts unless you have an ON ERROR routine in effect. Resume RETRY/Resume only/Resume label

Host Communications - Communications adapter already in use. Program aborts unless you have an ON ERROR routine in effect. Resume RETRY/Resume only/Resume label

Host Communications - Not enough system flags were available to install the Program aborts unless you have an ON ERROR routine in effect. Resume RETRY/Resume only/Resume label

80B40633 Explanation: Host Communications - SDLC driver - out of system event flags. Cannot complete open. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. Resume RETRY/Resume only/Resume label

OE

80B40634 Explanation: Host Communications - SDLC driver - Invalid interrupt specified. Cannot complete open. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. Resume RETRY/Resume only/Resume label

OE

80B40636 Explanation: RTSL Action:

Host Communications - SDLC line could not be opened. Program aborts unless you have an ON ERROR routine in effect. Resume RETRY/Resume only/Resume label

User Response: OE 80F306D4 Explanation: RTSL Action:

Sector zero of a keyed file is zero. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME only/RESUME label/ Note: The file should be deleted and/or recreated.

Appendix B. Runtime Error Messages

359

ERR Code OF

ERRN Code 00000054

Description Explanation: RTSL Action: User Response: An overflow occurs during a real arithmetic calculation. Program terminates unless you have an ON ERROR routine in effect. RESUME label

OI

00000056

Explanation: RTSL Action:

A 4-byte integer overflow. Program terminates unless you have an ON ERROR routine in effect. RESUME only/RESUME label

User Response: OM 00000058 Explanation: RTSL Action:

The program runs out of dynamically allocated memory during execution. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label (and free up string or array space). If you have linked your application program with a data area less than 64K (terminal medium model only), increase the size of the data area. OM 80600000 Explanation: RTSL Action: User Response: OM 80840000 Explanation: RTSL Action: User Response: OM 80A10000 Explanation: RTSL Action: User Response: OM 80B00000 Explanation: RTSL Action: User Response: OM 80B10000 Explanation: RTSL Action: User Response: OM Local area network out of memory. Program aborts unless you have an ON ERROR routine in effect. RESUME label.

I/O Processor - Insufficient memory for the input buffers. Program aborts unless you have an ON ERROR routine in effect. RESUME label

Video display driver out of memory. Program aborts unless you have an ON ERROR routine in effect. RESUME label.

Host Communications - ASYNC driver - out of memory. Program aborts unless you have an ON ERROR routine in effect. Resume label

Host Communications - BSC driver out of memory. Program aborts unless you have an ON ERROR routine in effect. Resume label

80B30000 Explanation: Host Communication - SNA not enough memory available for SNA link or session to be started. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME label

OM

80F00404 Explanation: RTSL Action:

Application Loader - Insufficient memory to load I/O Processor tables. Program aborts unless you have an ON ERROR routine in effect. RESUME label

User Response:

360

IBM 4680 BASIC: Language Reference

ERR Code OM

ERRN Code

Description Application Loader - Insufficient memory to load program on CHAIN. Program aborts unless you have an ON ERROR routine in effect. RESUME label

80F00405 Explanation: RTSL Action:

User Response: OM 80F10000 Explanation: RTSL Action: User Response: OM 80F30000 Explanation: buffers. RTSL Action: User Response: OP 000003EA Explanation: RTSL Action:

Terminal File Services - Insufficient memory for input buffers. Program aborts unless you have an ON ERROR routine in effect. RESUME label

Keyed File Services - Insufficient memory in the controller for the input Program aborts unless you have an ON ERROR routine in effect. RESUME label

An attempt was made to pass parameters while chaining to an overlay. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to eliminate the attempt to pass parameters to an overlay. Use COMMON variables instead. OV 0000005A Explanation: A format string in a READ FORM or WRITE FORM statement contains a format specification value greater than 32767. RTSL Action: User Response: PA Program terminates unless you have an ON ERROR routine in effect. RESUME only/RESUME label

80B20616 Explanation: Host Communication - SNA outbound pacing queue is full. Wait for buffer to become available. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME label

PC

0000008E Explanation: RTSL Action:

Invalid punctuation character has been encountered in OPTION statement. Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program to correct the error.

User Response: PR

80C30701 Explanation: Pipe Routing Services - requested read amount exceeded amount of data available. Pipe has been purged. RTSL Action: Program aborts unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify program to ensure that the amount of data which is written to the pipe by the controller application is the same as the amount of data expected by the terminal application. PR 80C30702 Explanation: maximum Pipe Routing Services - requested read/write amount exceeds the 120 byte RESUME label - Modify program to request read/write of no more than

User Response: 120 bytes.

Appendix B. Runtime Error Messages

361

ERR Code PU

ERRN Code

Description PRINT USING is in progress. Program terminates unless you have an ON ERROR routine in effect.

0000005C Explanation: RTSL Action:

User Response: RESUME label - Copy the following files onto a diskette: v the executable load module (.286 file that was created with the following linker options: [MAP[ALL],LI,LO] v the symbols file (.SYM file) v the map file (.MAP file) v the shared runtime library (.SRL file), if applicable v the appropriate version of the .L86 file. Contact your service representative when you have gathered the above information. QS 80B2060B Explanation: on the link. RTSL Action: User Response: RB Host Communication - SNA QUIESCE not specified and sessions are active Program aborts unless you have an ON ERROR routine in effect. RESUME label

0000005E Explanation: Random access is attempted to a file activated with the BUFF option specifying more than one buffer. RTSL Action: User Response: Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program to specify only one buffer.

RC

0000008C Explanation: While reading a string with a READ FORM statement, a C specifier was not found in the format string. RTSL Action: Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to ensure that the format string matches the variables being read. RD 00000092 Explanation: exist. RTSL Action: User Response: RE 00000060 Explanation: RTSL Action: The directory specified in the RMDIR statement is not empty or does not Program terminates unless you have an ON ERROR routine in effect. RESUME label

Attempt to read past the end of a record in a random file. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME only/RESUME label - Modify your program to ensure the number of variables specified on the READ statement matches the number of variables in the record. RF 0000008A Explanation: While reading a real number with a READ FORM statement, an R specifier was not found in the format string. RTSL Action: Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to ensure that the format string matches the variables being read.

362

IBM 4680 BASIC: Language Reference

ERR Code RI

ERRN Code 00000088

Description Explanation: While reading an integer with a READ FORM statement, an I specifier was not found in the format string. RTSL Action: Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to ensure that the format string matches the variables being read. RL 0000009A Explanation: RTSL Action: User Response: RN The program tried to lock or unlock a record in a sequential file. Program terminates unless you have an ON ERROR routine in effect. RESUME label - Remove statement or change file type.

0000007A Explanation: An attempt was made to execute a RESUME only statement (RESUME without a label specification), but the last error was not resumable. RTSL Action: Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to ensure that the RESUME only statement can only be executed for resumable errors. RP 80F10683 Explanation: Invalid request. One of the following: v Filename exceeds 25 bytes v Attempting to read from a keyed file with a bad key length or record length v Issuing a matrix write on anything other than a sequential file v Unformatted read from a remote pipe. RTSL Action: User Response: RP 80F10684 Explanation: RTSL Action: User Response: RS 80B3000C Explanation: RTSL Action: User Response: RU 00000062 Explanation: RTSL Action: Program aborts unless you have an ON ERROR routine in effect. RESUME label

Terminal File Services - Maximum number of files exceeded. Program aborts unless you have an ON ERROR routine in effect. RESUME label

Host Communication - RESUME not supported for specified operation. Program aborts unless you have an ON ERROR routine in effect. RESUME label

A random READ or PRINT is attempted to a sequential file. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to ensure that the file type is correct, or eliminate the random I/O. RX 00000064 Explanation: In a WRITE FORM format string, an integer specification was found, yet the corresponding variable or expression was of type real. RTSL Action: Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to ensure that the format string matches the variables to be written.

Appendix B. Runtime Error Messages

363

ERR Code *S

ERRN Code

Description Invalid DS value. This is an internal failure of the runtime library. Program terminates unless you have an ON ERROR routine in effect.

000000A6 Explanation: RTSL Action:

User Response: RESUME label - Copy the following files onto a diskette: v The executable load module (.286 file that was created with the following linker options: [MAP[ALL],LI,LO] v The symbols file (.SYM file) v The map file (.MAP file) v The shared runtime library (.SRL file), if applicable v The appropriate version of the .L86 file Contact your service representative when you have gathered the above information. SE 808404C2 Explanation: RTSL Action: User Response: SL 00000066 Explanation: RTSL Action: I/O Processor - An invalid State was specified in an UNLOCKDEV statement. Program aborts unless you have an ON ERROR routine in effect. RESUME label.

A concatenation operation results in a string greater than 64K bytes. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to ensure that the strings being combined are small enough. SM 00000068 Explanation: The in translate string and the out translate string parameters of the TRANSLATE$ function do not match in length. RTSL Action: User Response: SN 0000006A Explanation: RTSL Action: Program terminates unless you have an ON ERROR routine in effect. RESUME label

Null format string found in a WRITE FORM or READ FORM statement. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to ensure that a valid string is always provided. SS 0000006E Explanation: The second parameter of a MID$ function is zero or negative, or the last parameter of a LEFT$, RIGHT$, or MID$ is negative, or the first parameter of STRING$ is negative. RTSL Action: User Response: value. ST 80B2061A Explanation: RTSL Action: User Response: SU 0000007E Explanation: RTSL Action: Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program to correct the parameter

Host Communication - SNA SENSE status is available. Program aborts unless you have an ON ERROR routine in effect. RESUME only/RESUME label/RESUME RETRY

Array subscript is out of bounds. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to ensure that array references are always within the proper bounds.

364

IBM 4680 BASIC: Language Reference

ERR Code TD

ERRN Code

Description Too many devices were specified in a WAIT statement. Program terminates unless you have an ON ERROR routine in effect. RESUME label - Change the WAIT statement to specify fewer I/O session

000000A4 Explanation: RTSL Action:

User Response: numbers. TF

80F206A1 Explanation: Shared I/O Access Method - A pipe or file CREATE or OPEN request is received from a terminal and the SIOAM file number/terminal address table is full. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME label

TF

80F206A2 Explanation: Shared I/O Access Method - A CREATE or OPEN request was received for a file to be accessed as read only shared, and the SIOAM R/O table is full. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME label

TF

80F206A3 Explanation: Shared I/O Access Method - A SPECIAL read/ wait request is received for a pipe and the SIOAM file number/event number table is full. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME label

TF

80F206A4 Explanation: Shared I/O Access Method - The first application file or pipe request is received from a terminal and the SIOAM sequence table is full. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME label

TI

00000400

Explanation: An attempt has been made to use the lines-to-advance specification for a device other than CR, SJ, and DI. RTSL Action: Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to ensure that the lines-to-advance specification is used only for appropriate devices. TL 00000070 Explanation: RTSL Action: A TAB statement contains a value less than one. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to ensure that the argument to the TAB function is 1 or greater. TO 80F10681 Explanation: RTSL Action: User Response: TR 808304A1 Explanation: RTSL Action: User Response: Terminal File Services - Terminal offline. Program aborts unless you have an ON ERROR routine in effect. RESUME label/RESUME RETRY/RESUME only

Totals Retention - Too much data to read or write. Program aborts unless you have an ON ERROR routine in effect. RESUME label

Appendix B. Runtime Error Messages

365

ERR Code TR

ERRN Code

Description Totals Retention - Invalid offset specified. Program aborts unless you have an ON ERROR routine in effect. RESUME label

808304A2 Explanation: RTSL Action:

User Response: TR 808304A3 Explanation: RTSL Action: User Response: TR 808304A7 Explanation: RTSL Action: User Response: UE 0000003F Explanation: RTSL Action: User Response: UN 00000072

Totals Retention - Invalid record length specified on Direct Access Program aborts unless you have an ON ERROR routine in effect. RESUME label

Totals Retention - Pointer outside of authorized range Program aborts unless you have an ON ERROR routine in effect. RESUME label

An attempt was made to unlock a device that cannot be unlocked. Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program to correct the error.

Explanation: A PRINT USING statement is executed with a null edit string, or a backslash escape character is the last character in a edit string. RTSL Action: User Response: Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program to correct the error

*W

00000098

Explanation: RTSL Action:

The form string in a WRITE FORM statement is a null string. Program terminates unless you have an ON ERROR routine in effect. RESUME label - Change the format string.

User Response: WC 00000084

Explanation: While writing a numeric field with a WRITE FORM statement, a C specifier was encountered in the format string. RTSL Action: Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to ensure that the format string matches the variables being written WE 000003F4 Explanation: RTSL Action: User Response: WF 00000086 An attempt was made to wait on a device that cannot be waited on. Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program to correct the error.

Explanation: While writing an integer with a WRITE FORM statement, an R specifier was encountered in a format string. RTSL Action: Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to ensure that the format string matches the variables being written. WH 80F306CB Explanation: Keyed File Services - WRITE HOLD sequence error. Do not use WRITE HOLD to write to files which exist on two different nodes. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME label

366

IBM 4680 BASIC: Language Reference

ERR Code WI

ERRN Code 00000082

Description Explanation: While writing a character with a WRITE FORM statement, an I or R specifier was encountered in the format string. RTSL Action: Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to ensure that the format string matches the variables being written. WM 80F10682 Explanation: RTSL Action: User Response: WM Terminal File Services - Invalid file type for WRITE MATRIX. Program aborts unless you have an ON ERROR routine in effect. RESUME label

80F206A8 Explanation: Shared I/O Access Method - WRITE MATRIX sequence error. The first segment of the WRITE MATRIX was never received. RTSL Action: Program aborts unless you have an ON ERROR routine in effect.

User Response: RESUME only/RESUME RETRY/RESUME label. The WRITE MATRIX did not occur. Try the operation again. WP 00000074 Explanation: Nested I/O statements are not allowed. You cannot issue an I/O statement or function within an I/O statement or function. RTSL Action: Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label. Change your application program so that the I/O functions or statements your application issues are done serially (the first completes before the second). WR 00000076 Explanation: An attempt was made to write to a sequential file after it was read, but before it was read to the end-of-file. RTSL Action: User Response: WT variable Program terminates unless you have an ON ERROR routine in effect. RESUME RETRY/RESUME label

Explanation: An error occurred in an attempt to write to a device or file. This error will be returned to the application if the controller printer is off and an application tries to print on that printer. RTSL Action: Program terminates unless you have an ON ERROR routine in effect. Check the ERRN value to find out why. User Response: RESUME only/RESUME RETRY/RESUME label

XA

00000408

Explanation: RTSL Action:

Invalid access keywords were found on a device open. Program terminates unless you have an ON ERROR routine in effect. RESUME label - Do not specify any access keywords when opening a

User Response: device. XB

0000040A Explanation: The application specified the APPEND reserved word on an OPEN statement to a non-sequential file. RTSL Action: Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to either eliminate the APPEND option, or change the type of file.

Appendix B. Runtime Error Messages

367

ERR Code XC

ERRN Code

Description

0000040C Explanation: An attempt was made to read or write to a direct or keyed file without a FORM (format string) type of I/O statement. RTSL Action: User Response: Program terminates unless you have an ON ERROR routine in effect. RESUME label

XD

0000040E Explanation: An attempt was made to write to an existing sequential file without an APPEND specification. RTSL Action: User Response: Program terminates unless you have an ON ERROR routine in effect. RESUME label

XE

00000410

Explanation: The number of a serial device is less than 1 or greater than 4 in an OPEN SERIAL statement. RTSL Action: User Response: Program terminates unless you have an ON ERROR routine in effect. RESUME label -

XF

00000412

Explanation: RTSL Action:

The statement is not allowed for the specified device. Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program by removing the invalid

User Response: statement. XG 00000414 Explanation: RTSL Action: User Response: XH 00000416 Explanation: RTSL Action:

PUTLONG and GETLONG are not allowed for files in the terminal. Program terminates unless you have an ON ERROR routine in effect. RESUME label - Modify your source program to correct the error.

Did not read a full record. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME only/RESUME RETRY/RESUME label - Modify your source program to ensure that the format string matches the fields in the record, or that the number and type of variables specified on the READ statement matches the data in the record. XI 00000418 Explanation: RTSL Action: Length of FORM is not equal to record length. Program terminates unless you have an ON ERROR routine in effect.

User Response: RESUME label - Modify your source program to ensure that the length represented by the format string matches the record length specified on the OPEN or CREATE statements. XJ 0000041A Explanation: RTSL Action: User Response: XK 0000041C Explanation: RTSL Action: User Response: Attempt to delete a device. Program terminates unless you have an ON ERROR routine in effect. RESUME label - You can delete files, not devices.

Attempt to do a keyed read on a file that is not keyed. Program terminates unless you have an ON ERROR routine in effect. RESUME label

368

IBM 4680 BASIC: Language Reference

ERR Code XL

ERRN Code

Description

0000041E Explanation: The program attempted to execute a POINT or PTRRTN statement on a non-sequential file. RTSL Action: User Response: Program terminates unless you have an ON ERROR routine in effect. RESUME label

XM

00000420

Explanation: The program attempted to execute a POINT or PTRRTN statement on a file opened UNLOCKED, and NOWRITE was not specified in the OPEN statement. RTSL Action: User Response: Program terminates unless you have an ON ERROR routine in effect. RESUME label

XN

00000422

Explanation: The format string for a WRITE FORM statement on a write to DI:, SJ:, or CR: devices contains an A followed by an illegal character. RTSL Action: User Response: format string. Program terminates unless you have an ON ERROR routine in effect. RESUME label - Remove the illegal character following the A in the

XO

00000424

Explanation: RTSL Action:

The WRITE LOGO statement is not allowed on files. Program terminates unless you have an ON ERROR routine in effect. RESUME label.

User Response: XP 00000426 Explanation: RTSL Action: User Response: XQ 00000428

The WRITE MATRIX statement is allowed only on files opened sequentially. Program terminates unless you have an ON ERROR routine in effect. RESUME label.

Explanation: The link number of an OPEN SESSION statement was not the number of an open SNA link. RTSL Action: User Response: Program terminates unless you have an ON ERROR routine in effect. RESUME label.

XS

0000042C Explanation: RTSL Action:

An AUTOUNLOCK of a WRITE statement failed. Program terminates unless you have an ON ERROR routine in effect. RESUME only/RESUME RETRY/RESUME label

User Response: XT 0000042E Explanation: RTSL Action: User Response: ZO 00000430

An AUTOLOCK of a READ statement failed. Program terminates unless you have an ON ERROR routine in effect. RESUME only/RESUME RETRY/RESUME label

Explanation: A SIZE function specifies a file name that is not currently open in the terminal. Terminal applications may only get the SIZE of currently open files. RTSL Action: User Response: Program aborts unless you have an ON ERROR routine in effect. RESUME label.

Appendix B. Runtime Error Messages

369

370

IBM 4680 BASIC: Language Reference

Appendix C. IBM 4680 BASIC Reserved Words


This following list contains all the IBM 4680 BASIC reserved words. These may not be used as variable names in your program.
ABS ACCESS ALPHA AND ANGLE APPEND AS ASC ASK ASSIGNKEY ASYNC ATTACH ATTACH ATCLOSE ATN AUTOLOCK AUTOUNLOCK BACKGROUND BEAM BEGIN BINDVAR BLINK BORDER BOUNDS BSC BUFF BUFFSIZE CALL CHAIN CHARACTER CHDIR CHR$ CLEAR CLEARS CLIP CLOSE COLOR COLORS CLEARS COMMAND$ COMMON COMPOUND COMSTATUS CONCHAR% CONSOLE CONSTAT% COS COUNT CREATE CURRENCY DATA DATE DATE$ DECIMAL DEF DELETE DELREC DETACH DEVICE DIM DIRECT DISABLE DISK DISPLAY ELSE ENABLE END ENDIF EQ ERR ERRF% ERRL ERRN ERROR EVENT% EXIT EXP EXTERNAL FAST FEND FILL FLOAT FMTTBL FOR FORM FRE FUNCTION FUNCTIONKEY GE GET GETLONG GLOBAL GO GOSUB GOTO GRAPHIC GT HEIGHT HOLD IF INITIALIZE INKEY INPUT INT INT% INTEGER INVERSE ISTBL JUSTIFY KEEP KEY KEYED KEYIN LE LEFT$ LEN LET LINE LINK LOAD LOCAL LOCATE LOCK LOCKDEV LOCKED LOG LOGO LOGP LPRINTER LT MARKER MAT MATCH MATRIX MFRE MID$ MIRRORED MKDIR MOD MODE MODTBL MUSIC NE NEXT NODEL NOREAD NOT NOWRITE OFF ON OPEN OPTION OR OUT PACK$ PEEK PERUPDATE PLAY PLOT POINT POKE POS POSFILE POSITION PRIME PRINT PRINT# PRIORITY PTRRTN PUBLIC PURGE PUT PUTLONG QUIESCE RANDOM RANDOMIZE READ READ# READONLY READMATRIX REAL RECEIVE RECL RECL RECURSIVE REM REMARK RENAME RESTORE RESUME RETRY RETURN

Copyright IBM Corp. 1985, 2003

371

RIGHT$ RMDIR RND ROUND SADD SEGMENT SEND SERIAL SESSION SET SGN SHIFT SIN

SIZE SLOW SNA SQR STEP STOP STR$ STRING STRING$ STYLE SUB TAB TAN

TCLOSE TEXT THEN TIME TIME$ TO TRANSLATE$ TYPE UCASE$ UNLOCK UNLOCKDEV UNLOCKED UNPACK$

USE USING VAL VARPTR VIEWPORT WAIT WEND WHILE WINDOW WRITE WRITEMATRIX XOR

Certain IBM 4680 BASIC statement and function reserved words are designed for use in the store controller or the terminal application only. The %ENVIRON directive enables you to specify compilation for either store controller or terminals. See Chapter 9, IBM 4680 BASIC Compiler Operation for more information on the %ENVIRON directive. Note: If you do not specify store controller or terminal using the %ENVIRON directive, the default is to store controller.

372

IBM 4680 BASIC: Language Reference

Appendix D. Statement and Language-Defined Function Summary


When you are writing a program, you know what you want your program to do, but you are not sure which statement or function to use. This appendix organizes the IBM 4680 BASIC statements and language-defined functions into categories. It is a convenient source of reference that enables you to compare the various IBM 4680 BASIC programming alternatives. See Chapter 7, Statements and Language-Defined Functions for detailed information on each statement and function. The following is a list of the categories in this appendix: v Statements Input/Output Statements Non-Input/Output Statements v Language-Defined Functions Numeric Functions - Arithmetic Functions - String-Related Numeric Functions - Input/Output Numeric Functions - Miscellaneous Numeric Functions String Functions - General String Functions - Input/Output String Functions - Miscellaneous String Functions

Statements Input/Output Statements


ACCESS The ACCESS statement defines access rights for all files created in the program. CLEARS The CLEARS statement clears the screen of a specified I/O device display. CLOSE The CLOSE statement terminates input and output for I/O sessions. CONSOLE The CONSOLE statement directs all program output to the screen. CREATE The CREATE statement creates new files, queues, and pipes. CREATE POSFILE The CREATE POSFILE statement creates point-of-sale sequential disk files for the store controller environment. CREATE POSFILE KEYED The CREATE POSFILE KEYED statement creates point-of-sale keyed disk files for the store controller environment.
Copyright IBM Corp. 1985, 2003

373

CREATE POSFILE RANDOM/DIRECT The CREATE POSFILE RANDOM/DIRECT statement creates point-of-sale random and direct disk files for the store controller environment. DELETE The DELETE statement deactivates files from processing and erases them from the directory. DELREC The DELREC statement deletes a specified record from a keyed file. INPUT The INPUT statement requests data from the keyboard and assigns the data to variables. INPUT LINE The INPUT LINE statement requests a character string from the keyboard and assigns it to a string variable. LOAD The LOAD statement reads data from files into memory for use by the I/O processor. LOCATE The LOCATE statement moves the cursor to the specified pair of screen coordinates. LOCKDEV The LOCKDEV statement restricts input from the MSR device. For the I/O processor, LOCKDEV restricts input from the keyboard, scanner, OCR device, or magnetic wand. LPRINTER The LPRINTER statement directs all program output to the printer. OPEN The OPEN statement activates files, pipes, and queues for input and output. OPEN LINK The OPEN LINK statement activates a link process for host communications. OPEN SERIAL The OPEN SERIAL statement activates a serial driver session. OPEN SESSION The OPEN SESSION statement opens a host communications session. POINT The POINT statement positions a sequential file pointer for subsequent READ operations. PRINT The PRINT statement sends data to a keyboard or printer. PRINT # The PRINT # statement sends data to a disk file. PRINT USING The PRINT USING statement enables you to specify special formats for data output to the keyboard, printer, or disk file. PUT The PUT statement sends one byte of data to a specified I/O session.

374

IBM 4680 BASIC: Language Reference

PUTLONG The PUTLONG statement sends four bytes of data to a specified I/O session. READ # The READ # statement reads fields of data from a specified I/O session into specified variables. READ # LINE The READ # LINE statement reads one record of data from a specified I/O session into a specified string variable. READ FORM # The READ FORM # statement reads data from a specified I/O session into specified variables under the control of a format string. TCLOSE The TCLOSE statement temporarily closes an I/O session to update a directory or force the pending output of data. UNLOCKDEV The UNLOCKDEV statement allows input from the MSR device following a LOCKDEV operation. For the I/O processor, UNLOCKDEV allows input from the keyboard, scanner, OCR device, or magnetic wand following a LOCKDEV operation. WAIT The WAIT statement suspends program execution for a specified time interval or until input from a specified I/O session is available. WRITE The WRITE statement sends expressions to a specified I/O session. WRITE LOGO The WRITE LOGO statement is a form of the WRITE that handles all-points-addressable output. WRITE MATRIX The WRITE MATRIX statement is a form of the WRITE statement that efficiently handles one-dimensional string array output to sequential files.

Non-Input/Output Statements
ASSIGNKEY The ASSIGNKEY statement assigns a new value to a Programmable Function Key. CALL The CALL statement invokes subprograms or multiline functions. CHAIN The CHAIN statement invokes overlay programs and application programs. CHDIR The CHDIR statement changes to a different file directory. COMMON The COMMON statement specifies variables to retain in memory for use by chained programs. DATA The DATA statement specifies a list of constants that a READ can assign to variables. DEF The DEF statement defines both single-line and multiline functions.
Appendix D. Statement and Language-Defined Function Summary

375

DIM END

The DIM statement specifies the dimensions of an array and allocates the required storage space. The END statement indicates the end of an IBM 4680 BASIC program.

END FUNCTION The END FUNCTION statement indicates the end of a multiline function definition. (Same as FEND Statement) END SUB The END SUB statement indicates the end of a subprogram definition. EXIT FUNCTION The EXIT FUNCTION statement transfers control from a multiline function back to the calling program. EXIT SUB The EXIT SUB statement transfers control from a subprogram back to the calling program. FEND The FEND statement indicates the end of a multiline function definition. (Same as END FUNCTION Statement) FOR The FOR statement indicates the beginning and controls the processing of a FOR/NEXT loop.

FUNCTION The FUNCTION statement indicates the beginning of a multiline function definition. FUNCTIONKEY The FUNCTIONKEY statement turns the Programmable Function Key display on or off. GLOBAL Attribute The GLOBAL attribute statement declares the variables in a type declaration global to all modules in a program. GOSUB The GOSUB statement transfers control to a subroutine. GOTO The GOTO statement transfers execution to a labeled statement. IF The IF statement transfers control to the next source statement based on the value of a logical expression.

IF END # The IF END # statement transfers control to a labeled statement when a file access error occurs. INTEGER The INTEGER statement specifies an integer data type for variables and user-defined functions. LET The LET statement assigns the value of an expression to a variable.

MKDIR The MKDIR statement creates new directories. NEXT The NEXT statement indicates the end of a FOR/NEXT loop. ON ASYNC ERROR CALL The ON ASYNC ERROR CALL statement transfers control to the specified subprogram upon detection of an asynchronous runtime error.

376

IBM 4680 BASIC: Language Reference

ON

The ON statement transfers control to one of a specified number of labeled statements.

ON ERROR The ON ERROR statement transfers control to a labeled statement upon detection of a synchronous runtime error. OPTION The OPTION statement specifies different numeric and currency symbols for numeric data fields. POKE The POKE statement stores one byte of data at a specified memory location. RANDOMIZE The RANDOMIZE statement seeds the random number generator for use with the RND function. READ The READ statement sequentially assigns the constants in a DATA to specified variables. REAL The REAL statement specifies a real data type for variables and user-defined function. REMARK The REMARK statement enables you to place comments in a source program to improve readability. RESTORE The RESTORE statement repositions the DATA pointer to the beginning of the DATA constant list. RESUME The RESUME statement provides a recovery method for runtime errors not due to program logic and not handled by the IF END # statement. RETURN The RETURN statement transfers control from a subroutine to the first statement following the GOSUB that called the subroutine. RMDIR The RMDIR statement deletes (removes) a specified directory. STOP The STOP statement closes all open files and returns control to the operating system. STRING The STRING statement specifies a real data type for variables and user-defined functions SUB USE WEND The WEND statement indicates the end of a WHILE/WEND loop. WHILE The WHILE statement indicates the beginning and controls the processing of a WHILE/WEND loop. The SUB statement indicates the beginning of a subprogram definition. The USE statement obtains parameters passed on a CHAIN statement.

Language-Defined Functions
ABS The ABS function returns the absolute value of a numeric expression.
Appendix D. Statement and Language-Defined Function Summary

377

FLOAT The FLOAT function converts a 4-byte integer to a real (floating point) number. INT The INT function truncates the fractional portion of a numeric expression and returns the integer portion as a real (floating point) number.

INT% The INT% function truncates the fractional portion of a numeric expression and returns the integer portion as an integer. MOD The MOD function returns the remainder from the division of one numeric expression by another. RND The RND function generates and returns a uniformly distributed random number between 0 and 1. RANDOMIZE seeds the random number generator.

ROUND The ROUND function returns a real number rounded to a specified number of digits. SGN SHIFT The SHIFT function returns an integer that is arithmetically shifted a specified number of positions to the right. The SGN function returns an integer that represents the algebraic sign of a specified numeric expression.

String-Related Numeric Functions


ASC PACK$ The PACK$ function converts an ASCII string into a packed Binary Coded Decimal (BCD) string representation. UNPACK$ The UNPACK$ function converts a packed Binary Coded Decimal (BCD) string representation into an ASCII string. VAL The VAL function converts an ASCII digit string to a real number. The ASC function returns the ASCII decimal value for the first character in a string expression.

Input/Output Numeric Functions


CONCHAR% The CONCHAR% function returns the ASCII decimal value of an ASCII character entered at the controller keyboard. CONSTAT% The CONSTAT% function returns a logical value signifying the status of the controller keyboard. EVENT% The EVENT% function returns the I/O session number associated with the completion of a WAIT time interval. GET The GET function reads one byte of data from a specified file.

GETLONG The GETLONG function returns four bytes of data from a specified I/O session.

378

IBM 4680 BASIC: Language Reference

INKEY The INKEY function requests an ASCII character from the keyboard and returns the ASCII decimal value of the character. LOCK The LOCK function restricts all programs from modifying the data in a specified record. POS The POS function returns the next output column on the keyboard or printer.

PTRRTN The PTRRTN function returns the offset value in a sequential file indicating where the most recent READ or WRITE operation occurred. SIZE TAB The SIZE function returns the number of bytes in a specified file. The TAB function moves the cursor or print head to a specified column number.

UNLOCK The UNLOCK function unlocks a specified record enabling any program to modify data in the record.

Miscellaneous Numeric Functions


DISABLE The DISABLE function disables software interrupts. ENABLE The ENABLE function enables software interrupts. ERRF% The ERRF% function returns the I/O session number associated with the most recent I/O error. ERRL The ERRL function returns the number of the line containing the most recent runtime error. ERRN The ERRN function returns a 4-byte error code associated with I/O device and operating system errors. FRE The FRE function returns the number of bytes available in the Free Storage Area (FSA).

MFRE The MFRE function returns a number that indicates the largest number of contiguous bytes of available memory space in the heap. PEEK The PEEK function returns the contents of a specified memory location. SADD The SADD function returns a 4-byte value that represents a 16-bit or a 32-bit address in SOCCER. VARPTR The VARPTR function returns a 4-byte integer that represents a 16-bit or a 32-bit address of a variable.

String Functions
General String Functions
CHR$ The CHR$ function returns the ASCII character that corresponds to a specified ASCII decimal value.

Appendix D. Statement and Language-Defined Function Summary

379

LEFT$ The LEFT$ function returns a string containing a specified number of characters that are positioned leftmost in a string. LEN The LEN function returns the length of a string expression.

MATCH The MATCH function returns the position of the first occurrence of a specified character pattern in a string. MID$ The MID$ function returns a segment of a specified string. RIGHT$ The RIGHT$ function returns a string containing a specified number of characters that are positioned rightmost in a string. STR$ The STR$ function converts the value of a numeric expression to an equivalent string of digits.

TRANSLATE$ The TRANSLATE$ function converts the characters of one string to the characters of a second string based on comparison with a third string. UCASE$ The UCASE$ function converts all lowercase characters in a string to uppercase.

Input/Output and Miscellaneous String Functions


COMMAND$ The COMMAND$ function returns a string containing the command tail used to run the program. DATE$ The DATE$ function returns a string indicating the current year, month, and day set through the operating system. ERR The ERR function returns a two-character string signifying the last runtime error to occur in a program.

RENAME The RENAME function changes the name of a file during program execution. STRING$ The STRING$ function returns a string that consists of one string copied a specific number of times. TIME$ The TIME$ function returns a string indicating the current time of day set through the operating system.

380

IBM 4680 BASIC: Language Reference

Appendix E. Data I/O Device Statement Figures


Figure 28 shows which IBM 4680 BASIC statements are valid for the various types of files and for pipes.

Copyright IBM Corp. 1985, 2003

381

Files (Pipes)/ BASIC Statements CLOSE CREATE CREATE POSFILE DELETE DELREC GET GETLONG LOCK OPEN POINT PRINT # PTRRTN PUT PUTLONG READ # READ FORM # READ LINE # RENAME RESUME SIZE TCLOSE UNLOCK WAIT WRITE # WRITE FORM # WRITE MATRIX

K E Y E D Y

D I R E C T Y Y

R A N D O M Y Y Y Y

S E Q U E N T I A L Y Y Y Y

P I P E Y Y

1 Y Y

Y Y

1 1 N* Y Y* Y

1 1 Y* Y

1 1

1 1

Y Y

1 Y

1 1

1 1 Y

1 1 Y Y Y Y Y Y Y

1 1 Y Y Y

Y Y

Y Y Y Y N*

Y Y Y Y Y*

Y Y Y Y Y*

Y Y Y Y Y Y Y Y Y Y

N * For keyed files use READ AUTOLOCK and WRITE AUTOUNLOCK. Y * Can use LOCK/UNLOCK (Store Controller only) or READ AUTOLOCK/WRITE AUTOUNLOCK. Store Controller only 1

Figure 28. File Type to IBM 4680 BASIC Statement Match

382

IBM 4680 BASIC: Language Reference

Appendix F. Character Sets For Terminal Printers, Displays, and Controller Video Display
Each character set contains 255 code points (00H - FFH) and the character available at that code point for each device. This appendix contains the character sets for the following devices: Terminal v Alphanumeric Display v Operator Display v Liquid Crystal Display v 40 Character Vacuum Fluorescent Display II (VFD II) v Printer Models 1 and 2 v Printer Models 3 and 4 v Feature A Video Display v VGA Video Display v Shopper Display Controller v 4680 Controller Video Display v 4690 Controller Video Display In addition, you will find: Escape Sequences for the Controller Display Extended Codes for Controller Keyboard input Character sets are selected during 4680 or 4690 installation when country selection is made. These character sets are based as close as the electronics of the device can support, to a standard code page. 4690 treats the first 20 codepoints of the controller video display as control characters. Displayable characters are not available for these codepoints. If the user logical name disp4680 has been defined, then a 4680 Controller Video Display Character Set are used instead. In a 4680 Controller Video Display Character Set, only the following code points are treated as control characters: v 07 - bell v 08 - backspace v 09 - tab v 0A - linefeed v 0D - carriage return

Copyright IBM Corp. 1985, 2003

383

Hex

1st 2nd 0

0
000 016 03 2 048

@
064

P
080

.
096

P
11 2

128

1 44

.
160

.
176

.
192

.
208

.
224

.
2 40

Decimal
1

!
001 017 03 3

1
04 9

A
065

Q
081

A
097

Q
11 3

129

145

.
161

.
177

.
193

.
209 225

.
241

2
00 2 018

"
034

2
050

B
066

R
08 2

B
098

R
11 4

130

146

162

.
178

.
194

.
2 10

.
226

.
242

3
00 3 01 9

#
035

3
051

C
067

S
08 3

C
09 9

S
11 5

131

147

163

.
179

.
195

.
2 11

.
227

.
243

4
004

.
020

$
036

4
05 2

D
068

T
084

D
100

T
11 6

132

148

.
164

.
180

.
196

.
212

.
228

.
244

5
005

.
021

%
037

5
05 3

E
06 9

U
085

E
101

U
11 7

133

149

.
165

.
181

.
197

.
213

.
229

.
245

6
006 02 2

&
038

6
054

F
070

V
086

F
102

V
11 8

.
134

150

.
166

.
182

.
198

.
214

.
2 30

.
246

7
007 02 3

'
03 9

7
055

G
071

W
087

G
103

W
11 9

135

151

.
167

.
183

.
199

.
215

.
231

.
247

8
008 024

(
040

8
056

H
07 2

X
088

H
104

X
120

136

.
152

168

.
184

.
2 00

.
216

.
232

.
248

9
00 9 025

)
041

9
057

I
07 3

Y
08 9

I
105

Y
121

137

1 53

.
169

.
185

.
201

.
217

.
233

.
249

A
010 026

*
04 2

:
058

J
074

Z
090

J
106

Z
122

138

1 54

.
170

.
186

.
202

.
218

.
234

.
2 50

B
0 11 027

+
04 3

;
05 9

K
075

[
091

K
107

{
1 23

139

155

.
171

.
187

.
203

.
219

.
235

.
251

C
01 2 028

,
044

<
060

L
076

\
09 2

L
108 1 24

140

156

.
172

.
188

.
204

.
2 20

.
236

.
252

D
01 3 02 9

045

=
061

M
077

]
09 3

M
109

}
125

.
141

157

.
173

.
189

.
205

.
221

.
237

.
253

E
014 0 30

.
046

>
06 2

N
078 094

N
11 0 126

142

158

.
174

.
190

.
206

.
222

.
238

.
254

F
015 031

/
047

?
06 3

O
07 9

095

O
111

.
127

.
143

.
159

.
175

.
191

.
207

.
223

.
239 255

Figure 29. Alphanumeric Display Character Set - Canadian French (Based on Code Page 863)

384

IBM 4680 BASIC: Language Reference

Hex
2nd

1st

0
Decimal
000 016 032

0
048

@
064

P
080

.
096

p
112

128

144

.
160

.
176

.
192

.
208

.
224

.
240

1
001 017

!
033

1
049

A
065

Q
081

a
097

q
113

129

145

.
161

.
177

.
193

.
209 225

.
241

2
002 018

"
034

2
050

B
066

R
082

b
098

r
114

130

146

162

.
178

.
194

.
210 226

.
242

3
003 019

#
035

3
051

C
067

S
083

c
099

s
115

131

147

163

.
179

.
195

.
211

.
227

.
243

4
004

.
020

$
036

4
052

D
068

T
084

d
100

t
116

132

148

.
164

.
180

.
196

.
212 228

.
244

5
005

.
021

%
037

5
053

E
069

U
085

e
101

u
117

133

149

.
165

.
181

.
197

.
213

.
229

.
245

6
006 022

&
038

6
054

F
070

V
086

f
102

v
118

.
134

150

.
166

.
182

.
198

.
214

.
230

.
246

7
007 023

'
039

7
055

G
071

W
087

g
103

w
119

135

151

.
167

.
183

.
199

.
215

.
231

.
247

8
008 024

(
040

8
056

H
072

X
088

h
104

x
120

136

.
152

168

.
184

.
200

.
216 232

.
248

9
009 025

)
041

9
057

I
073

Y
089

i
105

y
121

137

153

.
169

.
185 201

.
217 233

.
249

A
010 026

*
042

:
058

J
074

Z
090

j
106

z
122

138

154

.
170

.
186

.
202

.
218 234

.
250

B
011 027

+
043

;
059

K
075

[
091

k
107

{
123

139

155

.
171

.
187

.
203

.
219

.
235

.
251

C
012 028

,
044

<
060

L
076

\
092

l
108

|
124

140

156

.
172

.
188

.
204

.
220

.
236

.
252

D
013 029

045

=
061

M
077

]
093

m
109

}
125

.
141

157

.
173

.
189

.
205

.
221

237

.
253

E
014 030

.
046

>
062

N
078

^
094

n
110

.
126

142

158

.
174

.
190

.
206

.
222

.
238

.
254

F
015 031

/
047

?
063

O
079

_
095

o
111

.
127

.
143

.
159

.
175

.
191

.
207

.
223

.
239 255

Figure 30. LCD Character Set - Canadian French (Based on Code Page 863)

Appendix F. Character Sets For Terminal Printers, Displays, and Controller Video Display

385

Hex
2nd

1st

0
Decimal
000 016 032

0
048

@
064

P
080

.
096

P
112

128

144

.
160

.
176

.
192

.
208

.
224

.
240

1
001 017

!
033

1
049

A
065

Q
081

A
097

Q
113

129

145

.
161

.
177

.
193

.
209 225

.
241

2
002 018

"
034

2
050

B
066

R
082

B
098

R
114

130

146

162

.
178

.
194

.
210

.
226

.
243

3
003 019

#
035

3
051

C
067

S
083

C
099

S
115

131

147

163

.
179

.
195

.
211

.
227

.
243

4
004

.
020

$
036

4
052

D
068

T
084

D
100

T
116

132

148

.
164

.
180

.
196

.
212

.
228

.
244

5
005

.
021

%
037

5
053

E
069

U
085

E
101

U
117

133

149

.
165

.
181

.
197

.
213

.
229

.
245

6
006 022

&
038

6
054

F
070

V
086

F
102

V
118

.
134

150

.
166

.
182

.
198

.
214

.
230

.
246

7
007 023

'
039

7
055

G
071

W
087

G
103

W
119

135

151

.
167

.
183

.
199

.
215

.
231

.
247

8
008 024

(
040

8
056

H
072

X
088

H
104

X
120

136

.
152

168

.
184

.
200

.
216

.
232

.
248

9
009 025

)
041

9
057

I
073

Y
089

I
105

Y
121

137

153

.
169

.
185

.
201

.
217

.
233

.
249

A
010 026

*
042

:
058

J
074

Z
090

J
106

Z
122

138

154

.
170

.
186

.
202

.
218

.
234

.
250

B
011 027

+
043

;
059

K
075

[
091

K
107

{
123

139

155

.
171

.
187

.
203

.
219

.
235

.
251

C
012 028

,
044

<
060

L
076

\
092

L
108

|
124

140

156

.
172

.
188

.
204

.
220

.
236

.
252

D
013 029

045

=
061

M
077

]
093

M
109

}
125

.
141

157

.
173

.
189

.
205

.
221

.
237

.
253

E
014 030

.
046

>
062

N
078

^
094

N
110

.
126

142

158

.
174

.
190

.
206

.
222

.
238

.
254

F
015 031

/
047

?
063

O
079

_
095

O
111

.
127

.
143

.
159

.
175

.
191

.
207

.
223

.
239 255

Figure 31. Operator Display Character Set - Canadian French (Based on Code Page 863)

386

IBM 4680 BASIC: Language Reference

Hex

1st 2nd 0

.
0 00 016 03 2

0
048

@
064

P
080

.
096

P
11 2

128

1 44

.
160

.
176

.
192

.
208

.
224

.
2 40

Decimal
1

.
001

.
017

!
03 3

1
04 9

A
065

Q
081

A
097

Q
11 3

129

145

.
161

.
177

.
193

.
209 225

.
241

.
002

.
018

"
034

2
050

B
066

R
08 2

B
098

R
11 4

130

146

162

.
178

.
194

.
2 10

.
226

.
242

.
00 3

.
01 9

#
035

3
051

C
067

S
08 3

C
09 9

S
11 5

131

147

1 63

.
179

.
195

.
2 11

.
227

.
243

.
004

.
020

$
036

4
05 2

D
068

T
084

D
100

T
11 6

132

148

.
1 64

.
180

.
196

.
212

.
228

.
244

.
005

.
021

%
037

5
05 3

E
06 9

U
085

E
101

U
11 7

133

149

.
165

.
181

.
197

.
213

.
229

.
245

.
006

.
02 2

&
038

6
054

F
070

V
086

F
102

V
11 8

.
134

150

.
166

.
182

.
198

.
214

.
2 30

.
246

.
007

.
02 3

'
03 9

7
055

G
071

W
087

G
103

W
11 9

135

151

.
167

.
183

.
199

.
215

.
231

.
247

.
008

.
024

(
040

8
056

H
07 2

X
088

H
104

X
120

136

.
152

168

.
184

.
2 00

.
216

.
232

.
248

.
009

.
025

)
041

9
057

I
07 3

Y
08 9

I
105

Y
121

137

1 53

.
169

.
185

.
201

.
217

.
233

.
249

.
0 10

.
026

*
04 2

:
058

J
074

Z
090

J
106

Z
122

138

1 54

.
170

.
186

.
202

.
218

.
234

.
2 50

.
0 11

.
027

+
04 3

;
05 9

K
075

[
091

K
107

{
1 23

139

155

.
171

.
187

.
203

.
219

.
235

.
251

.
012

.
028

,
044

<
060

L
076

\
09 2

L
108 1 24

140

156

.
172

.
188

.
204

.
2 20

.
236

.
252

.
013

.
02 9

045

=
061

M
077

]
09 3

M
109

}
125

.
141

157

.
1 73

.
189

.
205

.
221

.
237

.
253

.
014

.
030

.
046

>
06 2

N
078

N
11 0 126

142

158

.
1 74

>

.
190

.
206

.
222

.
238

.
254

094

.
015

.
031

/
047

?
06 3

O
07 9

095

O
111

.
127

.
143

.
159

.
175

.
191

.
207

.
223

.
239 255

Figure 32. Printer Models 1 and 2 Character Set - Canadian French (Based on Code Page 863)

Appendix F. Character Sets For Terminal Printers, Displays, and Controller Video Display

387

Hex

1st 2nd 0

.
0 00

.
016 032

0
048

@
064

P
0 80

.
096

p
11 2

128

1 44

.
160

.
176

.
192

.
208

.
224

.
240

Decimal
1

.
001

.
017

!
033

1
049

A
065

Q
081

a
097

q
11 3

129

145

.
161

.
177

.
1 93

.
209 225

+
241

.
002

.
018

"
034

2
0 50

B
066

R
082

b
098

r
11 4

130

146

162

.
178

.
1 94

.
210

.
226

.
242

.
003

.
019

#
035

3
051

C
067

S
083

c
099

s
11 5

131

147

1 63

.
179

.
195

.
211

.
227

.
243

.
004

.
0 20

$
036

4
052

D
068

T
084

d
100

t
11 6

132

148

.
1 64

.
180

.
196

.
212

.
228

.
244

.
005

.
021

%
037

5
053

E
069

U
085

e
101

u
11 7

1 33

149

.
165

.
181

.
197

.
213

.
229

.
245

.
006

.
022

&
038

6
054

F
0 70

V
086

f
102

v
11 8

.
1 34

150

.
166

.
182

.
198

.
214 230 246

.
007

.
023

'
039

7
055

G
071

W
087

g
1 03

w
11 9

135

151

.
167

.
1 83

.
199

.
215

.
231

.
247

.
008

.
024

(
0 40

8
056

H
072

X
088

h
1 04

x
120

136 152

168

.
1 84 200

.
216

.
232

.
248

.
009

.
025

)
041

9
057

I
073

Y
089

i
105

y
121

137

1 53

.
169 185 201

.
217

.
233

.
249

.
0 10

.
026

*
042

:
058

J
074

Z
0 90

j
106

z
122

138

1 54

.
170 186 202

.
218

.
234

.
250

.
0 11

.
027

+
043

;
059

K
075

[
091

k
107

{
1 23

139

155

.
171 187 203

.
219

.
235

.
251

.
012

.
028

,
044

<
0 60

L
076

\
092

l
108

|
1 24

140

156

.
172 188 204

.
220

.
236

.
252

.
013

.
029

045

=
061

M
077

]
093

m
109

}
125

=
141

157

.
1 73

.
189 205

.
221

.
237

.
253

.
014

.
0 30

.
046

>
062

N
078 094

n
11 0 126

142

158

.
1 74

.
190 206

.
222

.
238 254

.
015

.
031

/
047

?
063

O
079

095

o
111

.
127

.
1 43

.
159

.
175

.
191

.
207

.
223

.
239 255

Figure 33. Printer Models 3 and 4 Character Set - Canadian French (Based on Code Page 863)

388

IBM 4680 BASIC: Language Reference

Hex
2nd

1st

0
Decimal
000 016 032

0
048

@
064

P
080

.
096

p
112

128

144

.
160

.
176

.
192

.
208

.
224

.
240

1
001 017

!
033

1
049

A
065

Q
081

a
097

q
113

129

145

.
161

.
177

.
193

.
209 225

.
241

2
002 018

"
034

2
050

B
066

R
082

b
098

r
114

130

146

162

.
178

.
194

.
210 226

.
242

3
003 019

#
035

3
051

C
067

S
083

c
099

s
115

131

147

163

.
179

.
195

.
211

.
227

.
243

4
004

.
020

$
036

4
052

D
068

T
084

d
100

t
116

132

148

.
164

.
180

.
196

.
212 228

.
244

5
005

.
021

%
037

5
053

E
069

U
085

e
101

u
117

133

149

.
165

.
181

.
197

.
213

.
229

.
245

6
006 022

&
038

6
054

F
070

V
086

f
102

v
118

.
134

150

.
166

.
182

.
198

.
214

.
230

.
246

7
007 023

'
039

7
055

G
071

W
087

g
103

w
119

135

151

.
167

.
183

.
199

.
215

.
231

.
247

8
008 024

(
040

8
056

H
072

X
088

h
104

x
120

136

.
152

168

.
184

.
200

.
216 232

.
248

9
009 025

)
041

9
057

I
073

Y
089

i
105

y
121

137

153

.
169

.
185 201

.
217 233

.
249

A
010 026

*
042

:
058

J
074

Z
090

j
106

z
122

138

154

.
170

.
186

.
202

.
218 234

.
250

B
011 027

+
043

;
059

K
075

[
091

k
107

{
123

139

155

.
171

.
187

.
203

.
219

.
235

.
251

C
012 028

,
044

<
060

L
076

\
092

l
108

|
124

140

156

.
172

.
188

.
204

.
220

.
236

.
252

D
013 029

045

=
061

M
077

]
093

m
109

}
125

.
141

157

.
173

.
189

.
205

.
221

237

.
253

E
014 030

.
046

>
062

N
078

^
094

n
110

.
126

142

158

.
174

.
190

.
206

.
222

.
238

.
254

F
015 031

/
047

?
063

O
079

_
095

o
111

.
127

.
143

.
159

.
175

.
191

.
207

.
223

.
239 255

Figure 34. VFD II Character Set - Canadian French (Based on Code Page 863)

Appendix F. Character Sets For Terminal Printers, Displays, and Controller Video Display

389

Hex
2nd

1st

0
Decimal
000

.
016

(SP)

0
048

@
064

P
080

`
096

p
112

128

144

|
160

.
176

.
192

.
208

.
224

.
240

032

a
001

.
017

!
033

1
049

A
065

Q
081

a
097

q
113

129

145

,
161

.
177

.
193

.
209 225

241

U
002

.
018

"
034

2
050

B
066

R
082

b
098

r
114

130

146

162

.
178

.
194

.
210

.
226

.
243

X
003

.
019

#
035

3
051

C
067

S
083

c
099

s
115

131

147

163

.
179

.
195

.
211

.
227

.
243

4
004

020

$
036

4
052

D
068

T
084

d
100

t
116

132

148

..
164

.
180

.
196

.
212

.
228

.
244

5
005

021

%
037

5
053

E
069

U
085

e
101

u
117

133

149

.
165

.
181

.
197

.
213

.
229

.
245

6
006 022

&
038

6
054

F
070

V
086

f
102

v
118

134

150

166

.
182

.
198

.
214 230

246

7
007 023

'
039

7
055

G
071

W
087

g
103

w
119

135

151

_
167

.
183

.
199

.
215

.
231

.
247

8
008 024

(
040

8
056

H
072

X
088

h
104

x
120

136

152

168

.
184

.
200

.
216

.
232 248

9
009 025

)
041

9
057

I
073

Y
089

i
105

y
121

137

153

.
169

.
185

.
201

.
217

.
233

.
249

A
010 026

*
042

:
058

J
074

Z
090

j
106

z
122

138

154 170

.
186

.
202

.
218

.
234

.
250

B
011 027

+
043

;
059

K
075

[
091

k
107

{
123

139

155

171

.
187

.
203

.
219

.
235

.
251

C
012 028

,
044

<
060

L
076

\
092

l
108

|
124

140

156

172

.
188

.
204

.
220

.
236

.
252

D
013 029

045

=
061

M
077

]
093

m
109

}
125

.
141

157

173

.
189

.
205

.
221

.
237

253

E
014 030

.
046

>
062

N
078

^
094

n
110

~
126

142

158

174

.
190

.
206

.
222

.
238

.
254

F
015 031

/
047

?
063

O
079

_
095

o
111

.
127 143

.
159

175

.
191

.
207

.
223

.
239 255

Figure 35. Video Display (Feature A) Character Set - Canadian French (Based on Code Page 863)

390

IBM 4680 BASIC: Language Reference

Hex
2nd

1st

0
Decimal
000 016

(SP)

0
048

@
064

P
080

`
096

p
112

128

144 160 176 192 208 224

= =
240

032

1
001 017

!
033

1
049

A
065

Q
081

a
097

q
113

129

145

'
161 177 193 209 225

241

2
002 018

"
034

2
050

B
066

R
082

b
098

r
114

130

146

162 178 194 210 226

>
243

3
003

!!
019

#
035

3
051

C
067

S
083

c
099

s
115

131

147

163 179 195 211 227

<
243

4
004

020

$
036

4
052

D
068

T
084

d
100

t
116

132

148

164

180

196

212

228

244

5
005

021

%
037

5
053

E
069

U
085

e
101

u
117

133

149

,
165 181 197 213 229

245

6
006 022

&
038

6
054

F
070

V
086

f
102

v
118

134

150 166 182 198 214 230

246

7
007 023

'
039

7
055

G
071

W
087

g
103

w
119

135

151

_
167 183 199 215 231

247

8
008 024

(
040

8
056

H
072

X
088

h
104

x
120

136

152

168 184 200 216 232 248

9
009 025

)
041

9
057

I
073

Y
089

i
105

y
121

137

153 169 185 201 217 233

249

A
010 026

*
042

:
058

J
074

Z
090

j
106

z
122

138

154 170 186 202 218 234

B
011 027

+
043

;
059

K
075

[
091

k
107

{
123

139

155

171 187 203 219 235 251

C
012 028

,
044

<
060

L
076

\
092

l
108

|
124

140

156

172 188 204 220 236

D
013 029

045

=
061

M
077

]
093

m
109

}
125

_ _
141

157

173 189 205 221 237

E
014 030

.
046

>
062

N
078

^
094

n
110

~
126

142

158

174 190 206 222 238

F
015 031

/
047

?
063

O
079

o
111 127

143

159

175 191 207 223

095

239

Figure 36. Video Display (VGA) Character Set - Canadian French (Based on Code Page 863)

Appendix F. Character Sets For Terminal Printers, Displays, and Controller Video Display

(RSP)

.
250

252

253

254

255

U U

n 2

..

391

Hex
2nd

1st

0
Decimal
000 016

(SP)

0
048

@
064

P
080

`
096

p
112

128

144 160 176 192 208 224

= =
240

032

1
001 017

!
033

1
049

A
065

Q
081

a
097

q
113

129

145

'
161 177 193 209 225

241

2
002 018

"
034

2
050

B
066

R
082

b
098

r
114

130

146

162 178 194 210 226

>
243

3
003

!!
019

#
035

3
051

C
067

S
083

c
099

s
115

131

147

163 179 195 211 227

<
243

4
004

020

$
036

4
052

D
068

T
084

d
100

t
116

132

148

164

180

196

212

228

244

5
005

021

%
037

5
053

E
069

U
085

e
101

u
117

133

149

,
165 181 197 213 229

245

6
006 022

&
038

6
054

F
070

V
086

f
102

v
118

134

150 166 182 198 214 230

246

7
007 023

'
039

7
055

G
071

W
087

g
103

w
119

135

151

_
167 183 199 215 231

247

8
008 024

(
040

8
056

H
072

X
088

h
104

x
120

136

152

168 184 200 216 232 248

9
009 025

)
041

9
057

I
073

Y
089

i
105

y
121

137

153 169 185 201 217 233

249

A
010 026

*
042

:
058

J
074

Z
090

j
106

z
122

138

154 170 186 202 218 234

B
011 027

+
043

;
059

K
075

[
091

k
107

{
123

139

155

171 187 203 219 235 251

C
012 028

,
044

<
060

L
076

\
092

l
108

|
124

140

156

172 188 204 220 236

D
013 029

045

=
061

M
077

]
093

m
109

}
125

_ _
141

157

173 189 205 221 237

E
014 030

.
046

>
062

N
078

^
094

n
110

~
126

142

158

174 190 206 222 238

F
015 031

/
047

?
063

O
079

o
111 127

143

159

175 191 207 223

095

239

Figure 37. 4680 Controller Video Display Character Set - Canadian French (Based on Code Page 863)

Note: Code points 07H, 08H, 09H, 0AH, and 0DH are non-displayable control characters.

392

IBM 4680 BASIC: Language Reference

(RSP)

.
250

252

253

254

255

U U

n 2

..

Hex
2nd

1st

0
Decimal
000 016

(SP)

0
048

@
064

P
080

`
096

p
112

128

144 160 176 192 208 224

= =
240

032

1
001 017

!
033

1
049

A
065

Q
081

a
097

q
113

129

145

'
161 177 193 209 225

241

2
002 018

"
034

2
050

B
066

R
082

b
098

r
114

130

146

162 178 194 210 226

>
243

3
003 019

#
035

3
051

C
067

S
083

c
099

s
115

131

147

163 179 195 211 227

<
243

4
004 020

$
036

4
052

D
068

T
084

d
100

t
116

132

148

164

180

196

212

228

244

5
005 021

%
037

5
053

E
069

U
085

e
101

u
117

133

149

,
165 181 197 213 229

245

6
006 022

&
038

6
054

F
070

V
086

f
102

v
118

134

150 166 182 198 214 230

246

7
007 023

'
039

7
055

G
071

W
087

g
103

w
119

135

151

_
167 183 199 215 231

247

8
008 024

(
040

8
056

H
072

X
088

h
104

x
120

136

152

168 184 200 216 232 248

9
009 025

)
041

9
057

I
073

Y
089

i
105

y
121

137

153 169 185 201 217 233

249

A
010 026

*
042

:
058

J
074

Z
090

j
106

z
122

138

154 170 186 202 218 234

B
011 027

+
043

;
059

K
075

[
091

k
107

{
123

139

155

171 187 203 219 235 251

C
012 028

,
044

<
060

L
076

\
092

l
108

|
124

140

156

172 188 204 220 236

D
013 029

045

=
061

M
077

]
093

m
109

}
125

_ _
141

157

173 189 205 221 237

E
014 030

.
046

>
062

N
078

^
094

n
110

~
126

142

158

174 190 206 222 238

F
015 031

/
047

?
063

O
079

o
111 127

143

159

175 191 207 223

095

239

Figure 38. 4690 Controller Video Display Character Set - Canadian French (Based on Code Page 863)

Note: Code points 00H through IFH are non-displayable control characters.

Appendix F. Character Sets For Terminal Printers, Displays, and Controller Video Display

(RSP)

.
250

252

253

254

255

U U

n 2

..

393

Hex
2nd

1st

0
Decimal
000 016 032

0
048

@
064

P
080

.
096

p
112 128

.
144

.
160

.
176

.
192 208

.
224

.
240

1
001 017

!
033

1
049

A
065

Q
081

a
097

q
113 129

145

.
161

.
177

.
193 209

.
225

.
241

2
002 018

"
034

2
050

B
066

R
082

b
098

r
114 130

.
146

162

.
178

.
194 210

.
226

.
242

3
003 019

#
035

3
051

C
067

S
083

c
099

s
115 131 147

.
163

.
179

.
195 211

.
227 243

4
004

.
020

$
036

4
052

D
068

T
084

d
100

t
116 132 148 164

.
180

.
196 212

.
228

.
244

5
005

.
021

%
037

5
053

E
069

U
085

e
101

u
117 133

.
149 165 181

.
197 213

.
229

.
245

6
006 022

&
038

6
054

F
070

V
086

f
102

v
118

.
134

.
150 166 182 198

.
214

.
230

.
246

7
007 023

'
039

7
055

G
071

W
087

g
103

w
119 135

.
151 167 183 199 215

.
231

.
247

8
008 024

(
040

8
056

H
072

X
088

h
104

x
120

.
136

.
152 168 184

.
200

.
216

.
232

.
248

9
009 025

)
041

9
057

I
073

Y
089

i
105

y
121

.
137

.
153 169

.
185 201

.
217

.
233

.
249

A
010 026

*
042

:
058

J
074

Z
090

j
106

z
122

.
138

.
154 170

.
186

.
202

.
218

.
234

.
250

B
011 027

+
043

;
059

K
075

[
091

k
107

{
123

.
139

.
155

.
171

.
187

.
203

.
219

.
235

.
251

C
012 028

,
044

<
060

L
076

\
092

l
108

|
124

.
140

156 172

.
188

.
204

.
220

.
236

.
252

D
013 029

045

=
061

M
077

]
093

m
109

}
125

.
141

.
157 173 189

.
205

.
221

.
237

.
253

E
014 030

.
046

>
062

N
078

^
094

n
110

.
126

.
142

.
158

.
174 190

.
206

.
222

.
238

.
254

F
015 031

/
047

?
063

O
079

_
095

o
111

.
127

.
143

.
159

.
175

.
191 207

.
223

.
239 255

Figure 39. LCD Character Set - Greece (Based on Code Page 869)

394

IBM 4680 BASIC: Language Reference

Hex
2nd

1st

0
Decimal
000 016 032

0
048

@
064

P
080

.
096

p
112 128

.
144

.
160

.
176

.
192 208

.
224

.
240

1
001 017

!
033

1
049

A
065

Q
081

a
097

q
113 129

145

.
161

.
177

.
193 209

.
225

.
241

2
002 018

"
034

2
050

B
066

R
082

b
098

r
114 130

.
146

162

.
178

.
194 210

.
226

.
242

3
003 019

#
035

3
051

C
067

S
083

c
099

s
115 131 147

.
163

.
179

.
195 211

.
227 243

4
004

.
020

$
036

4
052

D
068

T
084

d
100

t
116 132 148 164

.
180

.
196 212

.
228

.
244

5
005

.
021

%
037

5
053

E
069

U
085

e
101

u
117 133

.
149 165 181

.
197 213

.
229

.
245

6
006 022

&
038

6
054

F
070

V
086

f
102

v
118

.
134

.
150 166 182 198

.
214

.
230

.
246

7
007 023

'
039

7
055

G
071

W
087

g
103

w
119 135

.
151 167 183 199 215

.
231

.
247

8
008 024

(
040

8
056

H
072

X
088

h
104

x
120

.
136

.
152 168 184

.
200

.
216

.
232

.
248

9
009 025

)
041

9
057

I
073

Y
089

i
105

y
121

.
137

.
153 169

.
185 201

.
217

.
233

.
249

A
010 026

*
042

:
058

J
074

Z
090

j
106

z
122

.
138

.
154 170

.
186

.
202

.
218

.
234

.
250

B
011 027

+
043

;
059

K
075

[
091

k
107

{
123

.
139

.
155

.
171

.
187

.
203

.
219

.
235

.
251

C
012 028

,
044

<
060

L
076

\
092

l
108

|
124

.
140

156 172

.
188

.
204

.
220

.
236

.
252

D
013 029

045

=
061

M
077

]
093

m
109

}
125

.
141

.
157 173 189

.
205

.
221

.
237

.
253

E
014 030

.
046

>
062

N
078

^
094

n
110

.
126

.
142

.
158

.
174 190

.
206

.
222

.
238

.
254

F
015 031

/
047

?
063

O
079

_
095

o
111

.
127

.
143

.
159

.
175

.
191 207

.
223

.
239 255

Figure 40. VFD II Character Set - Greece (Based on Code Page 869)

Appendix F. Character Sets For Terminal Printers, Displays, and Controller Video Display

395

Hex
2nd

1st

0
Decimal
000 016

(SP)

0
048

@
064

P
080

`
096

p
112 128 144

..
160 176 192

T
208 224

(SHY)

032

240

1
001 017

!
033

1
049

A
065

Q
081

a
097

q
113 129

..
145

..
161 177 193

Y
209 225

241

2
002 018

"
034

2
050

B
066

R
082

b
098

r
114 130 146 162 178 194 210 226 243

3
003

!!
019

#
035

3
051

C
067

S
083

c
099

s
115 131 147 163 179 195

X
211 227 243

4
004

020

$
036

4
052

D
068

T
084

d
100

t
116 132 148 164 180 196 212 228 244

5
005

021

%
037

5
053

E
069

U
085

e
101

u
117 133 149 165 181 197 213 229

245

6
006 022

&
038

6
054

F
070

V
086

f
102

v
118 134

..
150 166 182 198 214 230 246

7
007 023

'
039

7
055

G
071

W
087

g
103

w
119 135

151 167 183 199 215 231

..
247

8
008 024

(
040

8
056

H
072

X
088

h
104

x
120

.
136 152 168 184 200 216 232

248

9
009 025

)
041

9
057

I
073

Y
089

i
105

y
121 137

2
153 169 185 201 217 233

..
249

A
010 026

*
042

:
058

J
074

Z
090

j
106

z
122

|
138

3
154 170 186 202 218 234 250

B
011 027

+
043

;
059

K
075

[
091

k
107

{
123 139 155

171 187 203 219 235

..
251

C
012 028

,
044

<
060

L
076

\
092

l
108

|
124 140

156 172 188 204 220 236

..
252

D
013 029

045

=
061

M
077

]
093

m
109

}
125 141 157 173 189 205 221 237

253

E
014 030

.
046

>
062

N
078

^
094

n
110

~
126

142 158

174

O
190 206 222 238

.
254

F
015 031

/
047

?
063

O
079

_
095

o
111 127 143

159

175 191 207 223

'
239

(RSP)

255

Figure 41. Video Display (VGA) Character Set - Greece (Based on Code Page 869)

396

IBM 4680 BASIC: Language Reference

Hex
2nd

1st

0
Decimal
000 016

(SP)

0
048

@
064

P
080

`
096

p
112 128 144

..
160 176 192

T
208 224

(SHY)

032

240

1
001 017

!
033

1
049

A
065

Q
081

a
097

q
113 129

..
145

..
161 177 193

Y
209 225

241

2
002 018

"
034

2
050

B
066

R
082

b
098

r
114 130 146 162 178 194 210 226 243

3
003

!!
019

#
035

3
051

C
067

S
083

c
099

s
115 131 147 163 179 195

X
211 227 243

4
004

020

$
036

4
052

D
068

T
084

d
100

t
116 132 148 164 180 196 212 228 244

5
005

021

%
037

5
053

E
069

U
085

e
101

u
117 133 149 165 181 197 213 229

245

6
006 022

&
038

6
054

F
070

V
086

f
102

v
118 134

..
150 166 182 198 214 230 246

7
007 023

'
039

7
055

G
071

W
087

g
103

w
119 135

151 167 183 199 215 231

..
247

8
008 024

(
040

8
056

H
072

X
088

h
104

x
120

.
136 152 168 184 200 216 232

248

9
009 025

)
041

9
057

I
073

Y
089

i
105

y
121 137

2
153 169 185 201 217 233

..
249

A
010 026

*
042

:
058

J
074

Z
090

j
106

z
122

|
138

3
154 170 186 202 218 234 250

B
011 027

+
043

;
059

K
075

[
091

k
107

{
123 139 155

171 187 203 219 235

..
251

C
012 028

,
044

<
060

L
076

\
092

l
108

|
124 140

156 172 188 204 220 236

..
252

D
013 029

045

=
061

M
077

]
093

m
109

}
125 141 157 173 189 205 221 237

253

E
014 030

.
046

>
062

N
078

^
094

n
110

~
126

142 158

174

O
190 206 222 238

.
254

F
015 031

/
047

?
063

O
079

_
095

o
111 127 143

159

175 191 207 223

'
239

(RSP)

255

Figure 42. 4680 Controller Video Display Character Set - Greece (Based on Code Page 869)

Note: Code points 07H, 08H, 09H, 0AH, and 0DH are non-displayable control characters.

Appendix F. Character Sets For Terminal Printers, Displays, and Controller Video Display

397

Hex
2nd

1st

0
Decimal
000 016

(SP)

0
048

@
064

P
080

`
096

p
112 128 144

..
160 176 192

T
208 224

(SHY)

032

240

1
001 017

!
033

1
049

A
065

Q
081

a
097

q
113 129

..
145

..
161 177 193

Y
209 225

241

2
002 018

"
034

2
050

B
066

R
082

b
098

r
114 130 146 162 178 194 210 226 243

3
003 019

#
035

3
051

C
067

S
083

c
099

s
115 131 147 163 179 195

X
211 227 243

4
004 020

$
036

4
052

D
068

T
084

d
100

t
116 132 148 164 180 196 212 228 244

5
005 021

%
037

5
053

E
069

U
085

e
101

u
117 133 149 165 181 197 213 229

245

6
006 022

&
038

6
054

F
070

V
086

f
102

v
118 134

..
150 166 182 198 214 230 246

7
007 023

'
039

7
055

G
071

W
087

g
103

w
119 135

151 167 183 199 215 231

..
247

8
008 024

(
040

8
056

H
072

X
088

h
104

x
120

.
136 152 168 184 200 216 232

248

9
009 025

)
041

9
057

I
073

Y
089

i
105

y
121 137

2
153 169 185 201 217 233

..
249

A
010 026

*
042

:
058

J
074

Z
090

j
106

z
122

|
138

3
154 170 186 202 218 234 250

B
011 027

+
043

;
059

K
075

[
091

k
107

{
123 139 155

171 187 203 219 235

..
251

C
012 028

,
044

<
060

L
076

\
092

l
108

|
124 140

156 172 188 204 220 236

..
252

D
013 029

045

=
061

M
077

]
093

m
109

}
125 141 157 173 189 205 221 237

253

E
014 030

.
046

>
062

N
078

^
094

n
110

~
126

142 158

174

O
190 206 222 238

.
254

F
015 031

/
047

?
063

O
079

_
095

o
111 127 143

159

175 191 207 223

'
239

(RSP)

255

Figure 43. 4690 Controller Video Display Character Set - Greece (Based on Code Page 869)

Note: Code points 00H through IFH are non-displayable control characters.

398

IBM 4680 BASIC: Language Reference

Hex

1st 2nd 0

0
000 016 03 2 048

@
064

P
080

.
096

P
11 2

128

1 44

160

.
176

.
192 208

224

.
2 40

Decimal
1

!
001 017 03 3

1
04 9

A
065

Q
081

A
097

Q
11 3

129

145

161

.
177

.
193 209 225

.
241

2
00 2 018

"
034

2
050

B
066

R
08 2

B
098

R
11 4

130

146

162

.
178

.
194

2 10

226

.
242

3
00 3 01 9

#
035

3
051

C
067

S
08 3

C
09 9

S
11 5

131

147

163

.
179

.
195

2 11

227

.
243

4
004

.
020

$
036

4
05 2

D
068

T
084

D
100

T
11 6

132

148

164

.
180

.
196

212

228

.
244

5
005

.
021

%
037

5
05 3

E
06 9

U
085

E
101

U
11 7

133

149

165

181

.
197

.
213

229

.
245

6
006 02 2

&
038

6
054

F
070

V
086

F
102

V
11 8

. A
134

150

.
166

182

198

214

.
2 30

.
246

7
007 02 3

'
03 9

7
055

G
071

W
087

G
103

W
11 9

135

151

.
167

183

199

215 231

.
247

8
008 024

(
040

8
056

H
07 2

X
088

H
104

X
120

136

.
152

168

.
184

.
2 00

216 232

.
248

9
00 9 025

)
041

9
057

I
07 3

Y
08 9

I
105

Y
121

137

1 53

.
169

.
185

.
201

.
217

233

.
249

A
010 026

*
04 2

:
058

J
074

Z
090

J
106

Z
122

138

1 54

.
170

.
186

.
202

.
218

234

.
2 50

B
0 11 027

+
04 3

;
05 9

K
075

[
091

K
107

{
1 23

139

155

.
171

.
187

.
203

.
219

235

.
251

C
01 2 028

,
044

<
060

L
076

\
09 2

L
108 1 24

140

156

.
172

.
188

.
204

.
2 20

Y'
236

.
252

D
01 3 02 9

045

=
061

M
077

]
09 3

M
109

}
125

141

157

.
173

189

.
205

.
221

Y'
237

.
253

E
014 0 30

.
046

>
06 2

N
078 094

N
11 0 126

142

.
158

.
174

.
190

.
206

222

.
238

.
254

F
015 031

/
047

?
06 3

O
07 9

095

O
111

.
127

. A
143

.
159

.
175

.
191

.
207

.
223

.
239 255

Figure 44. Alphanumeric Display Character Set - Multilingual (Based on Code Page 850)

Appendix F. Character Sets For Terminal Printers, Displays, and Controller Video Display

399

Hex
2nd

1st

0
Decimal
000 016 032

0
048

@
064

P
080

.
096

p
112

128

144

160

.
176

.
192

208

224

.
240

1
001 017

!
033

1
049

A
065

Q
081

a
097

q
113

129

145

161

.
177

.
193

209 225

.
241

2
002 018

"
034

2
050

B
066

R
082

b
098

r
114

130

146

162

.
178

.
194

210

226

.
242

3
003 019

#
035

3
051

C
067

S
083

c
099

s
115

131

147

163

.
179

.
195

211

227

.
243

4
004

.
020

$
036

4
052

D
068

T
084

d
100

t
116

132

148

164

.
180

.
196

212

228

.
244

5
005

.
021

%
037