All in retrieval into California is liablefor ifit possibility right this obligation notify

Texte intégral

(1)

(2) TurboDOS 1.3 Z80 Programmer's Guide. Copyright Notice. NOTICES. Copyright 1983 rights reserved.. by. Software 2000, Inc. All part of this publication be reproduced, may transmitted, transcribed, stored in a retrieval system, or translated into any language or computer language, in any form raechaor by any means, electronic, nical, magnetic, optical, chemical, manual or otherwise, without the prior written permission of Software 2000, Inc., 1127 Hetrick Avenue, Arroyo Grande, California 93420, No. U.S.A.. Trademark. Disclaimer. Notice. TurboDOS a trademark of Software 2000, Inc., and has been registered in the United States and i.n most major countries of the CP/hl, CP/bl Plus, and MP/M free world. are trademarks of Digital Research.. is. Software 2000, Inc., makes no representations warranties with respect to the contents of and specifically this publication, disclaims any implied warranties of merchantability or fitness for any particular purpose. Software 2000, Inc., shall under no circumstances be damages liable for consequential or related has been notified expenses, even of the if it such damages. of possibility or. Software 2000, Inc., reserves the right to revise this publication from time to time without obligation to notify any person of such revision..

(3) TurboDOS 1.3 Z80 Programmer's Guide. ABOUT THIS Purpose. ABOUT. THIS. GUIDE. GUIDE We've. designed this Z8Q ProqrawlTler's to provide the information you need to know in order to write application software to run on Z80-based. microcomputers. under. the. TurboDOS. This document operating system. explains the theory of operation of each internal facility of TurboDOS. describes in detail It also that each TurboDOS function may be called by an application program. Assumptions. In writing this guide, we've assumed that you are an experienced assembly-language programmer writing application programs for the Z80 TurboDOS environment. We've also assumed you have read the Tl1rhopo,q and are therefore familiar with the commands and external features of TurboDOS.. 4=!m§gjjjA=. Organization. This guide starts with a section that describes the fundamentals of the TurboDOS environment, with emphasis on the organization of memory and the interface and flow of control between application programs and the operating system. The next. nals in system,. two more and. sections explain TurboDOS interOne describes the detail. file the other describes serial I/O.. There are two each TurboDOS. reference sections that explain function call in detail. One section describes CP/M-conipatible functions by TurboDOS, supported while the other describes functions unique to TurboDOS. Appendices describe. debugging tool called the function calls in tabular forní. Finally, there is an alphabetical index. MONITOR, condensed. and. summarize. a.

(4) TABLE. TurboDOS 1.3 Z80 Programmer's Guide. FUNDAMENTALS. Memory Organization Non-Banked 6íentory Banked Memory , . Program Interface .. C-Functions T-Functions Termination. .. .. .. .. .. .. File Sharing File Locks Record. Locks. Changes. . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . .. . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . .. .. .. .. .. .. .. .. .. .. . .. . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. . .. .. .. .. . .. .. .. . .. .. .. .. .. .. .. .. .. . . . Modes. .. .. .. .. .. .. .. .. .. .. . .. .. .. . .. .. .. .. .. .. .. .. .. .. .. .. . . .. .. . . .. . . . .. .. .. .. .. .. .. .. .. .. .. .. .. Compatibility Files . . . Optimization Buffer Management Error Handling. . .. .. FIFO Load. Media. . .. .. .. Numbers. . .. .. Disk Capacity . . . Disk Organization . Directory Formats . File Organization . File Operations . . Naming Files . . . Special File Names File Control Block File Attributes . . User. . .. ,. Tail Parsing . Command Strings Batch processing Automatic Loading Base Page Layout SYSTEM. . .. .. Table BIOS Branch Comnand Processing Command Prompt . Command Format .. FILE. . .. CONTENTS. OF. .. .. .. .. .. .. .. .. . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . .. . . .. . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. l-l. l-2 l-3. l-4 l-4 l-6. 1_6. l-7. l-8 l-8 l-8 l-9 l-9. l—10. l-10. l-ll. 2-l. 2-2 2-3 2-3 2-4 2-6 2-7 2-7 2-9 2-lO 2-lO. 2-ll. 2-12 2-13 2-15 2-16 2-17 2-18 2-18.

(5) 1.3. TurboDOS. '. SERIAL. I/O. C—FUNCTIONS. TABLE. Z80 Guide. CONTENTS. OF. (Continued). I/O . . . . . Console I/O . Raw Console I/O . . String Console I/O Attention Requests Comm Channel I/O . . Printer Output . . . Console. Basic. Basic Printing . Control Functions. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. Introduction . . . . . . . . . . . C-Function O: System Reset . . . . C-Function l: Console Input . . . . . . . C-Function 2: Console Output C-Function 3: Raw Console Input . . C-Function 4: Raw Console Output . C-Function 5: List Output . . . . . C-Function 6: Direct Console I/O . . C-Function 7: Get I/O Byte . . . C-Function 8: Set I/O Byte . . . . C-Function 9: print String . . . . C-Function IQ: Read Console Buffer C-Function II: Get Console Status . C-Function 12: Return Version . . . . C-Function 13: Reset Disk System C-Function 14: Select Disk . . . . C-Function 15: Open File . . . . . C—Function 16: Close File . . . . . C-Function 17: Search for First . . C-Function 18: Search for Next . . C-Function 19: Delete File . . . . C-Function 20: Read Sequential . . C-Function 21: Write Sequential . . C-Function 22: Make File . . . . . C-Function 23: Rename File . . . . C-Function 24: Return Login Vector C-Function 25: Return Current Disk C-Function 26: Set DMA Address . . C-Function 27: Get alv Address . . C-Function 28: Write protect Disk . C-Function 29: Get Read-Only Vector C-Function 30: Set File Attributes. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . .. .. .. .. .. .. . .. .. . .. .. .. .. .. .. .. .. .. .. .. .. 3-l 3-l 3-2 3-2 3-3 3-4 3-5 3-5 3-5. 4-l. 4-2 4-3 4-4 4-5 4-6 4-7 4-8 4-9 4-lO. 4-ll 4-12 4-13 4-14 4-15 4-16 4-17 4-18 4-19 4-21 4-22 4-23 4-24 4-25 4-26 4-27 4-28 4-29 4-30 4-31 4-32 4-33.

(6) TurboOOS. 1.3. '. C-FUNCTIONS (Continued). T-FUNCTIONS. Z80 Guide. TABLE. OF. CONTENTS. (Continued). C-Function C-Function C-Function C-Function C-Function C-Function C-Function C-Function C-Function C-Function C-Function C-Function C-Function C-Function C-Function C-Function C-Function C-Function C-Function C-Function. 31: 32: 33: 34: 35: 36: 37: 40: 42: 43: 46: 47: 104: 105: 107: 108:. .. .. .. .. .. .. .. .. 4-34 4-35 4-36 4-37 4-38 4-39 4-40 4-41 4-42 4-43 4-44 4-45 4-46 4-47 4-48 4-49 4-SO 4-51 4-52 4-53. .. .. 5-l. Address . . User Number Read Random . . . . Write Random . . . . Compute File Size . Set Random Record . Reset Drive . . . . Write Random zero Lock Record . . . . Unlock Record . . . Get Disk Free Space Chain to Program . . Set Date and Time . Get Date and Time . Return Serial Number Get/Set Return Code Get. DPB. Get/Set. .. . .. .. .. .. .. .. .. .. .. .. Fill. lió: Get/Set Delimiter Block . . . Ill: Print 112: Block . List 152: Parse. . .. .. .. .. .. .. . . . . .. .. . .. .. .. .. .. .. .. .. .. Introduction . . . , . . . . . . . T-Function O: Reset Operating System T-Punction l: Create Process . . . T-punction 2: Delay process . . . . T-F'unction 3: Allocate Memory . . . T-Function 4: Deallocate Memory . . T-Punction 5: Send I/P Message . . T—Function 6: Receive I/P Message . T-F'unction 7: Set Error Address . . T-Function 8: Set Abort Address . . T-Function 9: Set Date and Time . . T-Function 10: Get Date and Time . Rebrxi1d Disk Map T-Function . . T-Function 12: Return Serial Number T-Function 13: Set Compatibility . T-Function 14: Log-On/Log-Off . . . T-Function 15: Load File . . . . . T-Function 16: Activate Do-File . . Autoload T-Punction 17: Dis/Enab1e T-Function 18: Send Command Line . T-Function 19: Return AIIoc Info .. li:. . .. . .. .. .. .. .. .. .. .. . .. . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . .. . . .. .. .. 5-2 5-3 5-4 5-5 5-6 5-7 5-8 5-9 5-lO. 5-ll 5-12 5-13 5-14 5-15 5-16 5-17 S-18 5-19 5-20 5-21.

