DRAliON32 programmer's reference guide DRA&ON32 -,,ragrammer•s reference g11ide iiW_is MELBOURNE HOUSE Published in the United Kingdom by: Melbourne House (Publishers) Ltd., Melbourne House, Church Yard, Tring, Hertfordshire HP23 5LU, ISBN 0-86161- 134-9 Published in Australia by: Melbourne House (Australia) Ply. Ltd., Suite 4, 75 Palmerston Crescent, South Melbourne, Victoria, 3205, National Library of Australia Card Number and ISBN 0-86759-136-6 Published in the United States of America by: Melbourne House Software Inc., 347 Reedwood Drive, Nashville TN 37217. This book was edited by John Vander Reyden. With contributions from Denver Jeans. Copyright (c) 1983 Beam Software All rights reserved. This book is copyright. No part of this book may be copied or stored by any means whatsoever whether mechanical or electronic, except for private or study use as defined in the Copyright Act. All enquiries should be addressed to the publishers Printed in Hong Kong by ColorcraftLtd. 1st Edition Contents Introduction . 1 What's included . .. .. ................ 1 How to use this guide . .. ... .. .. ... .. .... .. .. .. 2 Chapter 1 BASIC ...................................... ......... 3 Constants . .. .. .... .. .. .. .. .. .. .... .. 3 Variables . 4 Arrays .. ... .... .. .... .. 4 Conversion . .. .. 5 Lines . .. .. .. .. .. .. .. .. .. 7 BASIC Commands ...................................... 7 BASIC Functions ....................... 28 Errors in BASIC ........................ 35 Chapter 2 GRAPHICS . .. .. ............. 36 Pixels and Resolution .... 37 Modes ............. 37 Video Memory . .. ................ 39 Lo Resolution Graphics .............•................. 42 CLS . .. .. .. ........................... 43 SET/RESET .... ....................... 43 Graphicsusing STRINGs ........................... 43 Hi Resolution Graphics . .. ..................... 46 Initialising commands .............................. 46 Producing Graphics . ................... 48 Assembler/Machine Code Graphics .................... 54 Graphics Modes .......•................. 55 Chapter 3 SOUND .... .. ........... 70 Example programs ..... .................. 72 Chapter 4 MACHINE CODE ... 81 What is Machine Code . ..................... 81 The CPU . .. .. .. .. .. .. .. ... ... ... 82 Registers .. 84 Addressing Modes ................... 85 Using M/C programs on the DRAGON ...... 90 Handy ROM Routines ...... ........................ 93 Handy Memory Locations .• . • . .. .. .. 96 Now BASIC Stores Variables ... 97 String Stack ....... 98 How Numerics are stored in the Variable Block ......... 98 How to access BASIC variables from Machine Language programs .. 99 Chapter5 PERIPHERALS ...................................... 107 Joysticks .. .. .. .. .... 1 01 Printer ........................................ 1 01 Cassette . .. .. .. .. .. ........ 1 02 Monitor/TV ...................................... 102 Edge Connector ................................ 103 Chapters HANDY ROUTINES and TIPS .......................... 104 Speeding things up ............................... 1 04 Disable/Enable break key ......................... 105 Auto Key Repeat .. .. .. 106 Reading Two Keys at Once ... 107 Recovering a Program after a NEW command ... 107 Merge . ... 108 Redefining BASIC Keywords . .. .. .. ... 109 Page Swapping . .. .. .. 109 Various Circles .•.............................. 110 Lines .. ................................ 112 Scrolls .......................................... 112 Appendix A Basic Keywords .. 120 Basic Symbols .. 122 Appendix B Error Messages .... 123 AppendixC Memory Map .. 125 AppendixD Colour Codes .. 126 Colour-set Table ...... 127 AppendixE Character Codes (CHA$ & ASC) . 128 AppendixF Print@GRID . 129 AppendixG ASCII Codes ..... ... 130 Appendix H Character Codes (PEEK & POKE) 132 Appendix I Base Conversions ..... 133 AppendixJ 6809 Instruction Set .... 137 INTRODUCTION This book has been developed as a reference source for people like you, who want to get the most out their DRAGON. It contains the information you need for your programs, from the simplest exercises right though to complex business or game applications. The DRAGON PROGRAMMERS GUIDE is designed so that everyone from the beginning BASIC programmer to the professional experienced 6809 machine language programmer can get information to develop their own creative programs. At the same time this book shows you just what your DRAGON can do. This PROGRAMMERS GUIDE is not designed to teach the BASIC programming language to a beginner but as a reference to the DRAGON which includes the DRAGON's BASIC language. If you have not already done some programming, I suggest that you read the other book in this series, THE COMPLETE DRAGON BASIC COURSE, which will teach you the BASIC language. The DRAGON PROGRAMMER'S GUIDE is just that; a guide. Like most reference books, your ability to apply the information depends on your knowledge of the subject. In other words, if you are a novice programmer you will not be able to use all the facts and figures in this book until your knowledge and experience increases. What is in this book is a considerable amount of valuable programming reference material written in easy to read English with the programming jargon explained. On the other hand, the programming professional will find all the information needed to use the capabilities of the DRAGON 32 effectively. WHAT'S INCLUDED? • Complete "BASIC dictionary" includes the DRAGON BASIC language commands, statements and functions, a detailed description of each word and examples on how to use it, even the average time it takes to execute each one, useful for "time critical" game programs. • An introduction to machine code programming and how to use machine code programs from BASIC. • A complete listing of the 6809 instruction set. • The peripherals chapter (Chapter 5) shows how the DRAGON can communicate with the outside world via its ports. • Useful routines and memory locations you can access from both BASIC and machine code • BASIC and machine code routines for you to type in yourself which will make your program even more powerfuland user friendly. HOW TO USE THIS GUIDE Throughout this manual certain conventional notations are used to describe the syntax (programming sentence structure) of BASIC commands to show both the recuired and the optional parts for each keyword. The rules to use for interpreting statments' syntax are as follows: • BASIC keywords are shown in capital letters. They must appear where shown in the statement, entered and spelled exactly as shown. • Parameter names are shown enclosed in square brackets ( [ ] ) and these must be substituted with values. These can be either a single constant, a single variable name or any complex expression unless otherwisestated. • TIME - Most commands have a time quoted for them at the end of their description. This is the approximate average time that the command takes to run, measured in seconds. It is included to enable comparison of different ways of performing a certain routine when programming time­ critical programs. 2 CHAPTER 1 BASIC This chapter is a reference guide to the DRAGON 32's BASIC. If you are new to programming then I suggest that you use a book like THE COMPLETE DRAGON BASIC COURSE which is written for people who don't have a lot of BASIC programming experience. If you are a competent programmer but have not used BASIC before, this chapter is probably sufficient to teach you the basics of the BASIC language. CONSTANTS DRAGON BASIC has two fundamental types of constants; string and numeric. String constants are made up of alphanumeric characters and are enclosed in quotation marks ( "" ). A character string can be up to 255 characters long. A string which does not contain any characters is called a "null string". Examples: "DRAGON32 " "!!23!" "m" "" - null string Numeric constants can have three formats: a)DECIMAL These can contain the digits O through 9, a decimal point ( . ) and a sign ( +or-). Example: -2783.796, 1200 Decimal numbers can also be stored in EXPONENTIAL FORMAT and are automatically displayed in this format for numbers greater than1 ,000 million and less than 1 thousandth. The highest value the exponent can take is 38; actually the largest number is about 1.1 x 1038 • The mantissa has a maximum of 9 digits. Example: 9.76E13, -9.67E-2 1 b) HEXIDECIMAL These can contain the digits O through to 9, A through to F and a sign ( + or- ), where: A represents 1 0 B represents 11 C represents 12 3 D represents 13 E represents 14 F represents 15 "&H" is placed at the start of the number to indicate that it is in hexadecimal format. If a sign is specified then it must come before "&H". Example: &H1A00, -&H1A0F c) OCTAL These can contain 0 through to 7 and a sign ( + or - ). "&" or "& O" is placed at the start of the number to indicate that it is an octal number. If a sign is specified it must be placed at the very head of the number. Example: &0707, -&0707, &147 VARIABLES Again, the DRAGON has two typesof variables, string and numeric, the only difference being that all numeric variables are floating point. A variable. need not be declared unless it is an array with more than 10 elements. Variable names have the following rules: a) The first character must be alphabetic (A - Z) followed by alphanumeric characters. b) Up to 255 characters may be used as a name but only the first 2 are used to identify the variable. Therefore, SNAKE and SNAP are considered the same by the DRAGON. c) Variable names cannot start with a BASIC keyword. Examples: