QDOS / SMS Reference Manual Version 4.5 Foreword This is the 4th edition of the QDOS/SMS Reference Manual, a guide and manual for programming the QL as well as QDOS and its many descendants, including especially SMSQ/E. The purpose of this is to have an up-to-date guide to the facilities offered by QDOS and SMSQ/E. This text is based on the original 3rd edition of the manual, as it was published by Jochen Merz and Marcel Kilgus. Except to make changes for error corrections and new insertions, I left much of the original text untouched, even where it was mostly outdated. All of this was made possible by, of course, the original writers of the original texts (Tony Tebby, Jochen Merz, Marcel Kilgus), and thanks go to them. As to the amendments made in this text, I did correct all errors I was able to spot. I also continued to point out the differences between the plain QDOS variety of things and those for SMSQ/E, where appropriate. Included in this edition are the updates for SMSQ/E as they stand now. It is true that this text now contains much information that is specific to SMSQ/E, but this is due to the fact that SMSQ/E is still being developped, which the other OSes aren’t. Thus, there are now sections on the HOME thing, the SMSQ/E style guide etc. In this manual, S*Basic means the QL's SuperBASIC and SMSQ/E's SBASIC. Sometimes you will find reference to assembler key files (e.g. keys_qdos_io). These refer to the keys files as found in the “keys” subdirectory in the SMSQ/E sources. The page numbers in each section and indexes thereto refer to the page numbers of that section. Unfortunately, whilst the initial table of content is “ clickable” (CTRL + left mouse click on a section to go there), this is not true for the indexes. Much care has gone into trying to make sure that the information herein is correct. All remaining errors/omissions are mine. Ideas, corrections and / or suggestions are always welcome. Derek Stewart Wolfgang Lenerz Versions of this manual as of v. 4.1 (all by WL) v. 4.5 Typos, added keys/information about standard hard disk format, Sbasic name table additions for integer REPeat and FOR loop indexes, warning for device driver linkage blocks, IOB.FLIN under SMSQE level 3 drivers converts <CR><LF> to <LF>. v. 4.4 Wrong label for SMS.LSHD corrected in trap description. Mem.achp does not modify A3 in SMSQ/E. Entry regs to vector $11c corrected. Correct registers for vector SB.GTINT and following shown. Current thing parameters completed and some keys don’t exist. On SMSQ/E it is not necessary to have the stack pointer in A1 before calling vector QA.RESRI. Spurious content of D2 & D3 removed from CV.ILDAT and CV.ILDAY. v. 4.3 Added some hyperlinks. IOU.DNAM: corrected spelling of some examples. Explained that opening a directory will open the next higher directory if not found. Typo corrections in the hardware keys section. Added keys for pointer device. v. 4.2 Corrected wrong register on entry to SB.PUTP (was A1 is now A3). IOB.SMUL: the buffer size is a positive word; D1 upper word is destroyed. IOB.FLIN/IOB.SMUM: error return if no LF found corrected, must be ERR.BFFL and not ERR.OVFL; D1 upper word is destroyed. IOU.DNAM correct title for trap. RCNT_GARJ, RCNT_GALL, RCNT_GALJ : return description, parameter description and examples corrected. v. 4.1 Corrected missing source & destination registers when restoring sr in section 10.9 example. The page numbers in the table of contents refer to the page numbers within each section. Table of contents 0. Why this book?...............................................................................................................1 1. About this Guide.............................................................................................................1 2. Introduction to QDOS / SMS / SMSQ/E.........................................................................1 2.1. Memory Map..............................................................................................................1 2.1.1. Principles............................................................................................................2 2.1.2. System Variables................................................................................................2 2.1.3. System Management Tables..............................................................................2 2.1.4. Common Heap Area...........................................................................................2 2.1.5. Free Memory Area.............................................................................................2 2.1.6. S*Basic area.......................................................................................................3 2.1.7. Transient Program Area.....................................................................................3 2.1.8. Resident Procedure Area...................................................................................3 2.2. Calling QDOS/SMS Routines....................................................................................3 2.2.1. Traps...................................................................................................................3 2.2.2. Vectored Routines..............................................................................................4 2.2.3. Atomic Actions....................................................................................................5 2.3. Exception Processing................................................................................................5 2.4. Start-up......................................................................................................................6 3. Machine Code Programming.........................................................................................1 3.1. Jobs...........................................................................................................................1 3.1.1. Normal Jobs.......................................................................................................1 3.1.2. Special Programs...............................................................................................3 3.1.3. Job Control Enhancements [SMSQ/E]...............................................................4 3.2. S*Basic Procedures and Functions...........................................................................5 3.3. Tasks.........................................................................................................................5 3.4. Operating System Extensions...................................................................................5 4. Memory Allocation..........................................................................................................1 4.1. Heap Mechanism.......................................................................................................1 5. Input/ Output on the QL..................................................................................................1 5.1. Serial I/O....................................................................................................................1 5.2. File I/O.......................................................................................................................2 5.3. Screen and Console I/O............................................................................................3 5.3.1. Display Modes....................................................................................................3 5.3.2. Window Properties and Operations...................................................................3 5.3.3. Screen Character Output Operations.................................................................5 5.3.4. Graphics Operations..........................................................................................5 5.3.5. Special Properties of Console Channels............................................................6 5.3.6. Special Keyboard Functions...............................................................................6 5.3.7. Extended Operations [SMSQ/E]...............................................................................6 5.3.8. Display [SMSQ/E]......................................................................................................6 5.3.8.1. New CON driver vectors.............................................................................6 5.3.8.2. New (WMAN) colour format......................................................................14 5.3.8.2.1. Stipple Format....................................................................................14 5.3.8.2.2. 3D Border Format..............................................................................14 5.3.8.3. System palette entries..............................................................................15 5.3.8.4. New Basic Keywords................................................................................16 5.3.8.4.1. Colours...............................................................................................16 5.3.8.4.2. Palette handling.................................................................................17 5.3.8.4.2.1. System palette keywords...........................................................17 5.3.8.4.2.2. Job palette keywords..................................................................17 5.3.8.5. New Move modes.....................................................................................18 5.3.8.5.1. The move modes...............................................................................18