(7) TurboDOS 1.3 programuíer's. T-FUNCTIONS (Continued). TABLE. Z80 Guide. OF. CONTENTS. (Continued). T-Punction T—Function. T-Function T-Function T-Function T-Function T-Punction T-Function T-Function T-Function T-Function T-Function T-Function T-Function T-Punction T-Function T-Function T-Function T-Function T-Function T-Function T-Function T-Function T-Function. 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43:. Return Physical Info . Get/Set Drive Status . Physical Disk Access . Set Buffer parameters Get Buffer parameters Lock/Unlock Drive . . Flush/Free Buffers . . Get/Set Print Mode . . . Signal End-of-Print Get/Set De-Spool Mode Queue a print Pile . . . . Flush List Buffer. Out . . . Network Remote Console I/O . . Get Cowm Status . . . Com Channel Input . . Comm Channel Output . set Conm Baud Rate . . Get Co~ Baud Rate . . Set Modem Controls . . Get Modem Status . . .. List. User-Defined Function Reorg Disk Directory . Select Memory mnk . .. .. . . .. . . .. . . . . .. . .. . . . . .. . .. . . .. 5-22 5-23 5-24 5-26 S-27 5-28 S-29 5-30 5-31 S-32 S-33 5-34 5-35 5-36 5-37 5-38 5-39 5-40 5-41 5-42 5-43 5-44 5-45 s-46.

(8) TurboDOS 1.3 Z80 Programmer's Guide. FUNDAMENTALS. Memory. Organization. FUNDAMENTALS. This section introduces you to the TurboDOS environment. Emphasis is given to the organization of memory, and to the interface and flow of control between application programs and the operating Subsequent secsystem tions describe the file system and other facilities in detail. resident portion of TurboDOS typically occupies between 12K and 24K of memory, deAn additional 2K pending on configuration. to 8K (or more) may be devoted to disk buffers, and another andIK or so to print queues, various other items of interlocks, file A dynamic working storage. 256-byte "Base Page" memory for reservedat thebottomof is communications between TurboDOS and applicaremaining memory space tion programs. The available for use by conírnands and application programs is known as the "Transient Program Area" (TPA). The. Z80 TurboDOS supports two alternative memory organization schemes, depending on whether or not bank-switched memory is available.. 1~1.

(9) TurboDOS. 1.3 Programuer's. Non-Banked. Z80 Guide. Memory. FUNDAMENTALS. Memory. Organization (Continued). non-banked Z80 configuration is limited by hardware constraints to a maximum of 64K of TurboDOS rnernory. resides in the topmost and allocates portion of memory, its disk buffers and other dynamic space requirements The TPA occupies immediately below itself. the lower portion of memory: A. FFFFH. l. l. l. I. l. TurboDOS. i. l. I. I. l !. I l l. Disk Buffers. I. Dynamic. Space. I. I. l. I. I. l. l. :. :. Transient. Program. Area. I. OOOOH. l. :. IK. 32K-50K. : I. I. OIOOH. 2K-8K. I I. l l. 12K-24K. l. BASe PAqe. l. the tpa is limited by systems, In non-banked disk buffers, and the size of TurboDOS, its more TPA is needed, other dynamic space. If the size of the disk buffer area may be decreased using the BUFFERS command or a system call. However, this works only when the system is quiescent (no files open, no queued, etc.) so that there is no print jobs dynamic space allocated below the disk buffers,. l-2.

(10) TurboDOS 1.3 Z80 programmer's Guide. FUNDAMENTALS. Memory. Organization (Continued). Banked. Memory. banked Z80 configuration permits wore than 64K of memory by providing two memory banks, only one of which may be active at a time. TurboDOS resides in bank O along with disk buffers and other dynamic space, while a bank 63K Transient Program Area occupies. A. its. l.. An area of common (non-switched) memory must be provided at the top of memory. should be IK, permitting each memory bank However, hardware design often to be 63K. dictates that the common area be larger, often as big as I6K. A large common area reduces the memory available for TurboDOS, but does not reduce the TPA size:. Ideally,. it. (com.NQrl}. FFFFH. l. l l. FBFFEI. TurboDOS. Bank. Mgr.. l. IK. l. i. i. l. !. l. l. 63K. l. Total. Transient. !. Program (Continued). Area. l. l. TPA l. l. (. [. I. (. l. l. l. i. l. l. !. l. l. l. l. !. I. i. I. l. l. (. l. l. l. l. I. l. l. l. I. I. ¡. !. !. 0 0. *P : I. 0 * : l. l. TurboDOS. I I l. Disk. Buffers. Dynamic. Space. l :. (Unúsed) l I. Base pnqe! (Bank O). l—3. : l. OIOOH. (. 0(jooh. i. Transient Program Area. f3áse P,jqe (Bank. l). ! l I. !.

(11) FUNDAMENTALS. TurbooOS 1.3 Z80 Prograuuner's Guide. program. Program. Interface. Interface. supports 94 different functions that invoked by an application program. Functions are provided for file management, console input/output, printing and spooling, The and various other TurboDOS facilities. devoted guide to is largely this half of last describing each of these functions in detail. TurboDOS may be. Functions supported by TurboDOS fall into two Cp/M-compatible functions, and categories: We TurboDOS-unique functions. will refer to them "T-functions", as "C-functions" and TurboDOS supports 50 C-funcrespectively. tions and 44 T-Functions. C-Functions. a C-function, a program executes 0005H Page Base with in the location a function nuniber in the C-register.CP/É4 TurboDOS 2.2: supports all BDOS functions of. To invoke CALL to. a. O. System Reset Console Input 2 Console Output 3*Raw Console Input 4*Raw Console Output 5 Output 6 Direct Console I/O 7 Get I/O Byte 8 Set I/O Byte. l. List. g. Print String. 10 Read Cons. Buffer Get Console Status 12 Return Version 13 Reset Disk System 14 Select Disk 15 Open File 16 Close File 17 Search for 18 Search for Next 19 Delete File. li. First. l-4. 20 Read Sequential 21 Write Sequential 22 Make File 23 Rename File 24 Return Login Vector 25 Return Current Disk 26 Set DMA Address 27*Get ALV Address 28 Write Protect Disk 29 Get R/O Vector 30 Set File Attributes 31 Get DPB Address 32 Get/Set User Number 33 Read Random 34 Write Random 35 Compute File Size 36 Set Random Record 37 Reset Drive (38-39 reserved) 40*Write Random O-Fill.

(12) TurboDOS. 1.3 Programner's. Z80 Guide. FUNDAMENTALS. program. Interface. (Continued). C-Functions (Continued). These. TurboDOS C-functions are compatible with the corresponding functions in CP/M 2.2 except for the four functions marked with an3 C-functions asterisk above. In TurboDOS, (Raw Console Input) and 4 (Raw Console Output) are compatible with MP,/M II rather than CP/M. C-function 40 (Write Random with zero Fill) is synonymous with 34 (Write Random). C-function 27 (Get ALV Address) performs no in TurboDOS, operation but this function STAT of CP/M which affects only theused utility with TurboDOS. is not normally. In addition to BDOS functions D-40 supported by CP/M 2.2, a number of additional functions have been implemented in cp/jq 3 and MP/M TurboDOS provides compatible C-functions for certain of these functions:. II.. 42 Lock Record 43 Unlock Record 46 Get Free Space 47 Chain to Program 104 Set Date/Time 105 Get Date/Time. 107 108. lió. Ill. 112 152. Return Serial No. Get/Set Rtn Code Get/Set Delimiter Print Block. List Parse. Block Filename. the following rarely-used CP/M functions ÁU implemented, II no function are perform in TurboDOS:. However, MP/M. 41 44 45 48 49 50 59 60. Test and Write Set Multi-Sector Set Error Mode Flush Buffers. Get/Set SCB Direct BIOS Call Load Overlay Call RSX. l-5. 3. and and. 98 Free Blocks 99 Truncate File lOó Set Dir Label Get Dir Label 102 Read PW Mode 103 Write File XFCB 106 Set Default PW 109 Get/Set Cons Mode. l0l.

(13) FUNDAMENTALS. TurboDOS 1.3 Z80 programmer's Guide. Program. T-Functions. a a T-function, a program executes location 0050H in the Base Page with a A diffunction number in the C-register. address is used to avoid ferent entrypoint conflict with C-function number assignments. TurboDOS supports the following T-functions:. To invoke CALL to. O. l. 2 3. 4 5 6 7 8 9. 10. li. Reset O/S Create Process Delay Process Allocate Memory Deallocate Memory Send Message Receive Message Set Error Address Set Abort Address Set Date/Time Get Date/Time Rebuild Disk Map Get TurboDOS S/N Flags Set Compat. Log-On/Log-Off Load File. 12 13 14 15 16 Activate Do-File 17 Autoloaá On/Off 18 Send Command Liñe 19 Get Alloc Info 20 Get Phys Disk Info 21 Get/Set Drv Status. Termination. Interface (Continued). 22 23 24 25 26 27. 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43. phys Disk Access Set Buffer Parms Get Buffer Parnís Lock/Unlock Drive. Flush/Free Buffers Get/Set Print Mode sig End-of-Print Get/Set Despl Mode Queue a Print File Flush List Buffer Network List Out Remote Console I/O Get Conun Status Comm Input Comm. Set Get Set Get. Output Corm Baud Comm Baud. Rate Rate. Controls Status User-Defined Func. Reorg Disk Directory Select Mem. Bank Modem Modem. terminate by jumping to locain the Base Page, or by invoking Both methods C-function C (System Reset). and cause TurboDOS are entirely equivalent, to terminate the programA in TPA and prompt command. program may also for the next terminate by invoking C-function 47 (Chain to which program), allows the program to specify the next command to be executed after the program terminates.. A. program OOOOH. tion. rriay. l-6.

