20: DISC ACCESS 260 --------------------------- The AMOS disc commands give you total access to the Amiga's filing system. These can be exploited to create anything from a simple reader to a fully fledged database. Drives and volumes ================== As you know, the Amiga lets you label your discs in a number of different ways. If you're unfamiliar with the CLI, you may find some of these terms a little confusing. So I'll now provide you with a brief explanation of the varoius naming conventions: Drives ------ Floppy Drives: Are assigned names in the following format DFn: n is a single digit which holds the number of your drive. The first floppy drive in your system (usually the internal drive) is known as DF0: then comes drives DF1:, DF2: and DF3: if they're installed. Hard drives: These are specified using: DHn: Where n is the number of your hard drive (or a partition on it). Volumes ------- The Amiga also creates a separate VOLUME name for each individual disc. Tihs label can be substituted for the drive name in any of your AMOS Basic commands. AMOS will automatically check each available drive for the required disc. If it can't be found, you'll get a "drive not mounted" error. Whenever you prepare a new disc from the Workbench, the disc will be assigned the name "Empty". To change this label from the WB, simply click on the RENAME option and enter your new name in the dialogue box provided. This name can be practically any string of characters you like, but it must be terminated with a colon character when it's used in your programs, just like the drive name. Here are some typical volume names for you to examine: AMOS: AMOS_DATA: WARNING! If you create several discs with the same name or swap them around indiscriminately, the Amiga can easily get confused as to which disc you are actually referring to. In these circumstances, you'll need to enter the drive name instead. This will tell AMOS precisely where the required disc can be found on your system. You are strongly recommended to assign a different name to each and every disc you use. This takes no more than a couple of secs from the WB but it does simplify things enormously. Logical devices --------------- Finally, there's also a set of objects known as logical devices. These are used by the Amiga's operating routines to determine the precise position of important systems files such has device handlers or fonts. Each device is normally assigned to a specific directory on the current start-up disc. Here are some examples used by AMOS. FONTS: A directory containing the current fonts. LIBS: Holds a library files required byt the AMOS SAY command. Cross Dos --------- If you've bought the separate CROSSDOS package and installed it into memory, you'll also be able to access IBM or ST format discs within AMOS Basic. These discs are assigned names starting with letters DI. DIn: (where n is the number of your drive) In order to convert your STOS programs to AMOS Basic, you'll need to save them in ASCII format using the FSAVE "*.ASC" option from STOS. Then insert the disc into an Amiga floppy drive that has been mounted by Cross-Dos as an IBM drive. Due to the differences between AMOS and STOS, many STOS progs will require modifying slightly before they will run under AMOS. Directory changing 262 ================== DIR (print out the directory of the current disc) DIR [PATH$] [/W] Lists all the files on the current disc. If the optional path$ is specified, only the files which satisfy a certain set of conditions will be displayed. Any folders in the listing will be distinguished by a leading "*" character. The listing can be halted at any time by pressing the spacebar. To resume, simply press the spacebar once again. Note that if you change discs and try to get a directory listing, you may be presented with a "device not mounted" error. This is because you've removed the current disc without informing AMOS Basic. The solution is to simply update the current directory name to the new using a line like: DIR$="DF0:" before calling DIR /W lists the files in two columns across the screen. This effectively doubles the number of files which can be displayed at any one time. The path string consists of three main elements: [Disc:][Directory/] Filter. Filter defines a set of conditions which should be satisfied for each file in your listing. Normal Text: Each character in your text should match exactly one character in the filename to be displayed. Example: Dir "Music" ( result : Music ) * (asterix): Match any list of letters in your filenames up to the next control character. Dir "M*" As a default, this option will ignore any files which include an MS-DOS type extension. So a file lake: Mad.Asc on the disc would not be listed. . (period): Matches the extension of a filename. It's commonly used in conjunction with the "*" command to list all files with a particular extension. ? (question mark): Matchces a single character at the current position. =DIR$= (change current directory) s$=DIR$ DIR$=s$ DIR$ contains the directory which will be used as the starting point for all future disc operations, such as loading and saving. It's very similar to the CD command from the CLI, with the added advantage of allowing you to read the directory as well as just change it. Examples of the usage: Print Dir$ Dir$="AMOS:Iff/" PARENT (sets the current path up one directory) 264 PARENT The action of PARENT is to load the current directory with the parent of the present folder. By repeatedly using this command, you can quickly get back to your original root directory. SET DIR (set style used by DIR) SET DIR n[,filter$] Sets the style of your directory listings. n is the number of characters ranging from 1-100 which will be displayed in each filename. Note that this setting has NO effect on the actual length of your names. It only changes the way they will be listed on the screen. "filter" is a list of pathnames which are to be EXCLUDED from your directory searches. All filenames that match this filter are completely ignored and will not be displayed as part of your directory. This can be used to supress the annoying ".INFO" files which cointain the icon definitions used by the WB. Note that it's possible to ignore a whole list of filepaths at once. Simply terminate each name with a single "/" character. As a default, the filter is set to: ".INFO/*.INFO/*.*.INFO" Common disc operations 265 ====================== DFREE (disc free space) f=DFREE Returns the amount of free space remaining in bytes on the current disc. MKDIR (create a folder) MKDIR f$ Creates a new folder on the disc with the name f$. Example: MkDir " Df0:TEST" KILL (erase a file from the disc) KILL f$ Deletes the file f$ from the current disc. RENAME (rename a file) RENAME old$ TO new$ Changs the name of a file. Selecting a file 266 ================ =FSEL$ (select a file) f$=FSEL$(path$[,default$][,title1$,title2$]) This function lets you choose your files directly from the disc, using the standard AMOS file selector. "path$" sets a search pattern which determines which files will be displayed in your listing. After you've selected a file, FSEL$ will return either its full pathname, or an empty string "" if you selected QUIT. "default$" chooses a filename to be used as a default. "title1$" and "title2$" are optional text strings which describe a title to be displayed at the top of your file selector. Example: F$=Fsel$("*.IFF","","Load an IFF File") If F$="" Then Edit : Rem Return to editor if no file was chosen. Load IFF F$,0 Running an AMOS program from disc ================================= RUN (execute an AMOS Basic program) RUN [file$] Although it's easy enough to execute your progs straight from the editor, we've also included a separate RUN command. This version of the command without file$ can only be used from direct mode. But the RUN file$ statement may also be placed inside a Basic program. This allows you to chain a list of programs together. Note that when you run a program in this way, the existing program will be removed from memory and any variables will be lost. Any data screens that have been created though, will remain intact, thus allowing intermediate loading screens to be displayed. This command is fantastically useful, as it allows you to split any AMOS game into a number of levels which can be loaded separately from the disc. Each level can now be writeen as a completely independent program. So the only limit to the size of your games is the amount of storage space on the disc! You can therefore produce some massive games with this system! See also PRUN Checking for the existence of a file 267 ==================================== =EXIST (check if specified file exists) flag=EXIST(f$) EXIST checks the current directory for the file f$. If it's found, then a value -1 will be returned, otherwise 0. This EXIST function is capable of checking for the existence of anything from a single file to an entire disc. Example: Print Exist("DF1:"): Rem Has a second drive been connected? =DIR FIRST$ (get first file in the directory satisfying path name) file$=DIR FIRST$(path$) Returns a string containing the name and length of the first file on the disc which satisfies the current search path$. WHen this function is called, the entire directory listing will be loaded into memory. You can now retrieve the name of the next file in the directory using a call to the DIR NEXT$ function. Print Dir First$("*.*") =DIR NEXT$ (get the next file satisfying current path) file$=DIR NEXT$ Returns the next filename in the directory listing created by a previous DIR FIRST$ command. After the last item has been read from this list, a string will be returned containing the empty string "". The entire directory array will now be erased and the memory it consumes will be released for the rest of your Basic program. Here's an example which prints out all the files in the current directory: F$=Dir First$("*.*") While F$<>"" Print F$ : Bell : Wait 30 F$=Dir Next$ Wend See EXAMPLE 20.1 in the manual folder. Disc files 268 ========== Files are just collections of information which have been grouped together in one place on the disc. Each file is assigned its own name which may contain anything from 1 to 255 characters. Before you can use one of these files, you first need to initialize it using either the OPEN IN, OPEN OUT, or APPEND instructions. When you open a file, you assign it to a "channel" number ranging from one to ten. This number will be used in all future disc operations to identify the file you are currently working with. The commodore Amiga supports two types of disc files: Sequential files and Random access files. Sequential files ================ Sequential files are the standard files which are used on the Amiga. The reason for their name is that they only allow you to read your information in the precise sequence it was originally created. This means that if you wanted to change just one piece of the data in the middle of a sequential file, you would have to read in the whole file up and including this value, and then write the entire file back to the disc. AMOS Basic allows you to access sequential files for either writing or reading, but never for both at the same time. Open Out1,"file.seq" Input "What is your name";N$ Print #1,N$ Close 1 This creates a file called FILE.SEQ containing your name. In order to read this information back from the file, type in the lines. Open In 1,"file.seq" Input #1,N$ Print "I remember your name. It's ";N$ Close 1 Notice how both these programs perform three separate operations: * Open the file using OPEN IN, OPEN OUT or APPEND * Access the file with INPUT# or PRINT#. * Close the file with CLOSE. Note that if you forget to do this, any changes to the file will be lost! These three steps need to be completed in exactly this order, every time you access a sequential file. OPEN OUT (open a file for output) 269 OPEN OUT channel,n$ Opens a sequential file for writing. If this file already exists it will be erased. "channel" is a number between 1 and 10 and is used to identify your new file in your subsequent PRINT# commands. n$ is the name of the file to be opened. APPEND (add some information to the of an existing file) APPEND channel,name$ Opens a sequential file for output. If this file exists, the new data is added onto the end. This allows you to expand your files at any time once they've been defined. OPEN IN (open a file for input) OPEN IN channel,f$ Sets up a file for reading. If this file doesn't exist, it will be automatically created. "channel" is a number ranging from 1 to 10 which is used by various INPUT instructions to refer to your open file. CLOSE (close a file) CLOSE n Closes file number n. WARNING! If you forget to close a file after you have finished with it, any changes you've made will be ignored!! PRINT # (print a list of variables to a file or device) PRINT #channel,variable list This command is identical to the normal print instruction, but instead of displaying the information to the screen, it outputs it to a file or output device specified by the channel number. Here's an example: Open Out 1,"TestFile" Print #,"Hello" Close 1 As with PRINT you can abbreviate PRINT # to ? #. INPUT # (input a list of variables from a file or device) Reads information from either a sequential file or a device such as the serial port. Like the standard INPUT command, it enters a list of values and loads them into a set of Basic variables. As always, each value in the list must be separated by a comma. Additionally, every line of data also needs to be terminated by its own character. This is equivalent to the Return you pressed when you entered a line from the keyboard. LINE INPUT # (input a list of variables not separated by a ",") LINE INPUT #channel,variable list LINE INPUT #channel,separators,variable list This function is identical to INPUT #, except that it allows you to separate your list of data using any character you with instead of the standard comma. If the separator is omitted, it's automatically set to the character. When you're reading text, LINE INPUT # is always the preferred choice. That's because the commas found in normal English will be treated as a separator by the INPUT # command. This will confuse your program completely. SET INPUT (set End Of Line characters) SET INPUT c1,c2 Sets the End-Of-Line chars which will be used to terminate a line of data. The Amiga expects a single at the end of each line, whereas most other computers (including the ST) require both a Return and . SO if you try importing your ST files via the serial cable, you'll end up with dozens of spurious Return characters in your files. Fortunately you can sidestep this problem using SET INPUT. c1 and c2 hold a pair of ASCII values which will be used for your separators. If you want to use a single character ,simply load c2 with a negative value such as minus one. Here's a couple of exmples: Set Input 10,-1 : Rem Standard Amiga Format Set Input 13,10 : Rem ST Format =INPUT$ (inputs a number of chars from a device) X$=INPUT$ (f,count) Reads "count" characters from device or file number f. =EOF (test for end of file) flag=EOF (channel) EOF is a useful function which tests to see if the end of a file has been reached at the current reading position. If it has, EOF returns a result of -1, otherwise 0. LOF (length of open file) length=LOF(channel) Returns the length of an open file. It makes no sense to use this function in conjunction with devices other than the disc. POF (variable holding current position of file pointer) pos=POF(channel) The POF function changes the current reading or writing position of an open file, for example: Pof(1)=1000 This sets the read/write position to 1'000 characters past the start of the file. Oddly enough POF can be used in this way to provide a crude form of random access when using sequential files! The reason this works is simply that disc drives are inherently random and all sequential operations are effectively simulated using random access. Random access files =================== Random access files are so called because you can access the information stored on the disc in any random order you like. In order to use these files you first need to understand a little bit of theory. All random access files are composed of units called records, each with their own unique number. These records are in turn split up into a number of separate fields. Every field contains one individual piece of information. When you use sequential files, these fields can be any length you with, as the file will only be read in one direction. Random access files, however, always require you to specify the maximum size of these fields in advance. Supposing you wanted to produce a file containing a list of names and telephone numbers. In this case you could use the fields: Field Max length ----- ---------- SURNAME$ 15 NAME$ 15 CODE$ 10 TEL$ 10 You could now define these fields using a line like: Field #1,15 as SURNAME$,15 as NAME$,10 as CODE$,10 as TEL$ It's important to realize that the strings specified by the FIELD instruction can also be used as normal string variables. This allows you to read and write information to any particular field. For example: SURNAME$="HILL" TEST$=SURNAME$ : Print TEST$ After you've loaded your record with information, you can write it onto the disc using PUT command. Example: Put 1,10 Loads data into record 10 of the file opened on channel 1 Similarly, you can read a record using the GET instruction: Get 1,10 OPEN RANDOM (open a channel to a random file) OPEN RANDOM channel,n$ Opens a random access file called n$ on the current disc. When you're using this instruction, you should always define the record sturcture immediately afterwards using the FIELD$ command. FIELD (define record structure) FIELD channel,length1 AS field1$,length2 AS field2$...... FIELD allows you to define a record which will be used for a random access file. This record can be up to 65535 bytes in length. Field 1,15 as SURNAME$,15 as NAME$,10 as CODE$,10 as TEL$ PUT (output a record to random access file) PUT channel,r PUT moves a record from memory into record number r of a random access file. Before use, the contents of the new record should first be placed in the field strings defined by FIELD, using a statement such as: SURNAME$="HILL" Although you can write existing records in any order you like, you're not allowed to scatter records on the disc totally at random. This means that if you have just created a file you can't type in something like: Put 1,1 Put 1,5 In this case, the PUT 1,5 instruction will generate an error, as there are no records in the file with numbers between 2 and 5. Record 2 must be the next new record in the file, then 3,4... example: Open Random 1,"TELEPHONE" Field 1,30 As NAME$, 30 As Tel$ INDEX=1 Do Input "Enter a name";NAME$ Exit If NAME$="" Input "Enter telephone number";TEL$ Put 1,Index : Inc INDEX Loop Close 1 GET (input a record from a random access file) GET channel,r Reads record number r stored in a random access file opened using OPEN. It then loads this record into the field strings created by FIELD. The strings can now be manipulated in the normal way. Note that you can only use GET to retrieve records which are actually on the disc. If you try to grab a record number which does not exist then an error will be generated. Example: Open Random 1,"TELEPHONE" Field 1,30 As NAME$, 30 As TEL$ Do Input "Enter Record number";INDEX Exit If Index=0 Get 1,INDEX : Print NAME$ : Print TEL$ Loop Close 1 The Printer 274 =========== LLIST (print a part or all of a program on a printer) LLIST Lists the entire program straight to the printer. Try listing some of the Basic programs supplied on the DATA disc. These provide a perfect demonstration of the various programming tehcniques neeked to write your own AMOS Basic games. Feel free to modify them as much as you like. LPRINT (output a list of variables to the printer) LPRINT variable list This is exactly the same as PRINT but sends your data to the printer instead of the screen. Example: Lprint "Hello" See PRINT, USING, PRINT # LDIR (list a directory to the printer) LDIR [PATH$] [W/] Lists the directory of the current disc to the printer. See DIR for more details. External devices ================ OPEN PORT (open a channel to an I/O port) OPEN PORT channel,"PAR:" (open a channel to the Paraller interface) OPEN PORT channel,"SER:" (open a channel to the RS232 port) OPEN PORT channel,"PRT:" (open a channel for the printer) OPEN PORT allows you to communicate with external devices such as the RS232 port. All the standard file commands can be performed as normal, except for commands like LOF or POF which are obviously only relevant to disc operations. Example: Open Port 1,"SER:" For X=0 To 10 Print #1,"AMOS BASIC" Next X Close 1 This program prints out ten lines of text on the device connected to the RS232 port. If your printer uses the paraller port change line 10 to: Open Port 1,"PRT:" Similarly you can input information from a device such as a modem with a line like: Input #1,A$ : Print A$ When accessing these external devices all the normal input statements are available for your use, including INPUT$ and LINE INPUT. =PORT (function to test if channel is waiting) n=PORT(channel) Tests to see if an input device is ready to send you some information. If the device is waiting for you to read it, a value of -1 will be returned by this function, otherwise 0 (false). 21: SCREEN COMPACTION 276 --------------------------- SPACK (screen compaction) SPACK s TO n [tx,ty,bx,by] The SPACK command packs screen s into memory bank n. Everything about the current image is saved, including its mode, screen size, offset and display position. This allows you to recreate your screen in exactly its original state. s is the number of the screen which contains yur image. n holds the number of a memory bank from 1-16. If this bank doesn't currently exist, it will be reserved for you automatically. Your new bank will be stored in FAST memory if it's available, and will be saved along with our Basic program. After you've called this function, the size of your screen can be found using LENGTH. Example: F$=FSEL$("*","","Load a picture") Load Iff F$,0 Spack 0 To 1 Print "The length of your new bank is ";Length(1);" Bytes" Wait Key Screen Close 0 UnPack 1 To 0 : Rem recreate compacted screen You don't, of course have to compact an entire screen with this instruction. The optional parameters let you compress any rectangular section of the display you like. tx,ty now hold the coordinates of the top left corner of this region. bx,by set the position of the bottom right corner. All x coordinates are rounded to the nearest 8 pixel boundary. Note that in order to achieve the maximum memory reduction, SPACK will attempt to compact your image using several different strategies. It will then compress your image using the method which consumes the least amount of memory. One side effect of this efficiency, is that it usually takes around 6 secs to compress one of your images. This is hardly a disadvantage however, as normally the compaction is only required when you are writing your programs. Since each image can be unpacked on the screen in less than a second, there's no risk of interference with the speed of your games. It speeds is of the essence though, you may wish to use the CBLOCK system instead. See the section on Background Graphics for more details. Incidentally, if you compare the compacted size of your files with their original length on the disc, you may be mislead into underestimating the size of the memory reduction. It's important to realize that the vast majority of these files have ALREADY BEEN COMPESSED using the standard IFF compaction routines. So it's rather surprising that AMOS can reduce them by a further 20 % ! Compacted screens are perfect for the titles and hi-score tables required in an arcade game, as they allow you to introduce snazzy screen effects without consuming enormous quantities of memory. They can also be incorporated directly into RPGs and Adventures. PACK (pack a screen) PACK s TO n [tx,ty,bx,by] Compresses screen s into bank number n. Unlike the previous SPACK command, only the image data is compressed. So your compacted screen must always be unpacked directly into an existing screen. Because of the way images are decompressed, there will be a noticeable shimmer effect unless you've previously double buffered your screens. Try to avoid using PACK with single buffered screens. It's much more sensible to call the SPACK system for this purpose. If the optional coordinates are included, only a section of the image will be compressed. Since PACK is fully compatible with the standard AUTOBACK system, it's easy to combine compacted images with moving screens. If you are using Autoback 2 mode, you'll even be able to unpack your images BEHIND existing bobs. It's therefore possible to exploit this instruction in conjunction with SCREEN OFFSET to create fantastic scrolling backgrounds for your games. UNPACK (unpack a compacted screen) Decompresses a screen which has been previously compacted using the SPACK or PACK instructions. Each compaction routine has its own specifix form of the UNPACK command. SPACK ----- UNPACK b TO s Opens a screen s and restores the compacted screen into bank b. If this screen already exists, it will completely replaced by the new image. Once the screen has been unpacked, it will be neatly flicked into view. PACK ---- PACKed screens can be unpacked using two separate instructions. These take an image from a memory bank, and load it straight into an existing screen. WARNING! The destination screen MUST be in exactly the same format as your compacted picture, otherwise you'll get an "illegal function call" error. When you unpack your screens, you may notice that the effect is slightly messy. That's 'cause the PACK command is only really intended for use with the double buffering system. Providing your screen is double buffered, you'll get a delightfully smooth result. UNPACK b Unpacks the screen at its original position UNPACK b,x,y Redraws your image starting at coordinates x,y. If the new image doesnt' fit into the current screen, you'll get an error message. 22: MACHINE CODE 279 --------------------------- Number conversion ----------------- =HEX$ (convert number to hexadecimal) h$=HEX$(v) h$=HEX$(v,n) HEX$ converts the integer v into hexadecimal notation (base 16). It returns a sequence of n hexadecimal characters in the string h$. Example: Print Hex$(Colour(1),3) =BIN$ (convert number to binary string) b$=BIN$(v) b$=BIN$(v,n) Converts a number into binary notation (base 2). Memory manipulation ------------------- =PEEK (get byte address) v=PEEK(address) Returns the 8-bit byte stored at "address" POKE (change byte at address) 280 POKE address,v Copies the number v into "address". v must always lie in the range 0-255. Be warned: POKE can be very dangeroud. If you poke around indiscriminately, you will almost certainly crash the Amiga! =DEEK (get word at address) v=DEEK(address) Reads the two-byte word found at "address". "address" MUST be even or an address error will occur. DOKE (change word at address) DOKE address,value DOKE loads a two-byte number between 0 and 65535 into the memory location at "address". In knowledgeable hands this function caan be very useful. Since even the best of us make mistakes however, you should always save a copy ot your progs to the disc before attempting to use this function in a new routine. Example: Doke Phybase(1)+1000,65535 =LEEK (read a long word at address) v=LEEK(address) Returns the four-byte long word stored at "address". Like DEEK, the address used with this function must always be EVEN. If bit 31 of the return value is set to 1, v will be diplsyed as a negative number. This isn't a bug. It's just a side effect of the way AMOS deals with numbers. LOKE (change long word at address) 281 LOKE address,n LOKE copies the four-byte number into "address". Example: Loke Phybase(1)+10000,$FFFFFFFF Indiscriminate use of this function can lead to the Amiga crashing horribly, so take care. =VARPTR (get address of a variable) address=VARPTR(variable) Returns the address in memory of a Basic variable. Each type of variable is stored using its own individual format: Integers: VARPTR finds the address of the four bytes containing the contents of your variable. Floating points: VARPTR returns the location of four bytes which hold the value of the variable in the IEEE single precision format Strings: The VARPRT address points to the first character of the string. Since AMOS Basic doesn't end its strings with a CHR$(0), you must obtain the length of the string using something like: DEEK(VARPTR(A$)-2), where A$ is the name of your variable. You could also use LEN(A$) of couse. COPY (copy a memory block) COPY start,finish TO destination This command is used to rapidly move large sections of the Amiga's memory from one place to another. "start" and "finish" are the addresses of the first and last bytes of your data respectively. "destination" points to a memory area which will be loaded with your new data. All these addresses MUST be even, or you'll get an address error. FILL (fill memory block with a longword) 282 FILL start TO finish, pattern Fills a selected region of memory with the four bytes held in "pattern". "start" and "finish" determine the position and size of the block which is to be filled. These addresses MUST BE EVEN! "pattern" is a long word containg a four byte fill pettern. This will be copied into each group of memory locations between "start" and "finish". =HUNT (find a string in memory) f=HUNT(start TO finish, s$) Searches through the Amiga's memory for the sequence of characters held in s$. "start" is the address of the first byte in memory to be searched, and "finish" is the address of the last. On completion, f will hold either 0 (in the string in a$ was not found) or the location of f$. Bitwise operations ------------------ ROL (rotate left) ROL.B n,v ROL.W n,v ROL.L n,v ROL is a Basic version of the ROL instruction found in 68000 assembly language. The effect is to take the binary representation of a number in v, and rotate it left by exactly n places. If v is a single variable, then the number to be rotated is taken directly from v. But if v is an expression, then it's treated as the address of your number instead. Example: A=8 Ror 1,A Print A ( result: 4 ) ROR is capable of dividing any positive value by a power of two. The resulting calculation will be performed much faster than the equivalent "/" operation. ROR (rotate right) 283 This is very similar to ROL but rotates the number in the opposite direction. =BTST (test a bit) 284 Tests the binary digit at position n in the variable v. If v is an expression, it will be used as the address of the bit which is to be checked. In this case n will be automatically ANDed with 7 before proceeding. After BTST has been called, b will be loaded with -1 if the bit at position n is set to 1, otherwise it will be 0. BSET (set a bit to 1) BSET n,v Sets the bit at position n to 1 in the variable v. BCHG (change a bit) BCHG n,v Changes bit number n in the variable v. If this bit is currently 1 then the new value will be a zero, and vice versa. BCLR (clear a bit) 285 BCLR n,v Clears bit number n in variable v by setting it to zero. Like all the bitwise operations, if v is an expression, then it will be used as the location of your data in memory. Using assembly language ----------------------- AMOS Basic includes special facilities which allow you to combine assembly language routines with your Basic programs. It's worth emphasising that, because of the sheer power of the AMOS system, machine code is only rarely useful. We've added these features solely for existing assembly language programmers who may wish to optimize their Basic programs with the occasional bit of machine code. PLOAD (reserve a memory bank for some machine code) PLOAD "filename",bank Reserves a memory bank and loads it with a machine-code program from the disc. "bank" is the number of a memory bank which is to be reserved for your program. If it's negative, then the bank will be calculated using the absolute value of this number, and the required memory area will be allocated from CHIP mem. Once you've loaded a program in this way, you can save it on the disc as an normal ".ABK" file. Since the banks created by this function are permanent, it will also be saved directly with your AMOS programs. Your program must consist of a machine code file in the standard Amiga format. In practice, it can contain practically anything you like, with the following restrictions: * The code MUST be totally relocatable. * Only the CODE chunck of your program will be loaded * The program must be terminated by a single RTS instruction CALL (call a machine-code program) CALL address[,params] CALL bank[,params] Executes an assembly language program held in the AMiga's memory. "addrss" can be either the absolute location of your code, or the number of an AMOS memory bank which has been previously created with PLOAD. On entry to your program, registers D0 to D7 and A0 to A2 will be loaded from the values stored in the DREG and AREG arrays. Your assembly language program can now change any 68000 register it likes. At the start the routine, register A3 will point to the optional parameter list, and A5 will contain the address of the main AMOS data area. When your program's finished, you can return to Basic with just a simple RTS instruction. "params" is a list of parameters which will be pushed onto the A3 stack by the CALL command. These parameters need to be removed in REVERSE order. So the last value you entered into the instruction wlil be the first on to the stack. Depending on the type of your parameters, the values referenced by A3 will be in one of the following three formats: Integer : Holds a long word containing a normal AMOS integer. F.Point : Contains a floating point number in IEEE single prec. format. String : Sortes the address of the string. All strings start with a single word containing their length. WARNING! Never poke directly into a string! When a string is initialised to a constant the string address will point to the original assignment statement inside the current program listing! So if you change this value, you'll affect your original source code. This is obviously extremely unwise, and should be avoided. See EXAMPLE 21.1 =AREG= (variable used to pass information to the 68000's address registers) a=AREG(r) AREG(r)=a AREG is an array of six PSEUDO variables which are used to hold a copy of the first six of the 68000's address registers. r can range from 0 to 6 and indicates the number of the address register which is to be affected. Whenever the CALL command is executed, the contents of this array are loaded automatically into address registers A0 to A2. At the end of the function, they are then saved back with any new information which has been placed in the appropriate registers. =DREG= (variable used to pass information to the 68000's data registers) d=DREG(r) DREG(r)=d This is an array of eight integers wihch holds a copy of the contents of the 68000 data registers. r refers to the register number and can range from 0 to 7 for D1 to D7 respectively. Accessing the system libraries 287 ============================== AMOS also allows you to call up most of the Amiga's internal system libraries directly from the ROM. These aren't particularly useful, since all the really interesting calls have already been built into AMOS! Don't use these routines unless you know precisely what you're doing. The Amiga is notoriously difficult to program, and it's all to easy to crash the system and generate the infamous GURU error by mistake. =DOSCALL (DOS library) r=DOSCALL(function) Executes a function directly from the DOS library. "function" is the offset to the appropriate function. See the Amiga ROM Kernel Manuals for more details. Before using this function, you'll need to set some of the control registers in D0 to D7 and A0 to A2 using the AREG and DREG functions. WHen the routine exits back to Basic, the contents of D0 are returned in r. Note: The return values will not be loaded into DREG and AREG. =EXECALL (EXEC library) r=EXECALL(function) Performs a call to the Amiga's EXEC library. On entry, D0 to D7 and A0 to A2 are loaded with the control settings from the DREG and AREG arrays. r is returned holding the contents of D0. =GFXCALL (Graphics library) r=GFXCALL(function) Calls a routine from the graphics library using the control values stored in the DREG and AREG arrays. =INTCALL (Intuition library) r=INTCALL(function) Executes a command from the Intuition library. As usual the control values are loaded from DREG and AREG arrays, and r holds the result of the call. Since AMOS doesn't use the standard intuition routine, this function is especially dangerous. Only call it if you are already familiar with the Amiga's intuition library. Inside AMOS Basic 288 ================= In order to provide full access to the inner workings of the AMOS system for developers, we've included several "hooks" into the various data areas. These are not intended for the casual programmer, but they do enable adbanved users to create their own AMOS utilities. =SCREEN BASE (get screen table) table=SCREEN BASE Returns the base address of the internal table used to hold the number and position of your AMOS screens. See EXAMPLE 21.2 =SPRITE BASE (get sprite table) table=SPRITE BASE(n) Provides the address of the internal data list for sprite n. If this sprite doesn't exist, then the address of the table will be zero. Negative values for n return the address of the optional MASK associated with your sprite. "table" will now contain one of three possible values, depending on the status of this mask: table < 0 Indicates that there's no mask for this sprite at all table = 0 Sprite n does have a mask, but it hasn't been generated table > 0 This is the address of the Mask in memory. The first long word of this area holds the length of the mask, and the next is followed by the actual definition. See EXAMPLE 21.3 =ICON BSE (get icon base) table=ICON BASE(n) Returns the address for icon n. The format of this information is exactly the same as the previous SPRITE BASE function. 23: COMMAND INDEX 289 --------------------------- ABS ..................125 ACOS .................112 ADD .................. 39 AMAL .................186 AMAL FREEZE ..........193 AMAL ON/OFF ..........193 AMALERR ..............195 AMPLAY ...............193 AMREG ................193 ANIM .................205 ANIM FREEZE ..........206 ANIM ON/OFF ..........206 APPEAR ...............136 APPEND ...............269 AREG .................286 ASC .................. 58 AT ................... 91 ATAN .................113 AUTO VIEW ON/OFF .....121 AUTOBACK .............158 BANK TO MENU .........221 BAR .................. 68 BCHG .................284 BCLR .................285 BELL .................234 BGRAB ................ 31 BIN$ .................279 BLOAD ................ 51 BOB ..................155 BOB CLEAR ............161 BOB COL ..............170 BOB DRAW .............161 BOB OFF ..............163 BOB UPDATE ...........161 BOBSPRITE COL ........170 BOOM .................233 BORDER ...............101 BORDER$ .............. 98 BOX .................. 65 BREAK ON/OFF ......... 83 BSAVE ................ 51 BSET .................284 BTST .................284 CALL .................285 CDOWN ................ 93 CDOWN$ ............... 93 CENTRE ............... 96 CHANAN ...............195 CHANGE MOUSE .........165 CHANMV ...............195 CHANNEL ..............197 CHOICE ...........214,216 CHR$ ................. 58 CIRCLE ............... 66 CLEAR KEY ............251 CLEFT ................ 94 CLEFT$ ............... 94 CLINE ................ 96 CLIP ................. 71 CLOSE ................269 CLOSE EDITOR ......... 30 CLOSE WORKBENCH ...... 30 CLS ..................131 CLW ..................103 CMOVE ................ 90 COL ..................170 COLOUR ............... 62 COP LOGIC ............144 COP MOVE .............143 COP MOVEL ............143 COP RESET ............144 COP WAIT .............143 COPPER OFF ...........143 COPPER ON ............143 COPY .................281 COS ..................112 CRIGHT ............... 94 CRIGHT$ .............. 94 CUP .................. 93 CUP$ ................. 93 CURS ON/OFF .......... 95 CURS PEN ............. 96 DATA .................256 DEC .................. 39 DEEK .................280 DEF FN ...............118 DEF SCROLL ...........133 DEFAULT ..............121 DEFAULT PALETTE ......131 DEGREE ...............111 DEL BLOCK ............210 DEL CBLOCK ...........211 DEL ICON .............209 DEL WAVE .............244 DFREE ................265 DIM .................. 36 DIR ..................262 DIR FIRST$ ...........267 DIR NEXT$ ............267 DIR$ .................263 DIRECT ............... 80 DO...LOOP ............ 79 DOKE .................280 DOSCALL ..............287 DOUBLE BUFFER ........156 DRAW ................. 65 DREG .................286 DUAL PLAYFIELD .......127 DUAL PRIORITY ........128 EDIT ................. 80 ELLIPSE .............. 66 END .................. 81 EOF ..................271 ERASE ................ 50 ERRN ................. 86 ERROR ................ 86 EVERY n GOSUB ........ 82 EVERY n PROC ......... 82 EVERY ON/OFF ......... 82 EXECALL ..............287 EXIST ................267 EXIT ................. 79 EXIT IF .............. 80 EXP ..................114 FADE .................137 FALSE ................259 FIELD ................272 FILL .................383 FIRE .................169 FIX ..................117 FLASH ................138 FLIP$ ................ 57 FN ...................118 FONT$ ................107 FOR...NEXT ........... 77 FREE ................. 53 FSEL$ ................266 GET ..................273 GET BLOCK ............209 GET BOB ..............163 GET CBLOCK ...........211 GET DISC FONTS .......107 GET FONTS ............106 GET ICON .............208 GET ICON PALETTE .....208 GET PALETTE ..........131 GET ROM FONTS ........107 GET SPRITE ...........107 GET SPRITE PALETTE ...151 GFXCALL ..............151 GLOBAL ............... 46 GOSUB ................ 46 GOTO ................. 74 GR LOCATE ............ 73 GR WRITING ........... 70 HCOS ................. 70 HEX$ .................279 HIDE .................279 HOME ................. 92 HOT SPOT ............. 92 SCROLL ............... 98 HSIN ................. 98 HSLIDER ..............104 HTAN .................104 HUNT .................282 HZONE ................173 I BOB ................162 I SPRITE .............154 ICON BASE ............154 IF..THEN..[ELSE] ..... 75 IF..[ELSE]..ENDIF .... 76 INC .................. 39 INK .................. 61 INKEY$ ...............249 INPUT ................252 INPUT # ..............269 INPUT$ ...............271 INPUT$() .............250 INSTR ................ 56 INT ..................115 INTCALL ..............287 INVERSE ON/OFF ....... 88 JDOWN ................169 JLEFT ................168 JOY ..................168 JRIGHT ...............168 JUP ..................168 KEY SHIFT ............250 KEY SPEED ............251 KEY STATE ............250 KILL .................265 LDIR .................274 LED ..................248 LEEK .................280 LEFT$ ................ 58 LEN .................. 58 LENGTH ............... 50 LIMIT BOB ............162 LIMIT MOUSE ..........167 LINE INPUT ...........253 LINE INPUT # .........253 LIST BANK ............ 49 LLIST ................274 LN ...................114 LOAD ................. 51 LOAD IFF .............124 LOCATE ............... 90 LOF ..................271 LOG ..................114 LOGBASE ..............136 LOGIC ................136 LOKE .................281 LOWER$ ............... 57 LPRINT ...............274 MAKE ICON MASK .......209 MAKE MASK ............172 MATCH ................ 60 MAX ..................116 MEMORIZE X/Y ......... 95 MENU$ ............212,215 MENU ACTIVE ..........229 MENU BAR .............228 MENU BASE ............231 MENU CALC ............222 MENU CALLED ..........226 MENU DEL .............221 MENU INACTIVE ........229 MENU ITEM MOVABLE ....230 MENU ITEM STATIC .....230 MENU KEY .............219 MENU LINE ............227 MENU LINKED ..........231 MENU MOUSE ...........232 MENU MOVABLE .........229 MENU ON/OFF ..213,220,221 MENU ONCE ............227 MENU SEPARATE ........231 MENU STATIC ..........230 MENU TLINE ...........228 MENU TO BANK .........221 MENU X ...............231 MENU Y ...............231 MID$ ................. 54 MIN ..................117 MKDIR ................265 MOUSE CLICK ..........166 MOUSE KEY ............166 MOUSE ZONE ...........173 MOVE FREEZE ..........205 MOVE ON/OFF ..........205 MOVE X ...............203 MOVE Y ...............204 MOVON ................205 MUSIC ................238 MUSIC OFF ............238 MUSIC STOP ...........238 MVOLUME ..............239 NO MASK ..............158 NOISE ................244 NOT ..................258 ON ERROR GOTO ........ 83 ON ERROR PROC ........ 84 ON MENU DEL ..........218 ON MENU GOSUB ........218 ON MENU GOTO .........218 ON MENU ON/OFF .......218 ON MENU PROC ......... 81 ON...GOSUB ........... 81 ON...GOTO ............ 81 ON...PROC ............ 81 OPEN IN ..............269 OPEN OUT .............269 OPEN PORT ............274 OPEN RANDOM ..........272 PACK .................277 PAINT ................ 67 PALETTE .............. 63 PAPER ................ 87 PAPER$ ............... 88 PARAM ................ 46 PARENT ...............264 PASTE BOB ............163 PASTE ICON ...........207 PEEK .................279 PEN .................. 87 PEN$ ................. 87 PHYBASE ..............135 PHYSIC ...............135 PI# ..................240 PLAY .................240 PLOAD ................285 PLOT ................. 64 POF ..................271 POINT ................ 64 POKE .................280 POLYGON .............. 68 POLYLINE ............. 65 POP .................. 75 POP PROC ............. 47 PORT .................275 PRG FIRST$ ........... 31 PRG NEXT$ ............ 31 PRINT # ..............269 PRINT / ? ............254 PRIORITY ON/OFF ......174 PROCEDURE ............ 42 PRUN ................. 31 PSEL$ ................ 32 PUT ..................273 PUT BLOCK ............210 PUT BOB ..............163 PUT CBLOCK ...........211 PUT KEY ..............252 RADIAN ...............111 RAIN .................141 RAINBOW ..............141 RANDOMIZE ............116 READ .................256 REM / ' ..............255 REMEMBER X/Y ......... 96 RENAME ...............265 REPEAT$ .............. 97 REPEAT...UNTIL ....... 78 RESERVE .............. 49 RESERVE ZONE .........172 RESET ZONE ...........174 RESTORE ..............257 RESUME ............... 85 RETURN ............... 74 RIGHT$ ............... 54 RND ..................115 ROL ..................282 ROR ..................283 RUN ..................266 SAM BANK .............236 SAM LOOP .............237 SAM PLAY .............235 SAM RAW ..............236 SAMPLE ...............244 SAVE ................. 51 SAVE IFF .............124 SAY ..................247 SCAN$ ................ 29 SCANCODE .............249 SCIN .................130 SCREEN ...............129 SCREEN BASE ..........288 SCREEN CLONE .........127 SCREEN CLOSE .........121 SCREEN COLOUR ........130 SCREEN COPY ..........132 SCREEN DISPLAY .......125 SCREEN HEIGHT ........130 SCREEN HIDE ..........129 SCREEN OFFSET ........126 SCREEN OPEN ..........119 SCREEN SHOW ..........130 SCREEN SWAP ..........134 SCREEN TO BACK .......129 SCREEN TO FRONT ......129 SCREEN WIDTH .........130 SCROLL ...............134 SET BOB ..............157 SET BUFFER ........... 53 SET CURS ............. 95 SET DIR ..............264 SET ENVEL ............245 SET FONT .............108 SET INPUT ............270 STE LINE ............. 67 SET MENU .............232 SET PAINT ............ 70 SET PATTERN .......... 69 SET RAINBOW ..........139 SET SLIDER ...........104 SET SPRITE BUFFER ....151 SET TAB .............. 97 SET TALK .............247 SET TEMPRAS .......... 71 SET TEXT .............108 SET WAVE .............241 SET ZONE .............172 SGN ..................115 SHADE ON/OFF ......... 88 SHARED ............... 45 SHIFT DOWN ...........139 SHIFT OFF ............139 SHIFT UP .............138 SHOOT ................233 SHOW .................165 SIN ..................111 SORT ................. 59 SPACE$ ............... 57 SPACK ................276 SPRITE ...............145 SPRITE BASE ..........288 SPRITE COL ...........169 SPRITE OFF ...........152 SPRITEBOB COL ........170 SPRITE UPDATE ........152 SQR ..................114 START ................ 50 STR$ ................. 59 STRING$ .............. 58 SWAP .................117 SYNCHRO ..............202 TAB$ ................. 97 TAN ..................112 TEMPO ................239 TEXT .................106 TEXT BASE ............109 TEXT LENGTH ..........109 TEXT STYLE ...........109 TIMER ................258 TITLE BOTTOM .........101 TITLE TOP ............101 TRUE .................258 UNDER ON/OFF ......... 89 UNPACK ...............277 UPDATE ...............175 UPDATE EVERY .........201 UPPER$ ............... 57 USING ................254 VAL .................. 59 VARPTR ...............281 VIEW .................121 VOICE ................239 VOLUME ...............235 VSCROLL .............. 99 VSLIDER ..............104 VUMETER ..............240 WAIT .................258 WAIT KEY .............259 WAIT VBL .............136 WAVE .................243 WHILE...WEND ......... 78 WIND CLOSE ...........102 WIND MOVE ............102 WIND SIZE ............103 WINDON ...............102 WINDOPEN ............. 99 WINDOW ...............102 WINDOW FONT ..........100 WINDSAVE .............100 WRITING .............. 89 X BOB ................162 X GRAPHIC ............ 92 X HARD ...............154 X MOUSE ..............167 X SCREEN .............153 X SPRITE .............152 XCURS ................ 94 XGR .................. 64 XTEXT ................ 91 Y BOB ................162 Y GRAPHIC ............ 92 Y HARD ...............154 Y MOUSE ..............167 Y SCREEN .............153 Y SPRITE .............153