(14) TurboDOS 1.3 Z80 Programmer's Guide. FUNDAMENTALS. program. Interface. (Continued). BIOS Branch. Table. TurboDOS For compatibility with CP/M, provides a full simulated "BIOS Branch Table" to that make direct BIOS support applications The branch table is compatible with calls. CP/M 2.2, and always begins on a page boundary (multiple of OIOOH) as in CP/M.. it. l l I l i { l i I l l l l l l l I l l. QffSet base-rO base+3 base+6 base+9 base+l2 base+l5 base+l8 base+21 base+24 base+27 base+30 base+33 base+36 base+39 base+42 base+45 base+48. L. {. Fnncti.oñ. l i. cold. I. start. warm start concole status console input. l. to A-reg to A-reg. console output from C-reg printer output from C-reg raw console output from C-reg raw console input to A-reg home drive to track zero select drive from C-reg set track from BC-reg sector from BC-reg set DMA address from BC-reg set read disk sector write disk sector status to A-reg list sector translate from BC to HL. I l l l l I I l l I I l l l l j. location OOOOH contains a JMP inentrystart) struction to the second (warmThus, a point of the branch table. program determine the base address of the can always the address found branch table by obtaining at Base Page location OOOIH and subtracting 3 from it.. Base. Page. l-7.

(15) TurboDOS. 1.3 programier's. Command. Z80 Guide. Processing. FUNDAMENTALS. Processing. Commnd. command always identifies a proon disk, and causes residing that file program to be loaded into memory (TPA) and TurboDOS has no "built-in" comexecuted. TurboDOS gram. A. mands.. TurboDOS comes with more than 30 standard command programs (described in detail in the You can expand 's GU9e). the vocabulary of commands simply by storing additional Programs are usually kept programs on disk.. in. Command prompt. .COM. files.. displays a command prompt on the whenever ready to accept a command. The command prompt is composed of the current user} number, the current drive and the symbol. prompt. TurboDOS. it. console. is. letter, Ccmmand Format. file. command TurboDOS consists of the possibly of the program to be executed, followed by an optional conunand of up to 127 characters. a command may be entered in upperbut is converor lower-case by TurboDOS. ted to upper-case Each name. tail. letters,. explicit file assumes explicit drive "B: ") specification (like ifYouthe program anis on The. program name may have type, but usually doesn't .COM). It niay also have not error. an (TurboDOS an. drive. will get the program file cannot be or the available tpa is not hold ifthe program.. the current. message found on disk, big enough to. if. special kind of the current drive.. A. command. specification (like. name.. l-8. is. used. It"B: ")consists with. to change of a drive no program.

(16) TurboDOS 1.3 380 Programmer's Guide. FUNDAMENTALS. Coumand. Tail parsing. Processing (Continued). format of a command tail is determined by TurboDoS the particular program involved. passes the command tail to the program by saving the length of the tail (in characters) at location 0080H of the Base Page, and saving the text of the tail (up to 126 characTurboDOS ters) starting at location 0081H. also stores a null (zero byte) immediately the last character of the command following The tail includes tail. all characters following the program name, including leading spaces. If no tail is given in the command, the length stored at 0080H is zero. The. If the command tail consists filenames of the form:. of. one. or two. {d:}filename{.typ} then TurboDOS parses each into File Control The Block (FCB) format. parsed FCB is saved at location 005CH offirst Base Page, and the the second parsed FCB is saved at location 006CH. Parsing is done following the proce152 dure described for C-function (Parse Filename). Conunand. Strings. also accepts strings of commands by the character \ (backslant). TurboDOS executes each command in sequence, and re-displays each but the firstnotas exceedis executed. A command string may the size of the command buffer, which is normally big enough toaccomodate two lines of text. TurboDOS. separated. it. 1~9.

(17) TurboOOS 1.3 Z80 Programmer's Guide. FUNDAMENTALS. Command. Processing. (Continued). Batch. Processing. Automatic. Loading. supports a batch processing mode in which execution is controlled by a predefined sequence of commands stored in a "doA on disk. do-file is a text file" (usually type .DO), each line of which file contains a valid TurboDOS command or command A a do string. do-file may be activated with 16 (Acticommand, or by invoking T-function A may contain any vate Do-File). do-file DO commands, and nesting embedded number of depth. is supported to any reasonable TurboDOS. provides a facility for loading any program or executing any command sequence at automatically start-up (cold program terminates (warm start) or whenever a initial start). Autoload at cold-start takes place only if a file named COLDSTRT.AUT is present on the start-up disk. Autoload at warm-start takes place only if a file named WARMSTRT.AUT is present on the current disk. The AUTOLOAD commandis the usual way to create these.AUT TurboDOS. files. program (.COM file) may be Alternatively, autoloaded by renaming as COLDSTRT.AUT or WARMSTRT.AUT. In this itcase, however, the must rely on the a. autoloaded not program contents of the Base Page FCB (at 005CH) buffer (at 0080H), because they will be by after the autoload. uninitialized. l-10. and. left.

(18) TurboDOS 1.3 Z80 programmer's Guide. FUNDAMENTALS. Base. Base. Page. Layout. Page Layout. Base Page is the 256-byte memory region from OOOOH to OOFFH, and is used primarily between TurboDOS and profor communication grams running in the TPA, The organization of the Base Page is shown below: The. |_Locations. l. l. O0OOH-0002H. I l l l I l l l i l. 0003H. l l I (. l. a JMP instruction to the warm-start entrypoint in the BIOS branch A program usually table. terminates by executing a OOOOH. JMP The address at location OOOIH can be used to locate the BIOS branch table.. I. I/O byte, may be used to control device assignments in some implementations.. l. Contains. 4 bits Least-significant contains current drive. 4 Most-significant bits contains current user nuniber (modulo 15).. 0004H. I l l l i }. l. pescri.pti.orI. l. 0005H-O007H. ] i I l I l l l l l l. instruction C-function to the A may program entrypoint. by exea C-function invoke cuting a CALL 0005Ii with a C-function number in the The address C-register. at location 0006H is highest address useable in the TPA plus one, and rnay be used by a program to find out Contains. jjqp TurboDOS a. how much memory. l-ll. it. can. use.. I l I l l i i l l. l i l l l I I I ! l I l I I l l l I l l ! I.

(19) TurboDOS. 1.3. '. Base. page. Layout. (Continued). FUNDAMENTALS. Z80 Guide. Page Layout (Continued). Base. |m¿QcjajáQns. l. --—. I I. 0008H-003AH. Reserved for tors (RST. 003BH-004FH. (Unused,. ]. l. l l I l. 0050H-0052H. I. interrupt vecthrough 7).. Contains a JMP TurboDOS the to. l l I. l l. (Unused,. 005CH-006BH. The Default part filename argument in a command tai.l is parsed. into this l6-byte. 006CH-007BH. l. area.. Default part 2. The second filename argument is parsed a command. I. l l l I l. FCB. tail. I. I. i. l.. first. l I. l. reserved). 0053H-005BH. l. i. l. instruction T-function. FCB. l. I. reserved). may program entrypoint. a T-function by exeinvoke cuting a CALL 0050H with a T-function number in the C-register.. i. I. l. A. l. I. !. De$cription. in. l. and. I. into this 16-byte area, be moved to another location before making use of the default FCB.. I. must l l l. 007CH. l l. 007DH-007FH. ! I. 0080H-OOFFH. l I I ! l. l-12. Default. FCB. current record.. Default. FCB. random. record.. Default l28-byte buffer. This area receives the command tail length in 0080H, and the conunand tail text (up to 126 characters plus a null terminator) in locations 0081H-OOFFH.. l. i I I l l i I l l l I.

(20) TurboDOS. 1.3. '. System. Z80 Guide. Start-Up. FUNDAMENTALS. System. Start-Up. get TurboDOS started, is necessary to systemfromdisk reada copyof theoperating into memory, a process known as "cold start". depends The exact cold-start procedure on the particular hardware involved.. it. To. Most. TurboDOS. step cold-start. implementations procedure:. use. this three-. l.. Whenthe computer isturnedonor reset, bootstrap from it executes the TurboDOS (Iñ read-only memory (ROM). the HORIZON implementation, the bootstrap is loaded The front reserved tracks on disk.) bootstrap scans all disk drives Erom A of each to P, searching the directory OSLOAD.COM ready drive for a file named which contains loader. the TurboDOS when this found, the bootstrap is TPA file and executes loads into the it.. 2.. loader scans all disk to P, searching for a file named OSSERVER.SYS which contains the When this server operating systeni. file is found, the loader proceeds to load the operating system into the upper portion of memory, then transfers conThe drive from which the trol to OSSERVER.SYS it. becomes the was loaded file "system disk".. it. 3.. The. TurboDOS. drives from. A. The. server downloads a user bootstrap routine into each user processor. The named a file then locates server OSUSER.SYS on the system disk which contains the user operating system, and downloads into each user processor.. it. During network operation, is helpful the system disk is always on-line. fixed disk is available, should be usedIf system disk. the. it. it. l-13. if. a as.

(21) TurboDOS. 1.3. '. Summary. Z80 Guide. FUNDAMENTALS. This section has introduced the fundamentals You have of the TurboDOS environment, learned how inemory is organized in both nonbanked and banked systems. You understand the TurboDOS program interface, including C-. and direct BIOS functions, T-functions, know how TurboDOS parses and calls. You and docommand strings, commands, processes how communicates programs with files, and it Base Page.. via the Next,. we examine. considerable. the. detail.. l-14. TurboDOS. file. system. in.

(22) TurboljOS 1.3 Z80 Programmer's Guide. FILE. SYSTEM. pile. sYsTm. section describes the TurboDOS file covers in detail. the structure of It facilities disks and files, the provided to manage files, and the procedures for calling these facilities from application programs. This. system. Disk Capacity. TurboDOS system can support up to drives per processor, identisixteen logical file by the fied letters A through P. Drives may be local to the processor, or may be attached to another processor and accessed by means of networking. The. accomodates any combination oE drives from mini-floppies to large hard disks Allocation block of a gigabyte. in excess be chosen size may for each individually drive, and affects maximum drive capacity as follows: TurboDOS. ;. R]1oc,. 8Fmk. qj7e. Mav.. PriTre. l. ciípÁcilr.Y. l. l i. IK. I. 2K. l. 4K. l. 8K. l. 16K. 256 128 256 512 1,024. i. Kilobytes. Megabytes Megabytes Megabytes Megabytes. l l I l l. l. theselimitsaresobig, itisalmost to partition a physical drive smaller logical drives under TurboDOS. into sometimes done such However,. Because never necessary. partitioning is for user convenience when using large fixed disks.. Star TurboDOS recognizes four standard mini-floppy disk formats: double and quad density (35 track and 70 track) CP/M format, and double and quad density (non-interleaved) TurboDOS format. In addition, BO-track TurboDOS although non-standard, diskettes, can be handled on a read-only basis by the North. system.. 2~1.

(23) FILE. TurboDOS 1.3 Z80 programmer's Guide. Disk Organization. SYSTEM. Disk Organization. Each. disk is organized into five I. I I. File e. 0. 0. 0. P 0 I. 0. I i l l. File. l. Storage. *0 *0. I. 0 0 ** O 0 I. 0. Storage. I I. Directory. l. Allocation Volume. l. Map. Label l. I l. areas:. Reserved. I. Tracks. Reserved tracks are required by certain hardconfigurations to support ware The but are not otherwise used by TurboDOS. be a given name to permits to volume label The each disk. map contains one each block on the disk, used by TurboDOS and to keep track of and which are which disk blocks are occupied The of contents a table directory free. stored on the which of the disk (wost of disk. The remainder. cold-start,. allocation allocation. bit for is. is identifies all files. is available. for. file. storage.. it). or not maintain a volume label When creates. allocation map on the disks CP/M disk is a accessed by TurboDOS, first CP/M few the first directory entries are relocated to the end of the automatically directory inorder toinake roomfor thelabel by When a TurboDOS disk is accessed and map. CP/M, andniapappear tobeordinary thelabel Thus, disks can entries. deleted directory CP/M and TurboDOS be moved between freely in spite of the differences in organization. CP/M. does. it. 2-2.

(24) TurbooOS 1.3 Z80 Programmer's Guide. FILE. Directory. Directory. Formats. SYSTEM. Formats. directory supports two alternative A formats: linear and hashed. flag bit in the directory label indicates which format is in use on a particular disk. TurboDOS. The standard CP/M, and. linear. format is compatible with. sequentially. is searched speed. Conse-. deteriorates look-up with quently, increasing directory size, and can get painfully slow on large disks with many files. hashed The optional directory format uses a hashing algorithm to make look-up in large A hashed much faster. directories directory may be used on any disk, but is especially suited for use on hard disks with many files. Hashed directories are ÁtQt media-compatible with CP/M, but may be converted to linear format whenever exporting to CP/M is needed.. the directory or hashed, is linear cards" have to be searches involving "wild Such wild-card done linearly. searches are typically slower if the directory is hashed.. Whether. File Organization. a sequence of l28-byte file contains and may be up to 134 megabytes records, (1,048,576 records) long. The records of a may be read and written sequentially or file randomly (by relative A record number). file beyond by writing may be extended the end of TurboDOS automatically allocates disk file. when a space extended, and deallois file when a cates file is deleted.. a. it. Textfilesarewrittenasa. sequence of ASCII (QDH) and with a carriage-return characters (OAF!) line-feed at the end of each text line. Text lines are variable length and may span records. The end of a text file is marked by the ascii character SUB (1AH).. 2~3.

(25) TurboDOS 1.3 Z80 Programmer's Guide. FILE. SYSTEM. File Operations. File Operations. About half of the 50 C-functions supported by TurboDOS are connected system. with the These functions support the operations needed and disks. directories, to manipulate. file. files,. following functions provide the basic facilities for sequential file access: The l. Fllnction. c-Fcn. I l ! I I !. Nam. l. File File Sequential Write Sequential Make File. 15 16 20 21 22. Open Close Read. I. !. l i l I l. additional functions are necessary to support random access and file sharing:. These i. c-Fcn. Fllnctj.on. I. Nam. I. 33. I. 34 35 36. i l l. 42. l. 43. !. Read Random Write Random Compute File Size Set Random Record Lock Record Record Unlock. ! l l l l. I. Directory i. functions. include: Fl,|nction. c-Fcn. l. 17. I. 18 19 23 30. l l l. Ná.m. l !. l. l. l l. l. for First for Next Delete File Rename File Set File Attributes Search Search. 2-4. I I l l.

(26) TurboDOS. 1.3. '. Z80 Guide. pile Operations (Continued). PILE. SYSTEM. File Operations (Continued). Drive-oriented I. functions. are:. FnnM",inn. r.-Fcn. l. Niíme. l. l l. 14 24 25 28 29 31 37. l I l l l l l. 46. Select. l. Disk. I. Login Vector Current Disk Write Protect Disk Get R/Q Vector Return Return. l l l I. Get dpb Address Reset Drive Get Free Space. I l i. i. Finally, the file l. some system. other functions include: Fl1nct.ion. c-Fen. connected. with. Nnnm l. l l. 13. l. 26 32 47 152. I l l. Reset Disk System Set DMA Address Set/Get User Number Chain to program Parse Filename. I l { l i I. of these file eysteni C-functions described in detail later in this document,. Each. 2-5. is.

(27) SYSTEM. FILE. TurboDOS 1.3 Z80 Programmer's Guide. Naming. Naming. Files. Files. keeps track of files by name, maintaining a directory of files on each disk. a file is identified uniquely by four fields:. TurboDOS. (A-P) . drive number (0-31) . user nanie (up to 8 . (up to 3 type .. letter. characters) file characters) file the disk on which The drive letter specifies no drive letter is the file is located. If by given, the current drive is assumed. default. The. user. number. libraries file allow files to. logical libraries by user is 31. specifies one of 32 These on each disk. be conveniently segregated. Generally, user or application. reserved for global files and user leaving reserved for log-on security, for general use.. fields are file name and. The name and type The ASCII characters.. is l-30. composed may have. of up. the file type may characters, Shorter names and types up to three. padded on the right with spaces.. to eight. have are. O. that file names and file is besuggested composed from the upper-case letters A-Z and the digits Q-9. any ASCII Actually, characters may be used including lower-case punctuation, and even non-printing letters, such names may However, control characters.. It types. not be parsed correctly in commands played correctly in directories.. nor. dis-. question mark ? is a special wild-card character which may be used in file names and types to match any character in the corresponding position during directory searches. The. 2-6.

(28) TurboDOS 1.3 680 programmer's Guide. FILE. SYSTEM. Special File N=es. Special File N=es. gives. special meaning to two "$.DIR" refers to the file "$.DSK" directory thearea of a disk, while the. TurboDOS. reserved. names.. entire contents of refers to disk volume (up to the maximum 134 megabytes). These special dumped,. patched, or However,. ary file. privileged File Control Block. physical file size of. files may be like any ordinaccess is restricted to. accessed. log-ons only.. File-oriented C-functions and T-functions are always called with the address of a File The Control Block (FCB) in the DE-register. FCB 33 bytes long (36 structure is a data bytes for random access operations) organized as follows: : l l. ñff": ef O. I. Field drive. l. ne,scripti.ork. l. 2. i. 16. :. l } l. l-8. name. l !. I. l. 9-ll. type. l l !. i. -> drive. l. file. 12. extent. 2—7. P. ! I I l I. name in padded on right with spaces, high-order of each byte reserved ASCII,. bit fl-f8. type in ASCII, padded on right with spaces, high-order of each byte reserved. file. for attributes. i l. l. code. for attributes. l l. (0-16): -> current drive -> drive A -> drive B. drive O. l. i. l. bit tl-t3 five. least significant bits of extent number. I l I l l I l l I l l ! I l.

(29) TurboDOS 1.3 Z80 Programmer's Guide. FILE. SYSTEM. File Control Block (Continued). File Control Block (Continued). l I I. Offset. I. 13. specl. flag byte. 14. spec2. most. l i. Pescript.ion. Fje1d. significant bits of extent. I I l. record. 15. I l. map. I l l. 32. l I. 33-35. l. eight. of records in current extent (0-128). I. allocation map of current extent. I. l I l. random. 20-bit record (byte 33 is least significant) for randomaccess operations. l l. l l. current record number (0-127) in current extent. record. l. number. current record. l l. l. Use). number. count 16-31. (Do Not. number. l i I l l I l l l i. the application program must bytes O-12 before opening, making, or searching for a file. It must alsozeroFCBbyte32beforereading or writfrom the beginning. ing a file sequentially In general,. initialize. FCB. is. fills. file from the direcbytes O-31 with information Thereafter, FCBthe application tory. program bytes 0-31. When the should not modify TurboDOS updates the direcis closed, file A directory with information from the FCB. as the tory entry has the same structure 32 bytes of an FCB. In a directory first O contains the user entry, however, byte number O-31 towhich the filebelongs, or the the directory entry is not in value OE5H use. Also, byte 13 may contain the exact byte count of the last record in the file. When. a. if. 2"8. opened,. TurboDOS. FCB.

(30) TurbooOS 1.3 Z80 Programmer's Guide. FILE. SYSTEM. File Attributes. Fíle Attributes. are stored in the high-order File attributes bytes fl-f8 and bits of the PCB name field type field bytes tl-t3, and are used to controlhow afilemay beaccessed: ' l. Attribnte. I I I I l l I. !. r'efin,it.iQn. l. file attribute undefined file attributes interface attributes read-only file attribute global file attribute archived attribute. flf2-f4. l. FIFO. f5-f8. ti t2 t3. I I l l I l. and are bits fl-f4 file attribute and may tl-t3 be set or recorded in the directory, cleared by means of C-function 30 (Set File Attributes). For a newly-created file, When all attribute bits are initialized to zero. a opened,. its attributes are copied file is be into the FCB. by Fíle attributes may also 17 and means of C-functions interrogated 18 (Search for First/Next). The. read-only attribute (ti) prevents a The being written, deleted or renamed. file saved (t2) enables a global attribute any user under user O to be accessed fromfile The from. effect for files. (it non-zero user numbers). The archived attribute and(t3) is used for incremental file backup, is automatically cleared by TurboDOS whenever a file is written or has. number under. renamed.. attribute (fl). saved. The FIFO causes be accessed using a special method access (described. file first-out" to. no. a. "first-in later).. Attributes f2-f4 are undefined, and available bits f5-f8 Interface attribute to the user. they cannot be used as file attributes; specify options for certain C-functions,. 2~9.

(31) FILE. TurboDOS 1.3 Z80 programmer's Guide. User. User. Numbers. SYSTEM. Numbers. provides 32 file libraries on each 0-31. disk correspondingO to user numbers reserved for global Generally, user is log-on files and user 31 is reserved for security, leaving l-30 for general use. TurboDOS. current user number is established inia non-privileged logtially at log-on. Forremains unchanged on, the user number until log-off. This restricts file access to the corresponding file library (plus global files a privileged under log-on, the user O). For changed be number without restricmay user tion by means of C-function 32 (Set/Get User The. Number).. current user number is treated as a prethereby allowing each disk to file names, fix directory to contain up to 32 libraries. Most directory functions (make, rename, delete, search, etc.) are restricted to the to the current user library corresponding number. However, in the user O library files which have the global file attribute may be opened This permits froni any user number. and other common files to commands, programs, The. be shared. File Sharing. by. all. users.. system, is posto accessitthe same sible for multiple users This can happen same time. In. a. multi-user. TurboDOS. if. at the file the users are. logged-on to the same user or accessing the same global file. supports interlocks to regulate such sharing at the file or record level.. number, TurboDOS. file. are compafile sharing facilities significant tible with MP/M, but provide extensions to alleviate the most serious deficiencies in file sharing.. TurboDOS. 61P/M. 2-lO.

(32) TurboDOS. 1.3. ' File. Locks. Z80 Guide. FILE. SYSTEM. E'iíe Sharing (Continued). File-level of four. interlocks. are. supported. by. means. distinct modes of opening file. The open mode is determined by interface attributes The f5-f6 when the modes file is opened or a. FCB. created. exclusive,. four open read-only,. shared,. and. are called permissive.. file opened in e¥.c.1!lS.i.\Te. mode is available to the opening process exclusively until by any other is closed, Aand may not be beopened opened in exclucannot process. sive mode if file the file is currently opened (in any mode) by another process. A. it. file. be opened in shAred inode by any of processes simultaneously. All processes are allowed to read, write and Record and extend the lock unlock honored functions are file. only for file opened in. A. number. shared. niay. mode.. fileinay. be openedin reaa-on1YInodebyany of processes simultaneously. All processes are allowed to read the file, but not to write or extend it.. A. number. may file number. be opened perlpissi\Te mode by in simultaneously. of processes All processes are allowed to read the file. If the file, any process writes or extends then that process gains an exclusive write-lock on the file, preventing any other process from The exclusive writing to the file. writelock is released when the locking process closes the file. A. any. In shared extends. permissive modes, if a process by adding new records at the end, these file records become immediately accessible to other processes that also have the. file. and. a. open.. 2-ll.

(33) TurboDOS. 1.3. '. Record. Locks. Z80 Guide. FILE. SYSTEM. File Sharing (Continued). by Record-level interlocks are controlled and means unlocking of explicit locking requests made by the application program. This allows concurrent update by multiple processes.. locks are by no means automatic, and by require explicit cooperative participation 42 (Lock programs. C-functions updating all Record) and 43 (Unlock Record) are honored only for files opened in the shared mode. Each program must lock a record before reading it, and must unlock the record after updating it. Record. program attempts to lock a record that already locked by another process, the Lock Record function returns an error code and the program must is try again until the program can successful. Alternatively, suspend ask TurboDOS to program execution automatically until the lock request can be satisfied.. If is. a. it. extend a shared file in a concurrent the extending program update environment, should first acquire a lock on record N+l N (where the last record in the file). is níay The program then safely write record N+l, and finally unlock N+l. To. 2-12.

(34) TurboDOS. 1.3 Progra=er's. Z80 Guide. SYS=. FILE. File Sharing (Continued). —-. Compatibility. Modes. file. The designed. sharing facilities of TurboDOS are with MP/M, to provide compatibility yet at the same time to alleviate the most serious limitations of MP/M file sharing. TurboDOS may be instructed to adhere strictly to MP/M file-sharing rules, or alternatively TO to relax sorBe of these rules. this end, a TurboDOS provides byte of "compatibility flags" with the following bit assignments: l i. Bit.. l. P1lÁq. Nam. {. Affects. I. 7. i. 6. l. 5. l. 4. mixed-mode. l. 3. I. 2-O. logical record lock (not defined). l. permissive suspend. global-write. l I. default open lock conflict action writing global files mode. mixed. file open validity. modes. I l l l I l I. each compatibility flag, a zero-bit denotes strict adherence to the MP/M rule, while a one-bit signifies a relaxation of The that rule. setting of the cominitial flags may be established during patibility TurboDOS system generation by assigning the desired value to the symbolic location COMPAT. A program may modify its compatiby calling T-function 13 (Set flags bility Compatibility Flags), but the flags automatically revert to their initial setting when the program terminates. For. flag (bit 7) is set, the If the permjckqive open mode is permissive, default rather file (as in MP/M). Specifically, than exclusive the open mode is determined when a file is opened or created by FCB interface attributes f5-f6, as shown in the following table:. 2-13.

(35) TurboDOS. 1.3 prograwmer's. FILE. Z80 Guide. SYSTEM. File Sharing (Continued). Compatibility (Continued). Modes l I. permis,si.\Te f1Aq = ffi f.5 l opejj H1oae. l. O. I. O. I i. l). l l l. O. 1. !. I. I. perHli¶síi\'e fj.aq = ffí f,5 I open mo&. I. i. O. shared. I. l. O. read-only permissive. I. l. l. l. exclusive. O. I. O. l l l l. O. } l I. permissive. l. shared. l. read-only exclusive. l l. (bit 6) is set, then an record that is already by someone else causes the process to be suspended until its lock request can be satisfied. Otherwise, an attempt to lock or to a record that is already locked by write someone else results in an immediate error return code (as in MP/M).. If the attempt locked. sl15pena. to lock. flag a. If the qIobaI_jÁ/rite flag (bit. a program number may. Otherwise, read-only. 5) is set, then under a non—zero user read and write global files. to global files is strictly. running. both access (as in. MP/M).. then the miKed-Node flaga (bit 4) is set, mode may open shared process in file mode open in read-only while another has Otherwise, the shared and (or vice-versa). read-only modes are mutually exclusive (as in. If. one. it. MP/M).. 3) the 1oqic@l set, then the 42 FCB random C-functions record and 43 (Lock/Unlock Record) is interpreted 24-bit logical record number as an arbitrary and does which not cause not validated Otherwise, the FCB random positioning. 42 and 43 for C-functions record interpreted as the relative number of a 128byte record, and causes the to be positioned to that record (as in MP/M).. is flag (bit field for. If. file. is field. is. file. 2-14.

(36) TurboDOS. 1.3. ' FIFO. Files. FILE. 280 Guide. SYSTEM. Files. FIFO. communications between To ses, processors and users, TurboDOS called a FIFO a special kind of. facilitate. file. processupports. (first-. similar in concept to Unix in, first-out) FIFOS are opened, pipe. closed, read and ordinary sequential exactly written However, alike FIFO record written to files. record to the end, and is always appended read from a FIFO is always taken from the and removed the FIFO. a. a. a. beginning. from. from is differentiated other files by the presence of the FIFO attribute (fil) in the directory. Record zero of a FIFO is a header record used by TurboDOS to keep track of the FIFO, and is organized as follows:. A FIFO. l. ñffíset.. cnntent.s. l l l l l i i I. I l. I O. l. 2-3 4-S 6-7 8-9 10-127. (0=RAM, type mode (0=error maximum size. -l=disk) code,. -l=suspend) (records) current size (records) number of last record read number of last record written (not used, reserved). l l l l l I l l. The header the body of the specifies whether and the maxiFIFO is RAM- or disk-resident, mum number RAMmay contain. of records resident FIFOS provide high-speed but limited capacity (up to 127 records, usually much FIFOs Disk-resident provide large less). capacity (up to 65,535 records) but slower command The FIFO may be used to speed. header. create a FIFO and. it. initialize its. 2-15.

(37) TurboDOS. 1.3. '. Z80 Guide. FIFO Files (Continued). Load. Optimization. FILE. SYSTEM. FIFO Files (Continued). Normally, reading an. from an empty FIFO code (A=l), and code returns a the mode byte in the FIFO. end-of-file FIFO. full. disk-full. returns. to writing (A=2).. a. header if set to -l (suspend), then reading from an is empty FIFO or writing to FIFO causes the process to be suspended full until the FIFO. However,. a. becomes. non-empty. or. non-full.. The header body of a FIFO or disk-resident may be accessed directly using C-functions 33 and 34 (Read/Write Random), thereby bypassing An the normal protocol. attempt to make (C-function 22) an FIFO treated as an open (C-function 15), while an attempt to delete (C-function 19) a FIFO The only way to get ignored. of a FIFO to clear the FIFO then delete. first-in first-out. is is. is. first it.. existing. rid attribute,. TurboDOS contains a program load optimizer which greatly improves the speed of program loading and overlay fetching from local disk drives. This module scans the allocation inap of program files to be loaded into TPA, detects sequentially-allocated file segments segments (often 16K or more), and loads these at the maximum transfer rate of the disk controller. This provides a manyfold increase over normal sequential file access performed one l28-byte record at a time. The program load optimizer is utilized automatically by the command line interpreter and the autoload processor, and is also accessible to user programs by means of T-function 15 (Load File). The optimizer is not invoked when loading from a remote drive over the network, nor when loading into a banked TPA.. 2-16.

(38) TurboDOS. 1.3. '. Buffer. Z80 Guide. Management. file Buffer. s:vstrm. Kanagement. TurbooOS. buffer manager performs multiof physical disk input/out(LRU) buffer least-recently-used put, assignment and other sophisticated optimizations. Buffering provides a inanyfold reduction in the number of physical disk accesses during both sequential and random file operations. The. buffering levelusing. Thenurnberand/or changed. sizeof diskbuffersmaybe. by means of T-function 23 (Set Buffer by T-function Parameters), and interrogated 24 (Get Buffer The number Parameters). of buffers must be at least two, and the buffer size must be at least as large as the physiFor cal sector size of the disks being used. optimum performance, the number of buffers should be as large as possible consistent. with the tpa size required.. The. maintains its buffers on and the "free" the "in-use" lists: list Whenever manager the requests a list. file disk access, the buffer manager first checks the in-use list to see if the requested disk Most of the sector is already in a buffer. time is, and no physical disk access is required. If not, the buffer manager attempts to acquire a new buffer from the free empty, the leastlist. list(atis the If the free end of the inrecently-used buffer use disk out to necesis written list) sary, and then reused to receive the newly requested disk sector. two. buffer. manager. it. if. 2-17.

(39) TurboDOS. 1.3. '. Media. PILE. Z80 Guide. Changes. Error Handling. Media. SYSTEM. Changes. disk volume is changed, it Before a removable is crucial that any buffers relating to that disk are written out if necessary, and returned to the free list. In single-user configurations of TurboDOS, this is done automatically whenever the system pauses for console input. In multi-user configurations, buffers must be explicitly flushed and freed by calling T-function 26 (Flush/Free Buffers) This is most comchanging disks. prior to command, monly done by executing the CHANGE but should also be coded into applications that require iuedia changes during operation. For safety, TurboDOS also flushes buffers automatically during any lull in system actiwhenever them automatically a vity, and frees disk drive becomes not-ready. In the event of an unrecoverable disk TurboDOS normally displays a diagnostic formats: sage in one of these. error,. mes-. I l l. Error, Drive A, Track [Retry, Ignore, Abort}. l. Write Error, Drive [Retry, Ignore, Abort]. l. Not. l. Spooler. l. O, Sector. Read. B,. Ready. Error,. Drive. I. 2. l I. Track. 5,. Sector. 16. i I. C. [Retry, Abort]. Error [Ignore, Abort]. I I l. waits for the user to choose the desired recovery option by keying in the appropriate letter (R, I or A).. and. 2-18.

(40) TurboOOS. 1.3 programer's. Z80 Guide. FILE. SYSTEM. Error Handling (Continued). Error tiandling (Continued). application. to intercept by calling 7 T-function (Set Error Address). In this case, TurboDOS does not display its usual Normal diagnostic messages. error processing when the application resumes automatically program terminates. An and. process. program may elect such errors, however,. Because the buffer manager optimizes them as disk write operations by deferring long as possible, write errors may be reporand possibly even to ted later than expected a user than expected. different NOTE:. 2-19.

(41) TurboDOS 1.3 Z80 Programmer's Guide. SERIAL. I/O. SERIAL. This section describes the TurboDOS facilities that deal with serial input/output (I/O) in connection with consoles, printers, and communications. Console. Basic. I/O. Console. INPUT/OUTPUT. channels.. TurboDOS provides ten C-functions that permit programs to interact with the user console device. Three kinds of console input/output basic I/O, raw are supported in TurboDOS: I/O, and string I/O.. I/O. Three on a l. C-functions provide basic console I/O single-character basis:. C-Fen. :. F\lncti.on. Nam. l. l. l. 1. l. 2. l. li. ¡. I. Console Input Console Output Get Console Status. I I I l. Console Input function waits for a character to be keyed in, echoes the character to the console screen to provide visual confirmation, and returns the character to the calling program.. The. The Console Output function displays a charhoriacter on the console screen. It expands based upon zontal tab characters into spaces, tab stops at every eighth column. The Get. Console Status function checks to whether or not a console input character available, and returns a Boolean result.. 3-l. see. is.

(42) TurboIKjS 1.3 Z80 Programmer's Guide. INPUT/OUTPUT. SERIAL. Console I/O (Continued). Raw Console. I/O. Three console l. C-Fen. additional I/O: I. Fam.tion. l i. 3. l. 4. I. 6. C-functions. provide. raw. Náme. I ! i. Console Input Raw Console Output Direct Console I/O Raw. I l I. Raw Console Input function is similar to the basic Console Input function, except that echoed to the input characters are not Likewise, the Raw Console Output screen. function is like the basic Console Output function, except that horizontal tabs are not. The. expanded.. The Direct Console I/O function combines the functions of Raw Console Input, Raw Console Output, and Console Status. It is supported with CP/M. only for compatibility. String. Console. I/O. remaining console I/O functions provide input and output of character strings:. The. L±Ecn_j-__-_---_-EunctiQn. l l. 9. I. 10. l i I. no. Ill. Print String. Read Console. Buffer Get/Set Delimiter Print Block. Nalne. l l l l l I l. Print String function outputs a string of characters to the console. The string may be of any length, and is terminated by a reserved The delimiter delimiter. is normally the dollar-sign $ character, but may be changed by means of the Get/Set Delimiter function. The. 3-2.

(43) TurboDOS 1.3 Z80 programmer's Guide. SERIAL. INPUT/OUTPUT. I/O (Continued). Console. String. Console (Continued). I/O. Print Block function is similar to Print String, except that the string length is passed so that no delimiter is explicitly needed. Both Print String and Print Block expand horizontal tabs. The. The Read Console Buffer function reads an entire line of edited input froni the console. from the console and Characters are accepted stored in successive memory locations until a carriage-return terminates the line, Input characters are echoed to console output (but, unlike CP/M, tabs are not expanded). Rudimentary editing is supported: backspace or delete characters erase the last typed charwhile CTRL-U or CTRL-X erase the acter, entire line.. Attention. Requests. The execution of suspended at any. a. program. or. do-file. ínay be. time by typing a reserved the console key"attention" character onTurboDOS, board, In North Star this is TurboDOS BREAK. "beep" to acknowledge will has received the attention request. that. it. After an attention request, the interrupted program or do-file will remain suspended until one of the following attention responses is typed: (resume) simply restarts the point of interruption.. CTRL-Q. execution at. (abort) cancels execution of the inany terrupted program or do-file, becauses nested commands and do-files disregarto ded, and returns to the command prompt. An application program may elect to intercept such abort requests, however, by calling Tfunction 8 (Set Abort Address). CTRL-C. 3H.

(44) TurboDOS 1.3 Z80 Programmer's Guide. SERIAL. INPUT/OUTPUT Console I/O (Continued). Attention. Requests. (Continued). CTRL-P (echo-print) execution and subsequent console causes output also to be echoed a second to the attention/echo sequence turns off echoing of con-. restarts printer.. all. sole output to the printer.. (end-print) restarts execution signalling the end of the current print CTRL-L. Coijm Channel. I/O. after job.. In order to allow communications-oriented applications programs to be written in a hardware-independent fashion, TurboDOS supchannel inports a standard communications terface consisting of seven T-functions: l. T-pcn. l. Fnñctimn. Nam. l. 34 35 36. Get. i. 37. i. 38 39 40. Set Get Set Get. I I. I l. I i. I. Comm Cornm. l. Channel Status Channel Input Channel Output Comm Baud Rate Channel Cornm Channel Baud Rate Comm Channel Modem Controls Modern Comm Channel Status Comm. l l l l i l i l. functions support multiple channels of 34-36 provide communications. T-functions basic single-character COlñIñ channel I/O (analogous T-functions 37to raw console I/O). 38 allow programs to sense the comm or set speed channel baud rate to any standard from 39-40 50 to 19,200 baud. T-functions allow to set modem control signals (RTS, programs DTR) and to sense modem status signals (CTS, DSR, DCD, RI). These. 3-4.

(45) TurboDOS 1.3 Z80 Programmer's Guide. SERIAL. INPUT/OUTPUT. Printer. Printer. Basic. Output. printing. Output. TurboDOS. provides the basic printing functions of CP/M, plus an elaborate concurrent printing facility which offers several modes of print spooling and flexible print routing among multiple printers and print queues. The spooling and routing facilities are completely transparent to application programs. Two C-functions provide the programs printer to generate l. !. C_,Fcn. FHnctiQn. .. l l. 5. I. 112. List. List. i. basic means for output: l. NÁTRe. l i. Output. i. Block. l. List Output function outputs a single character to be printed, while the List Block function outputs a character string of speciIn contrast to console I/O, fied length. these print output functions do not expand tabs. The. Control Functions. Four. T-functions. provide. control. spooling, tie-spooling, print mechanisms TurboDOS:. and. of. I. T-Fcn. l. Fl,lnct.i.on. Nam. t 27. I. 28 29 30. ! l. l l. I i. over the queuing. Get/Set Print Signal End-of-Print Get/Set De-Spool Mode Queue a Print File Mode. i l l i I. Get/Set Print Mode function controls Print output may be routed print routing. to a specified printer, spooled to direct specified drive and print queue, displayed on The. a. the console,. 3"5. or. simply discarded..

(46) TurboDOS 1.3 Z80 Programmer's Guide. SERIAL. INPUT/OUTPUT. printer. Output. (Continued). Control Functions (Continued). The Signal End-of-Print function allows a program job to terminate a function, a job In the absence of ends automatically at the conclusion of the program, upon receipt of an end-print attenrequest from the console, or when a. this. print. explicitly. print. tion. reserved end-of-print character (if defined) appears in the print output stream.. The Get/Set De-Spool Mode function controls A background printing (de-spooling). printer may be assigned to de-spool from a specified an queue, or rnay be placed Any job in process may be status. stopped, resumed, restarted from the beginning, or terminated altogether.. print. in. off-line. Queue a Print File function permits a program to queue a print file (or any text for that matter) for background printfile, The may be placed on any specified ing. file print queue, and inay be saved or deleted automatically after printing. The. 3-6.

(47) 1.3 Programmr's. TurboDOS. C-FUNCTIONS. Z80 Guide. C-FUNCTIONS. This section describes the 50 CP/M-couipatible functions ("C-functions") supported by TurboDOS. The C-functions are presented in numerwith calling parameters, return ical order, value, and a detailed explanation for each. To invoke a C-function, executes a program a 0005H in the Base Page with CALL to location C. a function number in register Byte-length arguments E, and wordare passed in register length arguments C-functions in register DE. return byte-length values in register A (dup-. licated in L), or word-length BA). register. (duplicated. HL. in. values. in. call is made with register C If a C-function an unsupported function number, Turboset to DOS returns immediately with registers HL and. BA. zeroed.. C-function. generally destroy registers but preserve X, y, and the register set. calls. A—B-C—D-E-H-L,. alternate. 4_1.

(48) TurboDOs 1.3 Z80 Programmer's Guide. C-FUNCTIONS. C-Function System. C-Function Entry. O. Arguments. System I. Reset. Req. i. C. =. I. pésc,ript.iQñ. I !. O. Reset. l O. l l. Explanation. The. System. Reset. function. terminates. the. Program calling programmore("warm-start"). commonly termination performed by is jump which has. executing a exactly the. same. to location effect.. OOOOH,. TurboDOS system, program In a multi-user termination closes any open files, releases any locked records or devices, and ends any active print job.. 4-2.

(49) TurboDOS 1.3 Z80 programmer's Guide. C-FUNCTIONS. C-Function Input. Console. C-Function Entry. I. Arguments. Console l. Input pescription. Req. l I. C. =. !. Returned. Value. l. Re'i. l I. T)eqcri.ptjon. I. l I. A. I. Explanation. I I. l. I l. l. =. input character. I l. Console Input function obtains the next character from the console keyboard, and in register A. If no character is returns available, the calling program is suspended until a character is typed.. The. it. Graphic. characters and certain control charline-feed, and backacters (carriage-return, space) to the console screen. are echoed Horizontal tabs are expanded into multiple based upon tab stops at every spaces, eighth column,. ,. 4~3.

(50) TurboDOS 1.3 Z80 Programmer's Guide. C-FUNCTIONS 2 C—Function Console Output. C-Function Entry. 2. Arguments. Explanation. Console i. Output. Req. l. l. C. =. 2. l. l. E. =. output character. i. _._. l. --^scnR_tjQn. ____—_.__l. l. The Console displays the Output function character passed in register E on the console tabs are expanded screen. Horizontal into based upon tab stops at multiple spaces, every eighth column.. 4_4.

(51) TurboDOS 1.3 Z80 Programmer's Guide. C-FUNCTIONS. C-Function 3 Input. Raw Console. C-Function Entry. 3. Arguments. Raw Console l. Req. Input. l. __,_.__Lpe=ÁptiQI)—. l l. C. =. I —. 3. I. l. Returned. Value. l. LM9. i. .————__—=cKjkRu9n. l. I I. Explanation. l. A. -—_-._——l l. =. input character. I I. Raw Console Input function obtains the and next character from the console keyboard, in register A. If no character is returns available, the calling program is suspended character is typed. Input characters until a echoed are not to the console screen.. The. it. This function is compatible with MP/M. (Iñ CP/M 2.2, this function is Input from Reader Device. In CP/M 3, this function is Auxiliary Input.). 4-5.

(52) TurboDOS 1.3 Z80 programmer's Guide. C-FUNCTIONS Raw. C-Function Entry. 4. Arguments. Raw Console I. Req. Explanation. Output. I. pescripti.op. ! I. C. =. 4. I. E. =. output character. l. C-Function 4 Output. Console. l l l i l. The. Output Raw Console function displays the passed in register E on the console screen. Horizontal tabs are not expanded.. character. This function is compatible with MP/M. (Iñ CP/M 2.2, function is Output to Punch this Device. In CP/M 3, this function is Auxiliary Output.). 4-6.

(53) TurboDOS 1.3 Z80 Programmer's Guide. C-FUNCTIONS C—Function. 5. List Output C-Function Entry. 5. Arguments. List Output l !. C. !. E. I. Explanation. peRcription. Req. I. = =. l l. 5. l. output character. l l. function sends the character Listin Output register to be printed according Horizontal to the current print routing. tabs expanded.. The passed. E. are not. 4~7.

(54) TurboDOS. 1.3. Prograumer's. Z80 Guide. C-FUNCTIONS. Direct. C—Function. Entry. 6. Arguments. Direct I. Req. Console. I/O. l. i. R==ij?já&R-——--.———. I. l. i. C. =. 6. l. I. E. =. (for combined status/input) -l -2 (for status) -3 (for raw input) output character (for raw output). i. l l I l. Returned. C-Function 6 Console I/O. Value. L~mL|. I I. Explanation. A. =. input character. Direct Console of four possible upon the argument. The. or. I i i. I. PescÁptKn. i. l. l l. status. I. I/O function performs one sub-functions, depending passed in register E.. any available console If E = character -l (OFFH), isthenreturned input register A, in without echo to the screen. If no character the function is available, returns A = O. (CFEH), If E = -2status console available, or A to C-function. li. (A =. then O =. -l. (Get. this function. returns. input is if no consoleEquivalent otherwise). Console. Status).. = -3 (OFDH), then this function obtains If E next console the input character and returns in register A, without echo to the screen. the calling If no character is available, a character program is suspended until is typed, Equivalent to C-function 3 (Raw Console Input).. it. other values of e, this function displays the character on the console screen. Horizontal tabs 4 are not expanded. Équivalent to (Raw Console C-function Output). For. 4"8.

(55) TurboDOS 1.3 Z80 programmer's Guide. C-FUNCTIONS. C-Function 7 I/O Byte. Get. C-Function Entry. 7. Arguments. get I/O. Byte. _.__-._--)e§~tiom________-!. y=n l. C. l. 7. =. i. l. Returned. Value. -——_ j=Áp£j9lL-_. contents of I/O byte (loc. LAQ9Ñ i I. Explanation. A. =. ___! 0003H). I l. This function simply returns the value of 0003H Page location (which is used in implementations to control serial I/O device assignment).. Base some. NOTE:. optional. This function. TurboDOS. module system. 4-9. the is supported only during if included is. CPMSUP. generation..

(56) TurboDOS 1.3 Z80 Programmer's Guide. C-FUNCTIONS. C-Function 8 Set I/O Byte. C-Function Entry. 8. Arguments. Explanation. I/O. Set l. Byte. Req. l. I. C. =. 7. l. E. =. new. _. _. D£scription l. value of I/O byte (loc. 0003H). I. This function simply sets the value of Base location 0003H (which is used in some implementations to control serial I/O device assignment). Page. This function is supported only module CPMSUP included TurboDOS system generation. NOTE:. optional. is. 4-lO. if the during.

(57) 1.3 Progra=er's TurboDOS. Z80 Guide. C-FUNCTIONS C—Function. 9. Print String. C-Function Entry. 9. Arguments. Print String l. RF'q. l. i. C. =. 9. l. DE. =. string. l. Explanation. pescriptiQn. l. l l i. address l. The print String function displays a string The of characters on the console screen. string may be of any length, and is terminated by a reserved delimiter, $ The delimiter is normally the dollar-sign character, but by means of C-function 110 may be changed (Get/Set Output Delimiter). Horizontal tabs are expanded into multiple spaces, based upon tab stops at every eighth column,. 4"11.

(58) TurboDOS. 1.3. '. C—Function. Entry. Z80 Guide. 10. C-FUNCTIONS. C-Function 10 Buffer. Read Console. Read Console. Lm_i. Arguments. Explanation. Buffer. _____. I l. C. =. 10. I. DE. =. buffer. I. I ] i. address. I i. The Read Console Buffer function reads an entire line of edited input from the console. The input buffer whose address is passed in register DE has the following structure:. |_j.ff§e-t__j_mectiQn I. O. l. l. i. 2. to. passed. returned returned. N+l. j_. PescriptiQñ input size (N) actual input (O-N). rnax. input characters. i I ! i l. The. first byte of the buffer must be preset to the maximum number of characters allowed in the input line. by input is accepted until terminated carriage-return. may be corInput errors rected by typing BACKSPACE or DELETE to erase one character at a time, or CTRL-U or CTRL-X to erase the entire line. Characters in not accepted, and excess of the maximum are diagnosed with a "beep". Input characters echoed to the console screen. Unlike are CP/M, this function does not expand tabs in Console a. TurboDOS.. return, the second byte of the buffer contains the actual number of input characters in the buffer. The input line is returned starting at the third byte of the The terminating buffer. carriage-return is neither stored in the buffer nor included in Unused buffer positions following the count. the last input character are uninitialized. Upon. 4-12.

(59) TurboDOS. 1.3. ' C-Function Entry. II. Arguments. Returned. Value. Explanation. C-FUNCTIONS. Z80 Guide Get. Get l. Console. Req. !. C. =. I. l. Pef;cjáRLLQn. l l. l l. I. pescriptj.Qjí. Req A. ). ----—--. li. l I. li. Status. I l. C-Function Status. Console. =. -l if if O. console console. I. get Console Status function checks to whether or not a console input character available. If console input is available,A returns A = -l. Otherwise, returns The. it. 4-13. l. input is available input is not available. { l. see. is. =. it O..

(60) 1.3 progranmer's TurboDOS. C—Function. Entry. Returned. 12. Arguments. Value. C-FUNCTIONS. Z80 Guide. C-Function 12 Return Version. Return Version i. C. I. Req. I. H. =. l l. L. =. l. 12. ._______pescripti«í. ._. =. (meaning: 31H (meaning:. OOH. l. Explanation. !. pesmñption. L-Rmj-—----.-.. CP/M, BDOS. l. MP/M). not version 3.1). l l. The Return Version function provides informacompatible version of on the (The BDOS version number returned in by patching L may be changed the register CPMVER symbol during system generation.). tion CP/M.. latest. 4-14.

(61) TurbooOs. 1.3. '. C-Function Entry. Z80 Guide. 13. Arguments. Explanation. C-FUNCTIONS Reset. Reset l. Disk. Req. l. C. =. System. Pescri.pt.ion. l l. C-Function 13 Disk System. 13. ! l I. I. l. the only effect of the Reset In TurboDOS, Disk System function is to reset the current DMA (See C-function 26, address to 0080H. DMA Set. Address.). 4-15.

(62) TurboDOS 1.3 Z80 Programmer's Guide. C-FUNCTIONS. C-Function 14 Select Disk. C—Function. Entry. 14. Arguments. LiBmA. ---———-ws£Ljptio.n_____. ._|. l. C. =. 14. l. l. E. =. selected disk drive: O for drive A l for drive B. l. I l I I. Explanation. Disk. Select. :. 15. for drive. P. ! I. The Select causes Disk function the disk drive specified in register E to be selected The as the current (default) disk drive. current drive is used in subsequent file operations whenever the PCB drive field is set to zero.. 4-16.

(63) 1.3 programaer's. TurboDOS. C-Function Entry. C-FUNCTIONS. Z80 Guide. 15. C-Function 15 Open File. File. Open. Returned. —_. I. Value. C. =. 15. l. DE. =. FCB. A. =. I. address. l. _pp,¶¢ri,,pt-i.Qn. LjUmL__ l I. Explanation. l l. I. I. j. -__—-—péscri.ptiQñ. l. Arguments. i l. if successful -l if file not found O. l. function opens the file specidrive, name, type, and extent 12). Normally, the fields (bytes O through extent field (byte 12) should be set to zero. The specified the curfile ormustmustexistbe aunder global rent user number file under user O.. The. Open. fied. by'. File. the. FCB. open mode is determined by compatibility flag bit 7 (permissive) and by the FCB interface attributes f5 and f6, as shown in the following table: The. Q_ peArlissiye_íÁag-= I E6 QPéñ µiodé f5 l l. I. O. O. i. O. 1. l I. O. l l l. pernlissi.\/e l !. =. 1 ! i. permissive. l. shared. l. read-only exclusive. !. I. I. O. shared. I. i. O. read-only permissive. l. l. l. l. exclusive. Elaq. !_=5-L&peILTR'pge l O. l l l l. O. l. record field (byte 32) is If theto FCB current function returns the byte set this -l, count of the last record of the file in the The calling program current record field. should zero the current record field before doing sequential reads or writes.. 4-17.

(64) TurboDOS 1.3 Z80 Programuíer's Guide. C-FUNCTIONS C—Function Close. C—Function. Entry. Returned. 16. Arguments. File. Close l. Req. i. ___—-)=jájmQn. I. Value. l. C. =. 16. I. DE. =. FCB. I. Reg. l. A. i I. Explanation. =. ! I !. address. I. DescriptiQn. I !. 16. File. if miccessful -l if file not found O. i l I I. The. Close File function closes a preMake viously opened by an Open File (15)file or The directory C-function, is upFile (22) necessary dated to reflect any new blocks if allocated to the file, and any locked records are. unlocked.. attribute f5 is set, this If FCB interface function performs a "partial close" operation which updates the directory but leaves the. file. open.. 4-18.

(65) TurboDOS. 1.3. '. C-Function Entry. Z80 Guide. 17. Arguments. Returned. Value. Explanation. C-FUNCTIONS C—Function Search for. 17. First. Search l. Req. First. for i. l. pescriptiop. I l. C. =. 17. l. DE. =. FCB. I l. address. l l. l. I. r)escriptio.rl. Req. l I l l. A. =. entry. -l if. number. (0-3). file not. found. if. successful. I i I I l. Search for First function scans the directory for the first entry which matches the FCB drive, name, type, and extent fields (bytes O through 12) and the current user number. AnASCII question niark (3FH) in any FCB byte I through 12 is treated as a wildcard which watches any character in the corresponding byte position of the directory entry. The. is successful, this function If the search a directory record (containing four returns 32-byte directory entries) at the current DMA address, and with a value in register A (0-3) that indicates which of the four entries was found to match the FCB. If the search is not in successful, the function returns -l (0!?FH) register A. If the Search for First function succeeds in finding an entry which matches the given FCB, then C-function 18 (Search for Next) may be called repeatedly to locate all remaining matches in the directory.. 4-19.