Z80-RIO OPERATING SYSTEM USER'S MANUAL · option can be issued. STATUS [0 I 1 ... engineer/programmer in Z80-based hardware/software system design. ... macro assembler, and

I

Z80-RIOOPERATING SYSTEM

USER'S MANUAL

REVISION A

1 I

READER'S COMMENTS

Your feedback about this document is important to us: only in this way can we ascertain yourneeds and fulfil l them in the future. Please take the time to fill out this question-naire and returnit to us. This information will be helpful to us, and, in time, to the future users of Zilog systems.Thank you.

Your Name:.

Company Name:.

Address:

Title of this document:.

What software products do you have?.

What is your hardware configuration (including memory size)?_

Does this publication meet your needs? CD Yes CD NoIf not, why not?

How do you use this publication? (Check all that apply)CD As an introduction to the subject?CD As a reference manual?CD As an instructor or student?

How do you find the material?Excellent

Technicality CDOrganization CDCompleteness CD

What would have improved the material?

GoodDDD

ial?

Poor

CDDn

Other comments, suggestions or corrections:.

If you found any mistakes in this document, please let us know what and where they were:

First Class

Permit No. 475CupertinoCalifornia95014

Business Reply Mail

No Postage Necessary if Mailed in the United States

Postage Will Be Paid By

ZilogSoftware Department Librarian10460 Bubb RoadCupertino, California 95014

\

TABLE OF CONTENTS

CHAPTER 1 - INTRODUCTION AND OVERVIEW 1

1.1 INTRODUCTION "' 1

1.2 SYSTEM OVERVIEW 3

1.2.1 Hardware Configuration 31.2.2 File Systems 31.2.3 System Initialization 61.2.4 Commands 71.2.5 I/O 7

\

CHAPTER 2 - RIO EXECUTIVE 9

2.1 SYSTEM INITIALIZATION 9

2.2 FILE NAME CONVENTIONS 10

2.3 MEMORY MANAGEMENT 12

2.3.1 MEMMGR 13

2.4 COMMAND STRING INTERPRETATION . '. . . . .13

2.5 ERROR HANDLING 15

2.6 PROGRAM EXECUTION OF COMMANDS 15

CHAPTER 3 - 1/0 STRUCTURE 16

3.1 OVERVIEW 16

3.2 I/O REQUESTS - SYSTEM CALLS 17

3.3 THE 'ASSIGN' I/O REQUEST 19

3.4 STANDARD RIO I/O DEVICES 21

3.4.1 ZDOS 213.4.2 DPS 213.4.3 NULL 213.4.4 CON 223.4.5 PCON 273.4.6 FLOPPY 273.4.7 DISK 27

CHAPTER 4 - PROGRAM INTERFACE 28

4.1 PROGRAM LOCATION 28

4.2 PARAMETER STRING ADDRESS 29

4.3 PROGRAM STACK SPACE 29

4.4 PROGRAM TERMINATION - ERROR HANDLING ... 29

4.5 SYSTEM CALLS - SYSTEM ENTRY POINT .... 30

4.6 INTERRUPT STATUS 31

4.7 I/O UNIT UTILIZATION 31

4.8 PROGRAM EXAMPLES 32

CHAPTER 5 - RIO COMMANDS 33

5.1 ACTIVATE 35

5.2 ALLOCATE 37

5.3 BRIEF 39

5.4 CAT 40

5.5 CLOSE 44

5.6 COMPARE 45

5.7 COPY 47

5.8 COPY.DISK 49

- 11 -

5.9

5.10

5.11

5.12

5.13

5.14

5.15

5.16

5.17

5.18

5.19

5.20

5.21

5.22

5.23

5.24

5.25

5.26

5.27

5.28

5.29

5.30

5.31

COPYSD I 51

DATE 53

DEACTIVATE 54

DEALLOCATE 55

DEBUG 56

DEFINE 60

DELETE 63

DISK. FORMAT 67

DISK.REPAIR 70

DISK. STATUS 72

DISPLAY 74

DO 75

DUMP 79

ECHO 80

ERROR 81

ERRORS 82

EXTRACT 83

FORCE 84

FORMAT 85

HELP 88

IMAGE 89

INITIALIZE 90

LADT 91

- m -

5.32 MASTER 92 x—

5.33 MOVE 93

5.34 PAUSE 98

5.35 RELEASE 99

5.36 RENAME 100

5.37 RESTORE_TABS 102•

5.38 SAVEJTABS 103

5.39 SET 104

5.40 STATUS 109

5.41 VERBOSE Ill

5.42 XEQ 112

5.43 EXPRESSION EVALUATION 113

CHAPTER 6 - ZDOS 114 ^_J

6.0 ZDOS OPERATION 114

6.1 INITIALIZE 122

6.2 ASSIGN 123

6.3 OPEN 125

6.4 CLOSE 132

6.5 REWIND 134

6.6 READ BINARY 135 *

6.7 WRITE BINARY 137

6.8 WRITE CURRENT 139

6.9 DELETE 140

- IV -

6.10 DELETE REMAINING RECORDS 142

6.11 ERASE 143

6.12 READ AND DELETE 145

6.13 READ CURRENT 147

6.14 READ PREVIOUS 149

6.15 READ DIRECT 151

6.16 SKIP FORWARD 153

6.17 SKIP BACKWARD 155

6.18 SKIP TO END 157

6.19 RENAME 158

6.20 UPDATE 160

6.21 SET ATTRIBUTES 162

6.22 QUERY ATTRIBUTES 164I

CHAPTER 7 - DPS 166

7.1 ZILOG DISK CONTROLLER 166

7.2 DPS OPERATION 168

7.3 SOFTWARE ORGANIZATION 171

7.4 DPS ALLOCATION 172

7.4.1 Sector 0 Format 1727.4.2 DPS Allocation Algorithm .... 173

7.5 THE BARE DISK CONTROLLER 174

7.6 CONTROLLER BOOTSTRAP OPERATION 177

7.7 SYSTEM BOOTSTRAPPING on the MCZ-1/35 . . 179

- V -

APPENDICES

APPENDIX A -APPENDIX B -APPENDIX C -APPENDIX D -APPENDIX E -APPENDIX F -

APPENDIX G -APPENDIX H -APPENDIX I -APPENDIX J -APPENDIX K -

RIO/ZDOS/DFS Error CodesRIO Command Syntax SummaryRIO System ConstantsConverting Files to RIO FormatAltering Default RIOI/O Request Vector Format andI/O Request Codes

Program ExamplesInternal Command Table ContentsRIO Memory ManagerDescriptor Record of Procedure Type FileZDOS/DFS Command Summary

PREFACE

This manual provides an introduction and user's manualfor the RIO operating system used with Zilog's Micro(ZDS). Detailed description is provided for systemfeatures, including the bootstrap process, the RIOExecutive, default console drivers, I/O structure,program interface, and the Zilog Floppy Disk File System,ZDOS, and the Zilog Hard Disk File System, DFS.

Other pertinent documentation with which the reader maywant to become familiar includes:

Z80-MCZ PROM User's Manual

Z80-ZDS PROM User's Manual

Z80-RIO Relocating Assembler and Linker User's Manual

Z80-RIO Text Editor User's Manual

This manual makes use of the following conventions ofnotation:

Optional portions of a modifier are enclosedin brackets, [].

The symbol for logical or, 'I', is used if eitheroption can be issued. STATUS [0 I 1...7] meansthe command can be issued as STATUS 0, STATUS 1,...STATUS 7, or simply as STATUS.

Parameters which can be repeated zero or more timesare enclosed in parentheses end followed by anasterisk - e.g., (filename)*.

Parameters which can be repeated as necessarybut must appear at least once are enclosed inparentheses and followed by a plus sign - e.g.,(filename)+.

- VTI -

All memory addresses and constants referring tomemory allocation are given in hexadecimal. Unlessso specified, other constants are given indecimal. Hexadecimal constants are also indicatedby an 'H' immediately following the hex digits,e.g., 4FH.

CHAPTER 1

INTRODUCTION AND OVERVIEW

1.1 INTRODUCTION

* The Z80 Operating System with Relocatable Modules and I/OManagement, or RIO, is a general-purpose computing systemdesigned to facilitate the development and integration ofuser's programs into a production environment. RIO isavailable on various Zilog hardware configurationsincluding the Z80 Micro Computer System (MCZ-1) series and theZ80 Development System (ZDS). The Z80 Development Systemprovides extensive hardware debugging aids to assist theengineer/programmer in Z80-based hardware/software systemdesign. The user has a choice between a modest environment

i - with a minimum of system support or an enhanced environment' which provides access to an assortment of system support

utilities including the Zilog Floppy Disk File System,ZDOS, and the Zilog Hard Disk File System, DFS.

In the modest environment, the user has access to 3K(1K=1024) bytes of dedicated read-only memory whichcontains a program debugger with file manipulationcapability, a floppy disk driver which supports up to eightdisk drives, and a basic console driver with provision forpaper tape operation.

In the enhanced environment, the user also has access tothe RIO Executive, ZDOS, DFS, and a collection of disk-resident

» software including a text editor, macro assembler, andlinker. The RIO Executive provides standardized I/Omanagement permitting device independent programdevelopment and utilization of alternate or multiple filesystems. ZDOS provides a versatile floppy disk based filesystem with variable record length files; up to 16concurrently active files; management of user-definedscratch files which are automatically deallocated afteruse; and support of up to eight disk drives for over 2.5megabytes of on-line storage. The hard disk file system,

DPS, supplies similar features on 10 megabyte high speeddisks. The text editor, macro assembler and linker givethe user full support in program development, minimizingassembly time with relocatable modules while allowing com-plex memory overlay structures. In addition, a consoledriver is provided which allows user definition of characterdelete and line delete symbols, automatic insertion of anynumber of line feeds, and automatic echo mode to accommodate awide range of console devices.

- 2 -

1.2 SYSTEM OVERVIEW

, \

1.2.1 HARDWARE CONFIGURATION

The RIO Operating System is designed to operate with the 4KPROM in either the Zilog Micro Computer System (MCZ) orDevelopment System (ZDS) . A minimum configuration of 32K(1K=1024) of random access memory, one disk drive, and aconsole device is required.

MCZ 1/20 Zilog Micro Computer System is equipped withtwo floppy disk drives. The left drive is designated drive"2 1 and the right drive is designated drive '0'. The ZilogDevelopment System (ZDS) also has two drives, but thedesignations are '!' and '0' for left and right, respectively.

The MCZ 1/35 uses hard disk cartridge and fixed platter drivesThe usual configuration consists of one fixed platter and onecartridge drive, designated '0' and '!', respectively. Thesystem will support up to 8 drives.

1.2.2 FILE SYSTEMS

For systems using floppy disks, ZDOS controls the organizationand allocation of the sectors on a diskette. While the basic unitof disk allocation is the sector, the fundamental structure withinZDOS is the "file1. A file consists of zero or more sectorsof data which contain logically-related information. Eachfile has a set of attributes including a name of from oneto thirty-two characters, a set of (possibly null)properties, a type, a subtype, and a record length. Thesmallest amount of information that can be read from orwritten to the disk is the contents of one sector, but moreefficient operation can often be achieved by grouping fromone to thirty-two contiguous sectors (a complete track)into one unit which is then read or written together. Thisunit is called a 'record' and the number of bytes of datein the record is the record length. A record may consistof 1, 2, 4, 8, 16 or 32 sectors; therefore the recordlength may be 128, 256, 512, 1024, 2048, or 4096 bytes.

On systems with hard disks, the Disk File System (DPS)provides a similar file structure. The bulk of the DFS

- 3 -

software runs in the memory of an intelligent disk con-troller; only a small interface routine resides in themain system memory, thus resulting in a large memoryspace saving. DPS files have the same structure as ZDOSfiles, except that multiple-sector records are not sup-ported. The sector (and record) size is 512 bytes.

The properties of a file are defined by the user and mayinclude any combination of the following:

1) write protected - may not have contents altered;

2) erase protected - may not have contents deleted;

3) locked attributes - may not have its attributeschanged (a file's attributes include itsproperties, type, subtype, and other informationincluded in the file's 'descriptor record1; seebelow);

4) random - file is in a format for randomaccess;

5) secret - file is not normally found in directorysearches (see below).

When a file is created, the user specifies its type,which must be exactly one of the following:

1) directory - a file directory (see below);

2) procedure - file contains information whichcan be loaded into memory and executeddirectly;

3) ASCII - file consists of symbols encoded inthe American Standard Code for InformationInterchange format, such as those producedby the editor or console input device;

4) binary - data of an unspecified format.

In addition to the file type, the user may define asubtype, which is a value ranging from 0 (default)to 15. The subtype is useful to differentiate betweenfiles of a certain type. For instance, RIO requiresall I/O device files to be of type procedure, subtype 1.

- 4 -

The file system maintains a special file on each disk which isnamed 'DIRECTORY'. In this file are the names of all files(including itself) on the disk and the location of thefirst record of each file. The first record of each fileis one sector long (regardless of the record length of the file)and is called the 'descriptor record". All the file attributesincluding entry point (where execution may begin), date ofcreation, date of last modification, first data recordaddress, last data record address, record length, andrecord count are contained in this record. Each record ofthe file contains pointers (disk addresses) to the previousrecord and the subsequent record in the file. Note thatrecords which are logically in order according to filecontents may, in fact, reside in an arbitrary order on thedisk. This 'linked' structure allows maximum utilizationof the disk. The disk allocation algorithm in ZDOSAttempts to localize the disk sectors used for a singlefile. Note that the sectors which comprise a single filerecord are physically contiguous on the disk and aretherefore always read or written as a single disk access.

ZDOS maintains a bit map to keep track of allocated vs.unallocated disk sectors. This map resides on threesectors of the diskette which are preallocated by the disketteformatting utility and is read into memory by the Initializecommand or automatically by ZDOS when the diskettes areexchanged. The map is written from memory to the diskettewhen a file is closed following an allocation change.If the diskette is formatted as a 'system' disk, additionalspace is preallocated for the system bootstrap routine andthe GET/SAVE command package (see the Debug command,section 5.13).

' \

Under DPS, the unallocated hard disk sectors are linkedin 6 free chain. The allocation and deallocation ofsectors is a matter of removing sectors from or addingsectors to the free chain. System disks contain the'BOOTSTRAP' file contains the file system that is loadedat system initialization.

While files created by the RIO Operating System or PROMdebugger on the Development System or Micro Computer Systemare compatible, the bootstrap is not. Thus files may beinterchcnged between systems (procedure files are generallynot transferable) but a system disk will bootstrapcorrectly only on the system for which it was designed.

- 5 -

1.2.3 SYSTEM INITIALIZATION

Where ZDOS is the primary file system, the bootstrappingof the operating system is from floppy disks. When acarriage return is entered as the first character afterpressing RESET, or when the OS command is entered whilein the Debug environment, the PROM monitor reads a 128 byteminibootstrap from track 17, sector 3 of the disk in drive0. This program initiates a directory search on drive 0 forthe files OS and ZDOS, which are then read into memory.Execution is started at the entry point of OS. This isone of two instances where a disk formatted as a systemdisk must be ready in drive 0. The other is when using theGET or SAVE commands of the PROM Debugger. In all othercases, while a particular drive search order may be implied,there is no difference in the utilization of drives.

This process is similar on systems which use DFS as theprimary file system. The file 'BOOTSTRAP' contains thefile system, which the disk controller loads directlyfrom disk, using the standard disk search sequence ofdrive 1, drive 2, ..., drive 0. The PROM monitor then maycommunicate directly with the controller to load the file'OS', again using the standard drive search sequence.

—̂sWhen execution of the file OS begins, an initializationprocedure is performed that may or may not involve otherfiles. A means is provided to read a set of commands froma file to extend this initialization process. In this way,a turnkey system can be implemented simply by editing theexternal initialization command file. Alternatively, thefile OS can be edited directly to execute a user-definedcommand sequence at initialization time (see Appendix E). Aspart of the initialization process, memory is sized to determinethe current configuration. If the sizing procedure determinesthe end of memory to be at other than a 4K boundary, awarning message is issued to indicate possible memoryfailure, thus providing a frequent diagnostic of systemmemory.

After initialization, OS responds with the message 'RIO REL v.cc1

(Where 'v' is the release version and "cc" is the release cycle)followed by the system prompt character '%'. Any time RIOis ready to accept command input, this prompt character isprinted.

- 6 -

1.2.4 COMMANDS

Command implementation is in one of two forms: for'internal' commands, the code which actually implements thecommand is a part of the file OS and resides in memorywhen OS is loaded; 'external1 commands are simply procedure-type files which are loaded into memory for execution. Ifa command is external, a search is made of all accessibledirectories for a file of the given name. In this context,the available command set is limited only by the particularfiles of procedure type which are on the "ready1 drives ata given moment. Therefore, user extension, modification,or replacement of the Zilog supplied software is a matterof file manipulation. For example, replacement of the filenamed OS on a system diskette with another file of thesame name results in the automatic bootstrap of auser-defined software package. The majority of thestandard RIO command set are implemented as external files.(Internal commands are noted as such in the command

fc description, Chapter 5).f

1.2.5 I/O

The I/O structure of RIO is designed to facilitate programdevelopment independent of physical device characteristics.To this end all I/O requests are made with reference to a'logical unit1 which may correspond to any of a given setof 'I/O devices'. In this way device modifications canoccur with minimal impact on existing software.

The software required to control a particular hardwaredevice or set of devices is termed the 'device handler'(used interchangeably with 'I/O device', 'I/O driver 1,'device driver 1, or simply 'device'). Before a particulardevice can be accessed, its device handler must be loadedin memory. Initialization procedures may be required, andit may be desirable for the memory it utilizes to beprotected from concurrent software routines. RIO providescommand level control of these tasks and assumes that oncethis is done, the device is ready to handle I/O requests.This process is referred to as "activating" a device.

The fundamental concept underlying the RIO I/O structure isthat of the 'logical unit' (also referred to as 'unit' or

'I/O unit1) which enables I/O activity independent of aparticular device. Units are 'defined1 by linking ormapping a unit to a given device. I/O requests may not bemade on undefined units, although some requests inherentlyresult in unit definition.

Three units are predefined by RIO to handle console input(unit 1) , console output (unit 2) and high volume printedoutput (unit 3). Unit 0 is used by system functions and isnot available to the user. Units 4-20 (in the standardsystem) are available for user programming. Units 1, 2,and 3 have the mnemonics CONIN, CONOUT and SYSLST,respectively which can be used interchangeably with theliteral unit designations, where applicable.

I/O requests are made with a standard vector format,containing information such as unit, data transfer address,data length, completion codes, and an optional supplementalparameter vector address. I/O requests are made byproviding a pointer to the request vector (see below) andmaking a system call.

Note that programs which use the RIO I/O structure canremain unchanged so long as compatible I/O devicesare provided. For instance, a BASIC system couldimmediately utilize a line printer by redefining SYSLST.No other software changes would be required.

- 8 -

CHAPTER 2

RIO EXECUTIVE

2.1 SYSTEM INITIALIZATION

As part of the system bootstrap procedure, the RIOExecutive (OS) performs a series of initialization tasks.CON, the system console device, is initialized. Theprimary file system (or the master device - see section3.1) is then initialized to identify the drives which areavailable. Memory size is determined by writing andsubsequently reading a known pattern through memory untilthe comparison fails. If the last 'good' address is onother than a 4K boundary, i.e., nFFF, a warning message isgenerated to indicate possible memory failure. Memoryoccupied by PFOM, OS, ZDOS, and CON is allocated.If the physical end of memory is other than FFFF, thenonexistent memory is also allocated (see section 2.3).

Initialization of the console device assigns default values tothe line delete (LINDEL) and character delete (CHRDEL) symbolsand the number of null characters (NULLCT) and line feeds (LFCNT)to be inserted after every carriage return. These values areNULLCT=1 (a single null character is sufficient for most CRT'Sat speeds up to and including 19.2 Kbaud), LFCNT=1, LINDEL=7FH(rubout or delete), and CHRDEL=08H (control-H or backspace). Theautomatic line feed insertion mode (AUTOLF) and consolecharacter echo (ECHO) modes are set "on", and full duplexoperation selected.

If the external initialization (EXTINI) bit (bit 2) of thesystem flag SYSFLG (see Appendices C and E) is set (=1),the external initialization command is executed. If theEXTINI bit is reset (=0) this initialization is notperformed. Zilog-supplied software has this bit set;the external initialization command consists of"DO OS.INIT1. This command causes the commands on fileOS.INIT, default drive search sequence, to be executedas part of the initialization process.

- 9 -

The user may alter the external initialization bit usingthe PROM Debugger GET/SAVE commands (see section 5.13) .See Appendix E for examples. In addition, the user canalter the initialization procedure by editing the contentsof the file OS.INIT.

After possible redefinition of logical units by thecommands on the external initialization file, the existingunit definitions are saved as the defaults. Subsequentunit definitions restoring a unit to its default willresult in the unit definition existing at this point in theinitialization process.

Concluding the bootstrap and initialization procedure, RIOprints an identifying message, the command prompt characteris sent to the console output unit, and the system waits forcommand input.

2.2 FILE NAME CONVENTIONS

In the most general case, file names in RIO consist ofthree parts:

1) the device name specifying which device tosearch for the named file (e.g. $ZDOS);

2) the drive designation restricting the searchto a particular element of the device (e.g. drive 2)

3) the file name itself.

The file name consists of from one to thirty-twocharacters, the first of which must be alphabetic.Subsequent characters may be alphanumeric ("A1...^1 or'0'...'9'), or one of the special characters, question mark('?'), underbar ('_'), or period ('.')• Upper and lowercase characters are interpreted as entered, i.e., 'Status1is not the same as 'status1.

When a period ('.') is used within a file name, thosecharacters in the name including and following the periodare referred to as a file name "extension". For instance,the file name OS.INIT has the extension ".INIT", while thefile name BOOK.CHAPTER.1 has the multiple extensions'.CHAPTER1 and ".I". The notion of file name extensions is

- 10 -

a useful convention for the user who wishes to categorizecertain files by their names. Some programs such as theassembler or editor require that file names end with aparticular extension—source files for the assembler mustend in .S, while the editor creates a backup file with theextension .OLD--however, in general, RIO makes nodistinction concerning extensions. In other words, aperiod is treated as any other valid character in a filename.

The drive designation consists of a single character from'O1...1?1. In the Zilog Development System, drive '0' isthe right-hand drive, drive '!' is the left-hand drive. Inthe standard Zilog Micro Computer System, drive '0' is theright hand drive, drive '2' is the left-hand drive. Thecharacter '*' denotes a standard search sequence ofdrives '!', '2' , . . . '71 , '0'.

Device names are essentially file names prefixed with thecharacter '$'. This character merely serves as a delimiterand is not really part of the name itself. In addition,the device name must have been made known to the systemeither by default initialization procedures or by theActivate command (see section 5.1). The devices known toOS after initialization are:

ZDOS file system (where floppy diskettes arethe primary file system media)

DPS file system (where hard disks are theprimary file system media)

CON console driverNULL null operation device (see section 3.4.2)PCON PROM console driverFLOPPY PROM floppy disk controller interfaceDISK PROM hard disk controller interface

When constructing a file name, the character ':' is used toseparate a device name from a drive designator and thecharacter '/' is used to separate the drive designator ordevice name from the file name.

- 11 -

For example, the command STATUS may be entered as:

STATUS/STATUS0/STATUS:0/STATUS$ZDOS/STATUS$ZDOS:0/STATUS

In the first case, the device name and drive designationare given default values. The default device is designatedby the user to be the source of all "unqualified1 (noexplicit device name) files and is termed the Masterdevice. Default is ZDOS for floppy disk systems, and DPSfor hard disk based systems, but may be redefined (and alsodisplayed) by the MASTER command (see section 5.32). Thedefault drive search order for command files is drive 'O1,followed by the standard search sequence (designated bydrive '*') if the initial search of drive '0' isunsuccessful.

All 'qualified1 file names (those with device or drivedesignations or the prefix '/') are treated as externalcommands. Thus, /DEBUG is not the same as the internalcommand DEBUG.

2.3 MEMORY MANAGEMENT

The RIO Executive includes a memory manager which controlsallocation/deallocation for the system. A bit map is usedto reflect the status of each 128 byte segment in the 65Kaddress space. A set bit (=1) indicates that the segmentin question is allocated. A reset bit (=0) indicates thesegment is available for allocation. During systeminitialization, memory which is occupied by the system orwhich is nonexistent is marked as allocated. Subsequentmemory utilization should be coordinated with informationsupplied by the memory manager, entry point MEMMGR, toavoid conflicting uses of the same memory segment.

- 12 -

2.3.1 MEMMGR

Subroutine calls to the system entry point MEMMGR can beused to allocate, deallocate, or determine the status ofdesignated memory areas. Appendix I gives the details ofthese subroutine calls. Alternately, memory segmentsmay be allocated, deallocated, or the current memorymap displayed from the command level. Refer to Chapter 5for details of the ALLOCATE, DEALLOCATE, and DISPLAYcommands.

2.4 COMMAND STRING INTERPRETATION

Whenever RIO is ready to accept command input, the promptcharacter '%' is printed on the console output device. Allcharacters entered (up to a maximum of 256, subject todevice driver editing, see section 3.4.3) after the promptcharacter, up to and including the first ASCII carriagereturn (CR), are entered into the command string buffer.This input constitutes the command input string. Thecommand separation character ';' is used to terminate acommand but does not terminate command input. Thus, asmany commands may be entered at one time as can becontained in the 256 byte command string buffer.

Several characters have special significance to the commandstring interpreter. As noted above, carriage return andsemicolon are used to terminate commands and aretherefore referred to as terminators. Space, horizontaltab (ASCII 09H) , and left and right parentheses can sep-arate command names from optional parameter lists andare referred to as delimiters.

There are two modes of providing system information to theuser. In verbose mode, each command is echoed as it isextracted from the command string buffer. This is usefulto verify input or when entering multiple commands percommand string. In brief mode, commands are not echoed(except as entered).

After a command has been located in the command inputstring, an attempt is made to match it against a list ofinternal commands. In doing so, an internal command namemay be abbreviated to the extent to which it isdifferentiable from other internal commands. For example,

- 13 -

the strings 'D', 'DE1, 'DEB', 'DEBU', or 'DEBUG1 allresult in entering the PROM Debugger. If the abbreviationdoes not identify a unique internal command, then the firstentry will be chosen. For example, 'D' and 'DE1 refers toDEBUG rather than DEALLOCATE (Appendix H lists the internalcommand table contents in order). If no match is found,the command name is assumed to be the name of a file. Thesearch order of drive '0', followed by drive '*', is thenused in an attempt to open the file. If the file is locatedand is of type procedure, a request is made to the memorymanager to allocate the space required to load the file.The values LOW_ADDRESS and HIGH_ADDRESS in the file'sdescriptor record define the memory which will be alteredas a result of loading, and generally represent the lowestsegment starting address and highest segment ending address,respectively. Note that since file I/O is not buffered, thelatter is a function of the record size and may not equalthe highest segment ending address. For example, loading a fileconsisting of 40 bytes linked at location 5000 having 80 byterecords will affect memory locations 5000-507F rather than5000-503F since a minimum of one record is required tocontain the file. If the allocating request is successful,the file is loaded into memory.

After loading the file, two things may inhibit itsexecution. If it has a null entry point (=0) or if thedelimiter following the command name is a comma, thecommand string interpreter suppresses command execution andinstead processes the remainder of the command input string,if any. In this way, files may be loaded together andcontrol passed to any one of them. For example, it may bedesired that a user program and debugger be loaded withcontrol passing to the debugger where instructions may beexecuted one at a time, breakpoints set, or registers givenappropriate values prior to user program execution.

In the event command execution is not inhibited, a stackmay be allocated consistent with the size specified in thedescriptor record by LINK or IMAGE. (If a null (=0) stacksize is requested, dispatch is made to the loaded fileusing the system stack space.) When several procedure filesare loaded together, a stack is allocated for the first filein the command string with a nonnull stack size; no otherstack space is allocated for the files loaded together. Twoattempts are made to allocate the stack area. First the mem-ory area following the loaded procedure to the end of memory issearched and, if unsuccessful, a second attempt is made, search-

- 14 -

ing from 0 to the beginning of the loaded file. If both attemptsfail, no stack space is available and command execution cannotbe initialized. Thus, normally the user stack is located im-mediately after the loaded file.

Since it is more efficient to not repeatedly load a commandfile which is to be executed several times in succession,RIO remembers the entry point of the last loaded file andprovides the internal command XEQ (see section 5.42) totransfer program execution to that address. Most RIOcommands can be executed repeatedly in this way.

Prior to executing the external command file, the memorymap is examined to identify those segments which wereallocated as a result of loading the file(s) to beexecuted. When return to OS is made, these segments willbe deallocated. Note that in the event a file is loaded,but not executed, the space it occupies will be allocateduntil either explicitly deallocated (see the RELEASEcommand, section 5.35) or a return to OS is made from anyexternal command file.

2.5 ERROR HANDLING '1 '

Wherever errors occur in the processing or execution ofsystem commands, a message is directed to the consoleoutput device. Command processing then continues with thenext command in the command string, if any.

2.6 PROGRAM EXECUTION OF COMMANDS

Any command or user program executable from the system :

console can also be executed from a program. This isaccomplished by making a system call to RIO with referenceto the command string to be executed. In this way programscan be chained together or complex overlay structureseasily implemented. (See the Relocating Assembler andLinker manual for details of overlay creation.) Systemcalls and the RIO system entry point are described insections 3.2 and 4.5.

- 15 -

CHAPTER 3

I/O STRUCTURE

3.1 OVERVIEW

The I/O architecture of RIO is designed to a) facilitateuser construction and implementation of device drivers toservice the I/O requests of system or user programs; and b)simplify and standardize interface to all I/O drivers.To this end, all I/O requests are made to RIO withreference to a logical unit. RIO determines the properrouting for the referenced unit and passes control forservicing of the I/O request to the appropriate devicedriver.

The internal structures supporting this facility includethe Active Device Table (ADT) and Logical File Table (LFT).The Active Device Table has one entry for every deviceknown to the system at a given time and includes the devicename and entry point. Devices are made 'known' to thesystem via the ACTIVATE command (see section 5.1), or theymay be removed from the ADT by the DEACTIVATE command (seesection 5.11). The current ADT contents can be reviewed withthe LADT command (List Activate Device Table - see section5.31).

Devices which are known to the system may be used toqualify a file name, thereby linking a logical unit to thenamed device. Unqualified file names (those without adevice name prefix) are given a default routing to themaster device (see MASTER, section 5.32).

The link between a logical unit and a specific deviceexists in the Logical File Table, each entry of whichcontains the address of the device that the correspondingunit is linked to. Before I/O requests may be processed viaa logical unit, the unit must be defined. This unitdefinition may occur via the 'Assign1 I/O request (see

- 16 -

Section 3.3) or it may occur as a result of the DEFINEcommand (see section 5.14).

As a part of system initialization units 1, 2, and 3are defined as the console input, console output, andvolume output devices, respectively, and are given themnemonics CONIN, CONOUT, and SYSLST. Although theseunits are available for redefinition by the user, RIOassumes that these units represent the equivalent devices,

3.2 I/O REQUESTS - SYSTEM CALLS*

I/O requests are accomplished by making a subroutine callto the RIO entry point SYSTEM (see Appendix C). The IYregister must hold the address of a request vector, of thefollowing format:

Byte , [. Contents

IY -> 0 logical unit number1 . request code2-3 data transfer address4-5 data length6-7 ' completion address8-9 error return addressA completion code

B-C , supplemental parameterinformation

Logical Unit Number/

The logical unit number is an integer in the range 1 toMAXLUN (20 in the standard system). Units 1, 2 and 3are predefined by RIO to be console input, console output,and volume output.

Request Code

Identifies the operation requested.

- 17 -

Data Transfer Address

The memory address at which data movement will begin.

Data Length

Number of bytes of information in the transfer. This willbe reset by the device to reflect the actual number ofbytes transferred upon completion of the operation.

Completion Return Address

If bit 0 (least significant) of the request code is set(=1), those devices which are interrupt-driven will returncontrol to the calling routine as soon as possible andcontinue the operation under interrupt control. At thetime that the operation is completed, transfer will be madeto the completion address which should exercise theresponsibilities of an interrupt service routine (i.e., itmust preserve all registers). However, an RETI instructionshould not be executed, since lower-level interrupts areenabled by the interrupt handler. (If immediate return isdesired, care must be taken not to change any words in theparameter vector, or use or change the data, until theoperationindicated (i.e., bitaddress is ignored.

is complete.) If return on completion is0 is reset=0) the completion return

Error Return Address

If nonzero, the error return address will be used as thereturn address in the event of an error condition. Theroutine thus entered should execute an RET instructionafter processing the error condition. Since the errorcondition is detected by the I/O driver, and the call tothe error return address is made there, the programmershould not make assumptions about the elements on thestack above the return address.

- 18 -

Completion Code

The completion code is always set by the device and willindicate completion of the request and any errors. Errorcodes are universal (i.e., for all devices to which a givenerror applies, the error code is the same). Generally, bit7=1 is used to signal operation complete, with bit 6=1indicating an error condition (see Appendix A). All I/Odevices must set this completion code prior to returning tothe calling procedure.

Supplemental Parameter Information (Optional)

The two bytes of supplemental paramater informationmay be used to hold either additional data or anaddress to a vector supplement. The format ofsuch an extension is defined by the device for agiven request.

3.3 THE 'ASSIGN' I/O REQUEST " ; ,--

If a system call is made with the request byte equal to the'ASSIGN1 request code (02), the request is trapped by RIO forpossible unit definition or supplemental parameter vectormanipulation. The exact sequence is controlled by a set offlags in the first byte of the supplemental parametervector .

If bit 7 (the most significant bit) of the flag byte isreset (=0) , then RIO will format the supplemental parametervector (see Appendix F) , including the drive name, filename length, and file name fields, from information derivedeither from the string referenced by the Data TransferAddress of the request vector (bit 1=0) or from the stringcontained in the file name field (bit 1=1).

For example, suppose a user program requires one parameterwhich can be a qualified or unqualified file name. Theuser may elect to parse this parameter string in order todetermine the device name (if any), drive designation (ifany), file name and file length. Alternatively, a requestvector can be set up with the Data Transfer Address fieldreferencing the parameter string and the first (flag) byte

- » -

of the supplemental parameter vector with bits 7 and 1reset to (this file name string must be terminated by adelimiter). RIO then moves the file name into the filename field of the supplemental parameter vector and setsthe name length and drive designation. If no name isgiven, the name length field is set to zero. If no drivedesignation is given, the standard search sequence symbol'*' is put in the drive designation field. Moreimportantly, the logical unit referenced in the requestvector is linked to the device specified as part of thefile name string, or the master device, if no device nameis given.

As a second alternative, the user program can set bit 1 ofthe flag byte after moving (or assembling) the entireparameter string into the supplemental parameter vectorfile name field. RIO then formats the rest of thesupplemental parameter vector in the same way as before.

If bit 7 of the flag byte is set (=1), the vector (andsupplemental parameter vector) is assumed to be in acorrect format, i.e., all fields hold valid information.If bit 0 is also set, the unit is linked to the masterdevice. If bit 0 is reset, unit redefinition does notoccur, maintaining the current unit-device link. In thislast case, previous unit definition must have taken place.After the preceding steps are taken, the I/O request ispassed to the intended device for processing. SubsequentI/O requests are routed directly to the device.

The following table summarizes the effects of specificsupplemental parameter vector flag byte values during the'ASSIGN1 I/O request:

Flag Byte Effect on ASSIGN I/O Request(hex)

0 (bit 1 reset) RIO formats SupplementalParameter Vector, Data TransferAddress is the address of thefile name string

2 (bit 1 set) RIO formats SupplementalParameter Vector, file namefield contains file namestring

- 20 -

80 (bit 7 set andbit 0 reset)

81 (bit 7 setand bit 0 set)

RIO passes request directlyto device (previous unitdefinition required)

RIO links unit tomaster device

3.4 STANDARD RIO I/O DEVICES

Five devices are known to RIO after default systeminitialization:

Device Description

ZDOS or DPSFLOPPY or DISKNULLPCONCON

Primary file systemInterface to device controllerNull devicePROM console driverSystem console driver

3.4.1 ZDOS

ZDOS is the file system for RIO on floppy disk based systemsIt distinguishes between logical units and supports namedfiles. Consult Chapter 6 for details of ZDOS request codesand request vector formats.

3.4.2 DFS

DPS is the ZDOS equivalent for hard disk based systems.Consult chapter 7 for details of DFS request codes andrequest vector formats.

3.4.3 NULL

NULL is a pseudo device driver which responds to allrequest codes. In most cases, the operation performed is,in fact, null—that is, no operation is performed.

- 21 -

Nonetheless, it responds with a completion code implyingcompletion of operation.

I/O Request Action

READ LINE completion code = C9H (end ofREAD BINARY file), data length = 0

All others completion code = 80H(operation completed)

This device provides a destination to which unwanted outputcan be diverted. It also provides a convenient way tocheck the integrity of a file. A file that can be copiedto NULL has no record pointer errors, since a complete READoperation is performed. In the same way, all files on adisk can be copied to the NULL device with a singlecommand, thus checking the file structure of the entiredisk.

3.4.4 CON

CON is the default RIO console driver especially designedfor CRT terminals. It is linked as part of the file OSwhich is loaded during system bootstrap. It allows theuser to define the line and character delete symbols andsupports arbitrary tab settings within a 134 characterline length. The standard RIO I/O vector format is usedin communicating with CON (see Appendix F).

During READ operations, entering the single characterdelete symbol (default = ASCII backspace, 08H) causes thelast character placed in the buffer to be logicallydeleted. A backspace, space, backspace sequence is sent tothe console to erase the character from the screen andreposition the cursor.

The line feed character (ASCII OAH) forces the cursor tothe start of the next line and places a space (ASCII 20H)in the buffer. This provides a convenient way to force thecursor or print mechanism to the beginning of the next linewithout terminating input. Note that no carriage return isplaced in the buffer, i.e., input is logically a singleline.

- 22 -

The line delete character (default = ASCII rubout ordelete, 7FH) deletes from the console display and theinput buffer all characters back to and including theprevious carriage return. (If linefeeds or backspaces havebeen entered, not all of the displayed input string iserased from the display).

The input delete character (control-X) flushes the inputbuffer and echoes a backslash carriage return on the consoledisplay. The effect of the line delete character and theinput delete character differs only when processing readbinary requests (described below).

To input verbatim special characters (like rubout, control-X,etc.), an escape character (backslash) is provided. So, toenter 'AB<rubout>' type 'AB\<rubout>'. To enter 'V, type'\\'. The backslash can be used to enter any character ,.other than carriage return.

The console driver is not interrupt-driven nor does itdistinguish between logical units. Modes can be set forlinefeed insertion, number of nulls, and character echo.If in AUTOLF ON mode (default), and the value of LFCNTis nonzero, then LFCNT linefeeds are output to the consolefollowing every carriage return. After line feed insertion(if any), and if the value of NULLCT is nonzero, then NULLCTnulls (ASCII 0) are output to allow time for print head orcursor repositioning. Default is NULLCT=1, which is sufficientfor CRT operation up to 19.2 Kbaud, and LFCNT=1. If in ECHO ONmode (default), then each character is echoed back to the ter-minal as it is read.

The ASCII tab character, control-I (09H), is expanded intoan appropriate number of spaces only when it is output to adisplay device, thus compacting symbolic files wherelarge numbers of spaces are required to improve readability.Tabs can be set by placing the cursor in the desiredcolumn and entering control-T (ASCII 14H) followed by"T 1. To clear a tab setting, the cursor is positionedin the column where the tab exists and the sequencecontrol-T followed by a 'space1 is entered.

The default tab settings are every eight columns, startingwith the leftmost column as column 0. To change this defaulttab setting, the user may use the SET TABSIZE command (see5.39) .

- 23 -

Tabs can be altered in the file OS (from the PROM Debugger)to change the default tab settings of every eightcolumns. Different tabbing environments can beestablished and made into a file so that they may bealtered by command (see Sections 5.37 and 5.38).

The following I/O requests are honored by CON:

INITIALIZE (OOH)

ASSIGN

OPEN

(02H)

(04H)

CLOSE (06H)

FEAD BINARY (OAH)

- Reads the current date into thedefault attributes table (see OPENbelow) and sets default status area.

- Null operation returnsoperation complete

- If data length = 0: null operation.Otherwise up to 20 bytes can berequested from the default set ofattributes including:

TypeRecord CountRecord LengthBlock LengthPropertiesStarting AddressBytes in last recordCreation Date

20H (ASCII)080H80H000Current Date

Null operation returns operationcomplete

Data length characters are receivedfrom the console. Entering acontrol-D (ASCII EOT, 04H) causesan end-of-file mark (FFH) to beplaced in the buffer and the requestterminated. Data length is reset tothe actual number of characters read,The parity bit of each character isreset.

- 24 -

READ LINE (OCH)

WRITE BINARY (OEH)

WRITE LINE (10H)

READ STATUS (4OH)

A maximum of data length charactersis received from the console up toand including the first carriagereturn. Data length is reset tothe actual number of characters read,The parity bit of each character isreset.

Data length characters are sent tothe console. An end-of-file mark(OFFH) results in termination of therequest. Data length is reset tothe actual number of characterswritten.

A maximum of data length charactersis sent to the console up to andincluding the first carriage return.Data length is reset to the actualnumber of characters written.

Transfers data length bytes of theCON status area to the areastarting at the data transferaddress. The CONSOL status flagsare defined as follows:

Byte

0 FLAG byte Bit 0 Local FlagBit 1 Auto linefeed

insertion (AUTOLF)On=l (default)Off=0

Bit 2 Echo On/OffOn=l (default)Off=0

Bit 3 Temporary Input buffer(TIB)Full=lEmpty=0 (default)

Bit 4 Echo carriage returnOff=lOn=0 (default)

Bit 5 Escape pendingNot pending=lPending=0 (default)

- 25 -

12

345, 138

reservedTIB

Cursor LocationreservedTabbing Drum

WRITE STATUS

DEACTIVATE

Bit 6 Local flagBit 7 Full/Half duplex

Half=lFull=0 (default)

Holds last character which hasbeen input from serialcommunication port but not yettransferred by a READ request.

134 positions used to mark tabsettings (nonzero values)

(42H) - Transfers data length bytesfrom the data transfer addressto the CON status area(see above).

(44H) - Null operation returnsoperation complete

READ ABSOLUTE (46H) Data length bytes arereceived from the consoledevice. Byte data is ac-cepted exactly as trans-mitted. Data length isunaffected.

WRITE ABSOLUTE (48H) - Data length bytes are sentto the console device. Bytedata is written exactly asgiven. Data length is un-affected.

All others - returns Invalid request completion code,

During write operations, entering a question mark causesthe operation to pause until a second question mark isentered. Entering an ESCape always immediately terminatesan I/O request.

- 26 -

3.4.5 PCON

The PROM console driver provides basic console I/O andbecomes the default device for logical units 1 and 2when OS encounters errors while requesting input fromor output to these units. Refer to the MCZ or ZDS PROMUser's Manual for full details.

3.4.6 FLOPPY

The PROM floppy disk driver is used by ZDOS as the accessprimitive for the floppy disk drives. Refer to the MCZor ZDS PROM User's Manual for full details.

3.4.7 DISK

DISK is the hard disk controller interface provided forthose utilities requiring access by sector address. Referto Chapter 7 for full details.

- 27 -

CHAPTER 4

PROGRAM INTERFACE

4.1 PROGRAM LOCATION

The following table describes the memory utilization forthe standard Microcomputer System (MCZ) and DevelopmentSystem (ZDS):

PROMPROM Dedicated RAMRIO Executive (OS)Console DriverZDOSUser Space

MCZ 1/20

0-FFF1000-13FF1400-24FF2500-29FF2AOO-43FF4400-

MCZ 1/35

0-FFF1000-13FF1400-24FF2500-29FF

2AOO-

ZDS (monitormode)0-BFFCOO-FFF1000-20FF2100-25FF2600-3FFF4000-

RIO commands, and, in fact, all RIO procedure files, arewritten as subroutines. That is, the system return addressis pushed on the stack when program execution of theprocedure file begins. Command files are generallyloaded into the low range of the program space forexecution. Entry points and file sizes can be obtainedusing the EXTRACT or CAT commands (see Chapter 5).

The minimum requirement for program execution concurrentwith RIO is that it be 'loadable' in the sense that thespace required to read the file into memory be unallocated,and that sufficient space be available in the system toallocate a user stack.

The current state of the memory allocation map can bedisplayed using the DISPLAY command (see Section 5.19). In theMCZ 1/20 configuration, memory from 4400H is unallocated and isavailable for system or user command execution. The only concernof the user is to insure that all programs which coexist in memoryform a disjoint memory space--i.e., if a program is to make systemcalls which result in execution of external procedure

- 28 -

files, then all programs referenced which reside in memoryconcurrently must not occupy the same address space.

4.2 PARAMETER STRING ADDRESS

When the command string interpreter identifies an externalfile name and succeeds in loading the procedure file, thevariable INPTR (see Appendix C) is given the address of thedelimiter following the file name. Programs may alterthe subsequent parameter string, if any, up to but notincluding the next terminator (carriage return or semicolon)Prior to program execution, this address is also pushedon the user stack, followed by the system return address.

4.3 PROGRAM STACK SPACE

To RIO, user programs look like subroutines. Beforeexecution, the system stack pointer is saved, a userstack is allocated (if the requested stack size is notequal to zero), and the parameter string address andreturn address in RIO are pushed. Dispatch is then madeto the program at its entry point. The stack size isdetermined by LINK or IMAGE, default being 80H bytes.Programs requiring larger stack space should be LINKedor IMAGEd with non-default stack sizes (ST=nn option).

4.4 PROGRAM TERMINATION - ERROR HANDLING

In addition, or as a supplement to internal error handlingprocedures, user programs may indicate certain errors toRIO by setting the variable ERCODE. In the RIO convention,if bit 6 is set, the value is taken to be an error code tobe displayed. If the error code value is one of thosewhich corresponds to a RIO error message (see Appendix A),then the message is printed instead of the value.

- 29 -

4.5 SYSTEM CALLS - SYSTEM ENTRY POINT

System calls for program execution of RIO procedure filesis accomplished by making a subroutine call to the systementry point SYSTEM (see Appendix C) in the same way as anI/O request: The IY register must hold the address of arequest vector of the following format:

Byte Contents

IY -> 0 zero - indicates request is a systemcall rather than an I/O request

1 unused2-3 command string address4-7 unused8-9 error handler addressA completion code

Command String Address

Address of the first byte of command input string.This string is of indefinite length, but must terminatewith a carriage return. The format for the command stringis the same as if entered on the console input device (seesection 2.3).

Error Handler Address

Address of the routine to which RIO jumps to handle errorconditions. If zero, no jump will be made and errorconditions will not be reported. This applies only toerrors either generated within RIO or reported to it viaERCODE.

Completion Code

Either the completion code generated internally by RIO orthe ERCODE reported by external file execution, ifapplicable, will be returned in this byte. Bit 6 set (=1)implies an error condition.

- 30 -

*** NOTE ***

When external files make system calls resulting inexecution of other external files, the current state of thememory map needs to be saved in order to determine whatspace to deallocate as a result of program loading. Thismap is saved on the user stack occupying a block of44H bytes. Care must be taken to allocate sufficientstack sizes for programs using this feature.

4.6 INTERRUPT STATUS

The initialization process associated with system restartsets interrupt mode 2, and the I register to the base addressof the interrupt vector, with interrupts enabled. Propersystem operation depends on this interrupt status. Withthis configuration the 8-bit vector supplied by theinterrupting device is used with the contents of the Iregister to form a pointer to the interrupt service routinestarting address. Zilog support devices can be programmedto supply appropriate interrupt vectors using this space.If program constraints make it necessary to alter theinterrupt mode or I register, they must restore the properconditions before making system calls that result in diskactivity. See Appendix C for the system interrupt vectoraddress for use in restoring the I register.

4.7 I/O UNIT UTILIZATION

The user is free to redefine all I/O logical units with theexception of '0'. Unit 0 is restricted to use by RIO.Units 1, 2 and 3 are predefined to be the console inputdevice, console output device and system volume outputdevice. Units 4 through 20 are initialized to be themaster device. Redefinition of these units may result inabnormal system behavior upon return to RIO. This meansthat in the standard RIO configuration which allows 0-20,17 units may be defined concurrently, with an additional3 units predefined by RIO for use as console or lineprinter I/O devices.

- 31 -

4.8 PROGRAM EXAMPLES

In Appendix G are sample programs which the user isencouraged to edit, assemble, link, and execute. Theyillustrate some of the concepts introduced in previoussections of the chapter, including console I/O, parameterstring processing, and file I/O.

- 32 -

CHAPTER 5

RIO COMMANDS

The following RIO commands are supplied as procedure typefiles which have the properties SECRET and WRITEPROTECTION. Each section is devoted to one command and hasthe following format:

SYNTAX

A description of the syntax of the command, givingparameter definitions, options and conventions. In allsyntax descriptions, the following notation is used:

Optional parts of a parameter list are enclosed inbrackets, '[...]'.

The symbol for logical or, '!', is used if eitherparameter separated by the symbol can be used, but notboth.

Parameters which can be repeated zero or more timesare enclosed in parentheses and followed by anasterisk, i.e., (param)*.

Parameters which can be repeated as necessary butmust appear at least once are enclosed in parenthesesand followed by a plus sign, i.e., (param)+.

- 33 -

Internal commands are indicated by notation just underthe command name in the upper right hand corner of thepage. In this case, the command as given in thesyntax also indicates the extent to which the commandmay be abbreviated. Upper case characters are requiredwhile trailing lower case characters are not.The command may be entered in either abbreviatedor unabbreviated form, in upper or lower case,e.g., 'DEB1 is the same as 'd'.

DESCRIPTION

A general description of command operation and definitionof options.

I/O UNIT UTILIZATION»

The logical units that the command uses for a particularfunction. I/O error messages generally refer to the uniton which the error occurred.

EXAMPLES

Illustrative examples of command invocation, whereappropriate.

Note that the length of the parameter string associatedwith any single command is intrinsically limited by thebuffer space associated with the command string. Thisimposes a 256 character limit on commands entered via theconsole input device and a 512 character limit on commandscreated by the editor for execution as part of commandfiles (see section 5.20). Of course, command files createdby copying the console input device directly to a file arelimited only by available memory when executing the commandfile.

- 34 -

5.1ACTIVATE ACTIVATE

SYNTAX

ACTIVATE device_name [address]

DESCRIPTION

Make a device known to the system by including it in theActive Device Table (ADT). It can thereafter be used as adevice name in qualified file names. If the optionaladdress is omitted, the file name referenced by thedevice_name will be located on the appropriate device andloaded if it is a device file (procedure type, subtype 1),has a non-null entry point, and does not overlay protectedmemory. The amount of memory allocated as a result ofloading the file is kept as the SIZE field of the ADT entryfor possible later use by the DEACTIVATE command. If theoptional address is given, the file is assumed to havebeen previously loaded in memory. In this case the addressparameter is taken as the device entry point. Since thememory bounds are unknown, the SIZE field of the ADT entryis set to a null value (0).

In either case, an Initialize I/O request is sent to thedevice to allow preparation for subsequent requesthandling.

I/O UNIT UTILIZATION

Unit 0: device file handlingUnit 2: error messages

- 35 -

ACTIVATE

EXAMPLES

ACTIVATE

ACTIVATE $MYDOS

locates file 'MYDOS1 on the master device usingthe default drive search sequence. It is thenloaded and given an Initialize request. Anentry is created in the Active Device Table.

ACTIVATE $MYDOS:4/$MY.VIDEO.DRIVER

locates file 'MY.VIDEO.DRIVER1 on device 'MYDOS1,drive 4. It is then loaded, an Initialize requestsent, and an Active Device Table entry created.

ACTIVATE $MY.PROM.DISK.DRIVER OBFD

creates an Active Device Table entry using OBFDHas the entry point. An Initialize request isgenerated.

- 36 -

5.2ALLOCATE ALLOCATE

(Internal Command)

SYNTAX

Allocate low_boundary high_boundary block_size

DESCRIPTION

Attempts to allocate block_size bytes (roundedup to a multiple of 80H bytes) of memory. The searchbegins at address low_boundary (rounded down modulo 80H),and the first block large enough and not extending beyondhigh_boundary (rounded up to the next multiple of 80H - 1)is marked as allocated in the system memory map. If allocationis not possible, the message INSUFFICIENT MEMORY is given.


None

EXAMPLES

ALLOCATE 0 FFFF 120

starting at memory address 0, a search is made fora 180H byte (120H bytes rounded up to a multiple of80H) memory segment.

ALLOCATE 5300 537F 80

attempts to allocate the single 80 byte memory segmentstarting at 05300H.

ALLOCATE 7400 8000 400INSUFFICIENT MEMORY

no 400H byte block is available in the address range7400-807FH.

- 37 -

ALLOCATE ALLOCATE

ALLOCATE 8EOO 9535 9535-8EOO

use the expression evaluator to determine theblocksize to be allocated. (780H bytes).

- 38 -

5.3BRIEF BRIEF

(Internal Command)

SYNTAX

Brief

DESCRIPTION

Enters console Brief mode. Commands are not echoed on theconsole output device as interpreted and some command filessuppress execution messages. See Verbose command.


None

EXAMPLES

I B

brief

- 39 -

5.4CAT CAT

SYNTAX

CAT (match_string I T=type I P=props I D=drive IF=format I L=listing_disposition I DATE rel dateCDATE rel date)*

DESCRIPTION

Prints a catalog of entries in the file systemdirectories which match the specified options. Givenwithout options, all (non-secret) files in each activedrive directory are listed. Options may be given in anyorder, and may appear more than once. Where options otherthan match strings are specified more than once, the lastone enterecF is used.

match_string

Fully- or partially-specified file names may be given, inwhich case only those directory entries which are identicalto one of the fully specified file names or match one ofthe partially specified file names, are listed. Partially-specified refers to the use of the symbol '*' which denotesan arbitrary character string. For example, '*XYZ' matchesany file which ends in 'XYZ1. 'ABC*XYZ' matches any namewhich starts with 'ABC1 and ends with 'XYZ1 but has any (orno) characters in the middle. The string '*' (which isequivalent to '**') matches any name. Match strings cannotbe qualified file names, i.e., no device or drive name maybe given (see the 'D=drive' option below).

- 40 -

CAT CAT

T=type

Only files of the given type will be listed. Type must beone of 'D' (directory), 'A1 (ASCII), 'B1 (binary) or 'P'(procedure). Subtype may also be specified immediately follow-ing the type (e.g., 'Pi1 refers to files of procedure type,subtype 1). If no subtype is given, all subtypes of the specifiedtype are listed.

P=props

will'E1

beOnly files with exactly the specified propertieslisted. Props must be from 'W (write protected),(erase protected), 'L' (properties locked), 'S1

(secret), "R" (random), 'F1 (force memory allocation), or'&'. Use of '&' will allow any file with at least thespecified properties to be listed. One or more propertiesmay be concatenated in which case only files with exactly(or at least, if '&' is included) the specified propertieswill be listed.

D=drive?

Only files from the specified drive will be listed. Drivemust be from '()'...'7'. Default is to search directoriesfrom all ready drives on the master device. If a device isspecified without a drive (i.e. D=$DFS), all ready drives onthat device will be searched.

F=f ormat - • - - - - - -

Specifies long (F=L) listing format. The short form(default) consists of name and drive while the long formgives name, drive, file type, record count, record length,file properties, starting address, date of creation, anddate of last modification. Additionally, the number offiles examined, the number of files listed, and the numberof sectors used by listed files are given.

- 41 -

CAT CAT

L=listing_disposition

The listing is normally routed to SYSLST but can be routedto any device or file. For example, L=$CON would routeoutput to the console (SYSLST may also be defined as thisdevice) or L=2/FILELISTING would route the output to file'FILELISTING' on drive 2 of the master device. All outputgenerated for the specified device or file will bebuffered, i.e., several lines will be transferred at onetime. While output is active at the console, entering a'?' character will cause output to stop until another '?'character is entered. If the ESCape character (ASCII 1BH)is typed, output will be terminated and control will returnto the Executive. The '?' and ESCape features applyonly to MCZ systems.

CDATE | DATE rel date

where rel is one of the relational operators '=','>', '<', '>=', '<='/ or '<>', and date is up to 6digits or '*' representing a date to be compared againstin 'yymmdd1 form. '*' in a digit position specifies thatthat digit will be considered equal to anything. A dateexpressed with less than 6 digits is treated as beingfilled on the right with '*'s.DATE refers to the date of last modification. CDATE refersto the date of creation. The entire option should bespecified with no intervening blanks. For example:

CDATE>=7805

refers to all files created with dates in May of 1978or later. This is equivalent to

CDATE>=7805**

If the referenced date field of the file descriptor hasa character which is not a digit, it will not match unlessthat digit position of the match date has an '*' in it.

- 42 -

CAT CAT


Unit 2: error messagesUnit 3: default listing destinationUnit 4: directoriesUnit 5: files listed in directoryUnit 6: non-default listing destination

EXAMPLES

CAT F=L

Lists all (non-secret) files (long format) fromall ready drives.

CAT D=$DFS:2 P=W SYS*

Lists all files (short format) on drive 2 on the device$DFS (if it is ready) which are write protected (only)and whose names start with 'SYS1.

CAT F=L *.fa *.L P=E& L=CAT.LIST

Lists all files (long format) which end with either'.S1 or '.L' and are at least erase protected.Listing goes to file CAT.LIST on the master device.

CAT F=L P=& DATE>=780301

Lists all files (long format) with at least nullproperties that have been last modified on orsince March 1, 1978.

- 43 -

5.5CLOSE CLOSE

(Internal Command)

SYNTAX

Close u/*

DESCRIPTION

Generates a Close (06) I/O request for (hexadecimal) logicalunit 'u1 or all logical units ('*')• Error returns are ignored.


As noted above

EXAMPLES

CLOSE 5

generates a Close I/O request for logical unit 5.

CLOSE *

generates a Close I/O request for all logical units.

- 44 -

5.6COMPARE COMPARE

SYNTAX

COMPARE file 1 file 2

DESCRIPTION

Performs a comparison of the contents of file_l andfile_2 (excluding the descriptor record). If the filecontents are identical, no message is given. For eachbyte comparison which fails, a message of the form

FILE1: BYTE 01FC RECORD 0003 = B6FILE2: BYTE 01FC RECORD 0003 = A6

is given.

Pressing the escape key will terminate command execution.File_l and file_2 may not be the same physical file, thoughthey can be the same named file on different drives if thenames are appropriately qualified.


Unit 2:Unit 6:Unit 7:

error messagesfile_l inputfile 2 input

EXAMPLES

COMPARE MYFILE YOURFILE

MYFILE and YOURFILE are read and compared,message implies the files are identical.

No

- 45 -

COMPARE COMPARE

COMPARE AFILE BFILEI/O ERROR C9 ON UNIT 7

an end of file was reached on BFILE before thecorresponding end of file on AFILE.

COMPARE 0/MYFILE 1/MYFILE

the two files have the same name, but they resideon different devices.

- 46 -

5.7COPY COPY

SYNTAX

COPY fileJL file_2 (A | U I 0 | PL=record lengthT=type)*

DESCRIPTION

Copies file_l (using a READ BINARY request) to file_2(using a WRITE BINARY request). Either file_l orfile_2 may be devices or fully qualified names. FILEattributes of file_l are transferred to file_2The options A (Append), U (Update), 0 (Output)are used to specify the type of open request performedon the destination file, file_2. See Chapter 6 fordetails. The default record length and type of file_2will be the same as file_l. These attributes can beoverridden by specifying one of 80, 100, 200, 400, 800or 1000 for record length, or one of D (directory),B (binary), A (ASCII) or P (procedure) for type.In the event that the destination file or device is unableto support the record length attribute of the sourcefile, the message

WARNING: RECORD LENGTH CHANGED

will be issued and the default attributes of the destinationdevice will be used.

*** WARNING ***

If the record length of the destination file is not thesame as the record length of the source file, eitherbecause the RL=record length option was specified ordue to automatic record length modification (see above),the BYTE_COUNT field in the source file's descriptorrecord is used to determine the number of bytes inthe last record. In the event this value is incorrect,file truncation may result.

COPY COPY


Unit 2: error messagesUnit 6: source fileUnit 7: destination file

EXAMPLES

COPY MYFILE 2/MYFILE.TOO

Copies MYFILE on the master device, default drivesearch, to MYFILE.TOO on the master device, drive 2.File attributes of MYFILE are transferred toMYFILE.TOO. Error occurs if MYFILE.TOO all readyexists.

COPY $ZDOS:2/THE.FILE $MYDOS/THE.FILE RL=400 0

Copies THE.FILE on drive 2 of ZDOS to THE.FILEon device $MYDOS, default drive search. Therecord length of the destination file is 400H andits previous contents (if any) will be erased.

COPY ANOTHER.FILE $CON

Copies ANOTHER.FILE from the master device,default drive search to the device CON, thedefault RIO console device driver (see section 3.4.3)

COPY $CON 7/TEXT 0

Copies from the device CON (see section 3.4.3) tothe file TEXT on the master device, drive 7. IfTEXT existed previously, its contents will beerased.

- 48 -

5.8COPY.DISK COPY.DISK

SYNTAX

COPY.DISK [s drive TO d drive] [V]

DESCRIPTION

3isk in drive s drive (defaul t = 0) to tic•ive 1

Copies the disk in drive s_drive (default = 0) to thedisk in drive d_drive (default = drive 2 (MCZ) or dr^(ZDS)). Before starting, the prompt message

DRIVES READY?

is given. Response other than 'Y1 will abort the command.The disks are read and written directly (through thedrive control ports) one track at a time; thus the previouscontents, if any, are overwritten. It is not necessarythat the destination disk be formatted. After the copyoperation, a verification pass is made during which a track-by-track comparison is made. At the completion of thispass, the message

VERFICATION COMPLETE

indicates a successful verify operation. The message

*** 0016 VERIFICATION ERROR(S) ***

indicates the number of compare errors found during theverification attempt.

If the verification pass only is required, the 'Voption in the command line causes the copy cycle to beskipped.

- 49 -

COPY.DISK COPY.DISK


Unit 0: FLOPPY or DPS interactionUnit 1: console interactionUnit 2: console interaction

EXAMPLES

COPY.DISKDRIVES READY7YVERIFICATION COMPLETE

copies disk in drive 0 onto disk(for MCZ) or 1 (for ZDS).

in drive 2

COPY.DISK 3 TO 7 VDRIVES READY7YVERIFICATION COMPLETE

verifies the disk in drive 3 is identicalto disk in drive 7.

- 50 -

5.9COPYSD COPYSD

SYNTAX

- COPYSD file name

DESCRIPTION

Copies a single ZDOS file from one diskette to anotherusing a single disk drive. The file_name may be fullyor partially qualified. The source and destination disketteare inserted as many times as necessary to copy the file.When either of the prompts:

INSERT SOURCE DISK. TYPE ANY KEY TO CONTINUE, ESCAPE TO ABORT:INSERT DESTINATION DISK. TYPE ANY KEY TO CONTINUE, ESCAPE TO ABORT;

is sent to the console device, the user must place the sourceor destination diskette, as specified in the prompt, into thedrive. If the user wishes to abort the command, the ESCapecharacter (ASCII 1BH) is entered from the console device atthis time; otherwise, any other character is entered. Thefile is created on the destination diskette with the same nameand attributes that it has on the source diskette.


Unit 1: console interactionUnit 2: console interactionUnit 6: ZDOS interaction

- 51 -

COPYSD COPYSD

EXAMPLE

%COPYSD DATA.FILEINSERT SOURCE DISK. TYPE ANY KEY TO CONTINUE, ESCAPE TO ABORT:GINSERT DESTINATION DISK. TYPE ANY KEY TO CONTINUE, ESCAPE TO ABORT:G%

copies the file DATA.FILE from the source diskette to thedestination diskette.

- 52 -

5.10DATE DATE

SYNTAX

DATE [yymmdd]

DESCRIPTION

Displays and optionally sets the date field which is usedas the date of creation or date of last modification byZDOS. Digits 'yy' specify the year, 'mm1 the month, and'dd' the day.

The Date command is part of the standard RIO externalinitialization command file OS.INIT. Editing the filemanually is required to change the date set at systeminitialization.

Users are encouraged to maintain the DATE consistent withthe actual date in order to maximize the utility of theinformation and capabilities provided by the file system(s)


Unit 2: output response

EXAMPLES

DATE 780801AUGUST 1, 1978

Sets and displays current system date.

DATEAUGUST 1, 1978

Displays current system date.

- 53 -

5.11DEACTIVATE DEACTIVATE

SYNTAX

DEACTIVATE device_name

DESCRIPTION

Deletes device_name from the Active Device Table (ADT) and thusmakes it unknown to RIO. A Close I/O request is generatedfor units linked to the deactivated device and a DeactivateI/O request is generated for the device itself. If the ADTsize entry is non-null (> 0), the space allocated to thedevice handler is deallocated.

Deactivation is inhibited for the last active device, sincethere would be no source for further external commands andtherefore no method to activate other device files.Likewise, the master device cannot be deactivated.


Unit 2: error messagesOthers: all units currently linked to device

EXAMPLE

DEACTIVATE $MYDOS

Removes MYDOS from Active Device Table and generatesClose request for all units linked to MYDOS. ADeactivate request is sent to MYDOS and the spaceallocated to it deallocated (if ADT size entry > 0).

- 54 -

5.12DEALLOCATE DEALLOCATE

(Internal Command)

SYNTAX

DEAllocate block_address block_size

DESCRIPTION

Marks the block_size segment starting at block_address asunallocated in the system memory map. If any affectedblocks were not previously allocated, the message

MEMORY PROTECTION

is given. Block_address will be rounded down andblock_size will be rounded up to a multiple of 80 bytes.


None

EXAMPLE

DEALLOCATE 5000 1400

deallocates the 1400 byte block starting at 5000(must have been previously allocated).

DEALLOCATE COOO 180MEMORY PROTECTION

the 180 byte block starting at COOO was not previouslyallocated.

- 55 -

5.13DEBUG DEBUG

(Internal Command)

SYNTAX

Debug

DESCRIPTION

Enters the RIO PROM debugger (RIO PROM User's Manual).A 'Q1 command in the debugger will return directly toOS while an 'OS1 command will first bootstrap (andreinitialize) the system.

The PROM contains a bootstrap loader which will bringin the diskette-resident Debug commands, as well as thefull operating system. The following commands usethe bootstrap loader, and, when used with the Zilogdiskette-based operating system, will execute as describedbelow. These commands require that the system diskette ondrive 0 is not write-protected.

GET filename

Loads a memory image into memory and stores itsstarting execution address in the user PC. A memoryimage file can be created by the SAVE command or bythe IMAGE or LINK commands. Such files contain in thedescriptor the starting address and length of one ormore segments of contiguous memory which is stored in thefile, as well as the starting address for execution ofthe file. The Get command can handle files of up to fivesegments of memory, but the segments may be of any size.If more than five segments are in the file, ONLY the FIRSTFIVE will be loaded.

If any segment contains information in the range 0-13FFH,the message 'MEMORY PROTECTION1 will be printed and theload will be aborted.

- 56 -

Page 57 is missing

DEBUG DEBUG

***WARNING***

SAVE uses diskette allocation information retrieved directlyfrom the diskette, whereas ZDOS uses a copy of the sameinformation stored in memory. If ZDOS activities havebeen going on immediately preceding the SAVE (e.g., ifthe Debug environment is entered via a Break from anoperating system program), or will be going on immediatelyfollowing the SAVE (e.g., by Quitting back to the operatingsystem without rebooting), steps must be taken to makesure that the diskette copy of the allocation information is inagreement with the memory copy both before and after theSAVE operation. The following procedures are recommended:

1) If Debug was entered via a breakpoint and ZDOS isbeing accessed by the program in question, do notissue a SAVE command unless it can be verified thatall ZDOS files are closed.

2) When returning to OS via a Quit command, after aSAVE has been done, immediately issue an Initializecommand to update the allocation maps.


None

EXAMPLES

%D>BREAK 5500 ;set a breakpoint>Q ;return to RIO

- 58 -

DEBUG DEBUG

ID>GET 0/OS ;get the RIO executive>D 140E ;display system flag140E 84 80 Q ;turn off external

Initialization flag>SAVE 0/OS 1400 2BFF E=17DE RL=400>OS ;Must rebootstrap after

;getting OS

- 59 -

5.14DEFINE DEFINE

SYNTAX

DEFINE (unit file_name I unit device_name I unit **)+ [A | 0 | U I I I NF | NO]

DESCRIPTION

Links a logical unit (referenced by an integer from 1 to20) to a currently active device or restores unit to thedefault established at system initialization (bootstrap).(Units 1,2,3 may be referenced by the mnemonics CONIN,CONOUT, and SYSLST, respectively.) If the unit waspreviously defined, a close request is generated. Afile name may optionally be associated with the unit.Assign and Open requests may be generated for the unit.

Unit file_name

The unit is linked to the specified device if name isqualified, or to the master device if unqualified. AnAssign request is sent to the device with file_name as aparameter, followed by an Open request (default open typeis 'open for update1).

Unit device_name

The unit is linked to device_name (must be active). Noother I/O requests are generated.

Unit *

Links unit to the default established at systeminitialization.

- 60 -

DEFINE DEFINE

Links all units to their defaults established at systeminitialization. The standard RIO system defaults to units1, 2 and 3 defined as the console device; the remainingunits are linked to the master device.

Options

A open type = Append (See Chapter 6 for0 open type = Output open types)U open type = Update1 open type = InputNF open type = NewfileNO Generate No Open request


Unit 2: error messagesOthers: parameter dependent

EXAMPLES

DEFINE SYSLST $LPR

Defines the system volume output unit SYSLST (3) to bedevice driver LPR, which must be an active device.Subsequent I/O requests for unit 3 will be directedto this device.

DEFINE 6 MYFILE

Links unit 6 to the master device. Assign and Open(for update) I/O requests are then sent to unit 6with MYFILE as parameter.

- 61 -

DEFINE DEFINE

DEFINE *

Restores all units to the defaults established atsystem initialization (after bootstrap). Alldefined units are closed prior to being redefinedas their defaults.

DEFINE 12 $YOUR.DOS/YOURFILE NO

Links unit 12 to the device YOUR.DOS (which mustbe active). An Assign I/O request is then generatedwith YOURFILE as the filename, but no Open request.

- 62 -

5.15DELETE DELETE

SYNTAX

DELETE (match_string I T=type | P=props | D=driveQ=query I DATE rel date I CDATE rel date)*

DESCRIPTION

Deallocates all records and deletes name from filedirectory of files which match the specified options.Given without option, all (non-secret) files in each activeunit are deleted. Options may be given in any order, andmay appear more than once. Where options other thanmatch_strings are specified more than once, the lastentered is used. As matches are made, if in query mode, aprompt is made to the console of the form:

DELETE drive/filename (Y/N/A/Q)?

One character is accepted as input and must be one of thefollowing:

'Y1 Yes, delete the named file'N1 No, do not delete the named file'A' Yes, delete the named file and all other

files without further query.'Q1 No, do not delete the named file and discontinue

searching for file matches.

In general, if a file is listed with a given parameter listusing CAT, it will be deleted using the same parameter listusing DELETE.

DELETE DELETE

match_string

Fully- or partially-specified file names may be given, inwhich case only those directory entries are deleted whichare identical to one of the fully-specified file names ormatch one of the partially-specified file names. Partially-specified refers to the use of the symbol '*' which denotesan arbitrary character string. For example '*XYZ' matchesany file which ends in 'XYZ'. 'ABC*XYZ' matches any namewhich starts with 'ABC1 and ends with 'XYZ' but has any (orno) characters in the middle. The string '*' (which isequivalent to '**') matches any name. Match strings cannotbe qualified file names, i.e., no device or drive name maybe given (see the 'D=' option below).

T=type

Only files of the given type will be deleted. Type must beone of 'D1 (directory), 'A1 (ASCII), 'B' (binary) or 'P1

(procedure). Subtype may also be specified immediately follow-ing the type (e.g. 'AO' refers to files of ASCII type, subtype0). If no subtype is given, all subtypes of the specified typeare deleted.

P=props

Only files with exactly the specified properties will bedeleted. Props may include any of the following:

W write protectedE erase protectedL properties lockedP randomF force memory allocation& files with at least the specified

properties

One or more properties may be concatenated in which caseonly files with exactly (or at least, if '&' is included)the specified properties, will be deleted.

- 64 -

DELETE DELETE

D=dr ive

Only files from the specified drive will be deleted. Drivemust be from 'O'...1?'. Default is to list all readydrives.

Q=query

Sets Query mode for delete operations. 'Q=Y' (default)causes a query before a delete; 'Q=N' suppresses queries.Note that the 'Q=Y' mode can be overridden by the queryresponse 'A'.

CDATE | DATE rel date

where rel is one of the relational operators '=','>', '<', '>=', '<=', or '<>', and date is up to 6digits or '*' representing a date to be compared againstin 'yymmdd' form. '*' in a digit position specifies thatthat digit will be considered equal to anything. A dateexpressed with less than 6 digits is treated as beingfilled on the right with '*'s.DATE refers to the date of last modification. CDATE refersto the date of creation. The entire option should bespecified with no intervening blanks. For example:

CDATE>=7805


CDATE>=7805**



Unit 2: error messagesUnit 4: directoriesUnit 5: files listed in directories

- 65 -

DELETE DELETE

EXAMPLES

DELETE *.OLD Q=N

Deletes without query all files on all ready driveswhich end in '.OLD' (backup files are normallyproduced by the text editor).

DELETE T=A CDATE<773112

Deletes (after prompting) all ASCII typefiles created before December 31, 1977.

DELETE D=2 P=R *.BASIC Q=N

Deletes without query all random files on drive 2whose name ends in '.BASIC'.

- 66 -

5.16DISK.FORMAT DISK.FORMAT

SYNTAX

DISK.FORMAT (S | D=drive | ID='disk_name' I Q=query)*

i

DESCRIPTION

Formats a hard disk cartridge or hard disk fixed platter,initializes the disk allocation map and utilization statistics,A directory file is established. When a system disk isformatted, the file 'BOOTSTRAP1 is copied from the masterdevice. This file allows file system bootstrap in the diskcontroller.

A known pattern is written on each sector; then, eachsector is read back and the initial allocation free chainis constructed. Any sectors that read back with errors areassumed to be bad sectors and are counted in a separatevariable and not put in the free chain. The total operationtakes approximately 9 minutes with a 5 megabyte platter.After the first pass, the message:

WRITE PASS DONE

is sent to the console device. - -

The parameter list specifies the following options:

Determines whether or not the disk is to beformatted as a system disk. System disks containthe 'BOOTSTRAP' file.

- 67 -

5.17DISK.REPAIR DISK.REPAIR

SYNTAX

DISK.REPAIR DFS_drive_number level_number

DESCRIPTION

Attempts to recover lost file data due to software failureor abnormal program interruption. There are four in-creasingly drastic levels of repair; level_number is aninteger from 1 to 4 specifying the level of repair to beused (at present, only level 1 has been implemented). Therepair is attempted on the disk in DPS drive DFS_drive_number.

Level 1 Repair:

When software failure or external interruption prevents thethe free chain of unallocated sectors from being updated,using the first level of repair will remove any allocatedsectors that may be at the beginning of the free chain.

If the command is effective in retrieving data, the message:

n SECTORS REMOVED FROM FREE CHAIN

is sent to the console device, where n is the decimal numberof sectors the command retrieved from the free chain, restoredto a file, and marked as allocated. If the disk appears to beundamaged, the message:

FREE CHAIN UNMODIFIED

is sent to the console device. If the disk damage is beyondthe repair capability of level 1, the message:

LEVEL 1 REPAIR NOT SUFFICIENT FOR THIS DRIVE

is displayed at the console.

- 70 -

DISK.REPAIR DISK.REPAIR


Unit 0: disk sector accessUnit 2: execution messages

EXAMPLES

%DISK.REPAIR 3 16 SECTORS REMOVED FROM FREE CHAIN

level 1 repair is administered to the disk in drive 3;6 allocated sectors are removed from the unallocatedsector list.

%DISK.REPAIR 0 1FREE CHAIN UNMODIFIED

level 1 repair detects no problem with the diskdrive 0.

in

- 71 -

5.19DISPLAY DISPLAY

SYNTAX

DISPLAY

DESCRIPTION

Displays the current state of the memory allocation map onthe system console.

The memory allocation display is a matrix with one horizontalrow for each 1000H bytes of memory. The point correspondingto each 80H byte segment of memory is either marked with 'A'if the segment is allocated, or '.' if it is free.


Unit 2: memory display

- 74 -

5.20DO DO

SYNTAX

DO command_file [parameter list]

DESCRIPTION

Executes commands from file command_file. The file is readinto a dynamically allocated buffer. Each command line (asterminated by a carriage return) is then expanded accordingto the presence of certain expansion control symbols.

A 'parameter string1 is a group of symbols delimited byeither a blank (20H), comma (2CH), horizontal tab (09H),left parenthesis (28H), right parenthesis (29H), semicolon(3BH), or carriage return (ODH).

Simple parameter substitution is made for each occurrenceof the string '#n', where n is an integer less than orequal to the number of parameters given. If n is greaterthan the number of parameters given, a Command ExpansionError is generated and processing is terminated. For each'#n', the nth parameter string from the parameter list issubstituted. A maximum of 64 parameter strings may bepassed in this manner. Parameters which are present butnot referenced are ignored.

Conditional expansion of the command line can be controlledby the symbol pair '[' and ']'. At each occurrence of '[',the depth of conditional expansion increases by one. Ifthe resultant depth is greater than the number ofparameters given, the command line is scanned over untilthe matching ']' is located. If the resultant depth is notgreater than the number of parameters given, the '[' isdeleted from the command string and expansion continued.At each occurrence of ']'/ the depth of conditionalexpansion decreases by one. Thus, the command string'AB[C]DE' would expand into 'ABCDE1 only if at least oneparameter were given. Otherwise, the resultant commandstring (after expansion) would be "ABDE1. Note thatparameters may control command string expansion regardless

- 75 -

DO DO

of whether or not they are used in that expansion.

After command string editing according to the above rules,a system call is generated to execute the resultant commandstring.

This command is reentrant (and has the 'force allocation"property) and may call itself up to a depth limited only bythe amount of memory available. That is to say, FILE.X maycontain the command 'DO FILE.Y', which may contain thecommand 'DO FILE.Z1, etc., down to a level where insufficientmemory exists to allocate buffer space. For short commandfiles (a few records) in a 32K system, this depth isapproximately 15, depending on memory requirements forother command executions.

*** WARNING ***

Due to the force allocation property of this command, itwill over-write the memory where it is loaded, whether ornot the memory is all ready allocated. This command shouldbe linked to load at an address that will not affect memorythat is preallocated for system use.

I/O UNJT UTILIZATION

Unit 0:Unit 2:

command fileerror messages

EXAMPLES

The examples have the following format:

FILENAME:Command:Result:

DO file contentsCommand line enteredThe expanded file contents whichare to be executed.

- 76 -

DO DO

1) PRINT:

Command;

Result:

ACTIVATE $LPTR;COPY #1 $LPTR;DEACTIVATE $LPTR

DO PRINT MYFILE

ACTIVATE $LPTRCOPY MYFILE $LPTRDEACTIVATE $LPTR

Failing to give a parameter would resultin a Parameter Expansion Error.

2) PRINT:

Command:

ACTIVATE $LPTR[COPY #1 $LPTR[;COPY #2 $LPTR[;COPY #3 $LPTR]]]DEACTIVATE $LPTR

DO PRINT MYFILE

Result: ACTIVATE $LPTRCOPY MYFILE $LPTRDEACTIVATE $LPTR

Simple parameter substitution is performed for asmany strings enclosed within brackets as there areparameters given. Only the parameter 'MYFILE1 waspresent, therefore the command after (andincluding) the second '[' was ignored.

Command: DO PRINT FILEl FILE2

Result: ACTIVATE $LPTRCOPY FILEl $LPTR;COPY FILE2 $LPTRDEACTIVATE $LPTR

Two parameters were given so that two levels ofconditional expansion were valid.

- 77 -

DO DO

3) BATCH: EDIT fl[;ASM #1[;LINK $=4400 #![;#!]]]

Command: DO BATCH MYFILE A L X

Result: EDIT MYFILE;ASM MYFILE;LINK $=4400 MYFILE;MYFILE

Command: DO BATCH MYFILE A

Result: EDIT MYFILE;ASM MYFILE

In the first command, four parameters were givenindicating conditional expansion of four levels.In the second command, only two were given, limitingexpansion to two levels. The characters "A 1, 'L1, and'X1 could have been any character string althoughthey serve as symbolic notations for assemble, link,and execute. This is an example where the numberof parameters controls expansion but the parametersthemselves do not take part in the expansion.

- 78 -

5.21DUMP DUMP

SYNTAX

DUMP file_name [m[ n]]

s

DESCRIPTION

Converts the referenced file into a hexadecimal/ASCII dumpon unit SYSLST. Each byte of the file is displayed inhexadecimal. In addition, printable characters aredisplayed as ASCII symbols, while unprintable charactersare displayed as '.'.

If m and n are specified, the dump starts with record m andcontinues through record n. If m and/or n are unspecified,the dump starts with the first and continues through thelast, respectively.

While output is active at the console, entering a '?' willcause output to stop until another '?' is entered. If theESCape character (1BH) is entered, output will beterminated.


Unit 3: output listingUnit 4: file to be dumped

EXAMPLES*« , ~J

DUMP $MICR0.80:2/DATA

Dumps the file 'DATA' from device MICRO.80,drive 2 on the system volume output unit.

- 79 -

5.22ECHO ECHO

SYNTAX

ECHO string

DESCRIPTION

Copies the string following the command name up to, but notincluding, the command terminator, to the console outputdevice. This provides a method to send messages to theconsole from the command line.


unit 2: string output

EXAMPLES

ASM MYFILE;LINK $=4400 MYFILE;ECHO <control-G>

This would send a control-G (bell) to the console outputdevice after completion of the assembly and link.

ECHO is also useful to provide instructions to the user ofthe console command file. For example,

COPY,;ECHO INSERT DISKETTES;PAUSE;I;X 4400 #1 #2

can be used to copy files from one diskette to another,neither of which have the command file COPY on them.

- 80 -

5.23ERROR ERROR

SYNTAX

ERROR [error_code|*]

DESCRIPTION

Prints the meaning of error_code when returned by RIO or adevice as a completion code. If the optional error_code is'*', all error_code meanings are displayed. If error_code isomitted, this description of the ERROR command is printed.

*


Unit 2: output

EXAMPLE

%ERROR 4343: MEMORY PROTECT VIOLATION

- 81 -

5.24ERRORS ERRORS

SYNTAX

ERRORS

DESCRIPTION

Prints a summary of the recoverable disk errors which haveoccured since system bootstrap. Output is of the form:

THE FOLLOWING RECOVERABLE ERRORS HAVE OCCURRED SINCE SYSTEM RESTART0000 SEEK ERRORS0000 SECTOR ADDRESS ERRORS0000 DATA TRANSFER ERRORS

Reference the Z80-MCZ PROM User's Manual for a detailedexplanation of these errors.


Unit 2: output listing

*** NOTE ***

This command is implemented only with the MCZ 1/20 PROMdate coded 78089 or later, or with the MCZ 1/35 PROM datecoded 780529 or later when ZDOS is used as a secondaryfile system.

- 82 -

5.25EXTRACT . EXTRACT

SYNTAX

EXTRACT file_name

DESCRIPTION

Lists record count, record length, and the number of bytesin the last record of file_name. If the file is of typeprocedure, the file entry point, the lowest and highestmemory addresses affected by the file, and the addressesof the memory segments which make up the file are alsodisplayed. For files created by IMAGE, the segment addressesare those given in the parameter list. However, LINK providesan optimizing algorithm for segment allocation dependent onprogram memory utilization and file record length. Thus,EXTRACT can be used to determine the best record length fora procedure file.


Unit 0: file inputUnit 2: output listing, error messages

EXAMPLE

%EXTRACT EXTRACTRECORD COUNT = 0001 RECORD LENGTH = 0400

NO. OF BYTES IN LAST RECORD = 0400ENTRY POINT = 4400 LOW ADDRESS = 4400 HIGH ADDRESS = 47FF

STACK SIZE = 0080SEGMENTS:4400 45F2

- 83 -

5.26FORCE FORCE

(Internal Command)

SYNTAX

Force command parameter_l1st

DESCRIPTION

Causes all command files in the current command string tobe loaded regardless of previous memory allocation.Normally, a procedure file will be loaded only if thememory space it requires is unallocated. Sometimes it isconvenient to load a file into previously allocatedmemory space. Command overlays or recursive program callsare two examples. As an alternative to using the Forcecommand, the properties of a file can include F (forcememory allocation), which has the same effect as theForce command, but only for that file.


None

EXAMPLES

FORCE DISPLAY

loads and executes the procedure file DISPLAY evenif the memory space it requires is preallocated.

F FILEA,FILEB,;FILEC

loads the procedure files FILEA and FILEB, but doesnot execute either. FILEC will be loaded (andexecuted) only if the memory it requires isavailable; i.e., the context of the FORCE does notextend into subsequent commands.

- 84 -

5.27FORMAT FORMAT

SYNTAX

FORMAT (S I D=drive I ID='disk_name' I Q=query)*

DESCRIPTION;

Formats a diskette into 77 tracks of 32 sectors,initializes the disk allocation map and disk utilizationstatistics. An empty (except for one entry for itself)directory file is established.

Thirteen sectors are allocated for the disk allocationmap (3 sectors) and directory (10 sectors). When asystem disk is formatted, an additional 64 sectors(2 tracks) are preallocated for the RIO bootstrap

and RIO Debug Get/Save package.

The parameter list specifies the following options:

S

Determines whether or not the disk is to beformatted as a system disk. Systems disks havededicated areas for the bootstrap and GET/SAVEoverlays.

When the 'S1 option is given and the disk isbeing formatted on any drive except 0, thebootstrap and GET/SAVE overlays are read fromthe disk in drive 0. If the 'S1 option isgiven and the disk is being formatted ondrive 0, a prompt is made for the user to inserta formatted system disk in drive 0 replacingthe disk being formatted. After this is done,entering any key will cause the system bootstrapand the GET/SAVE overlays to be read intomemory and another prompt to be issued. Againentering any key will result in the bootstrapand the GET/SAVE overlays being written ontothe disk, thereby making it a 'system1 disk.

- 85 -

FORMAT FORMAT

D=drive

The drive containing the disk to be formatted isgiven as 'drive1. If the option is not present,the query

DRIVE:

will be given, the correct response to which mustbe an integer 0...7.

ID='diskname1

Up to 24 characters not including a carriage returnare used to identify the disk. These are writtenon the disk and used by ZDOS to determine diskallocation map validity. If this option is notgiven, the query

DISK ID:

will be given.

Q=Query

Normally, before formatting commences, the query

READY?

is given. Any response other than 'Y1 will resultin aborting the format. The generation of this querymay be inhibited by giving the 'Q=N' option. The 'Q=Y'option is the default and has no effect.

- 86 -

FORMAT FORMAT

NOTE: Diskettes formatted on OS 2.1 software are NOTcompatible with RIO. Refer to Appendix D forconversion details.

Format interacts with FLOPPY through the system. Thedriver $FLOPPY must appear in the Active Device Table.On floppy disk-based systems, this occurs automatically.On hard disk-based systems, FLOPPY is part of ZDOS,and has an entry point two greater than the entryaddress for ZDOS. It must be activated separately.For example, if the ZDOS.60 is being used on a 64Ksystem, has been renamed to ZDOS, and has anentry point of EOOOH, than a sequence of commandssuch as:

ACTIVATE $ZDOS; X* $FLOPPY E002would have to have been executed at some time prior toissuing a FORMAT command.


Unit 0: FLOPPY interactionUnit 1: console interactionUnit 2: console interactionUnit 4: ZDOS interaction

- 87 -

5.28HELP HELP

SYNTAX

HELP (key_word|'*')*

DESCRIPTION

Prints a description of key_word(s). If the final argumentis *, a list of valid key_words that can be used as furthermodifiers of the preceding key_words is displayed. If thefinal argument is omitted, a general description of the useof the preceding modifying key_words is printed.


Unit 2: Help messageUnit 4: File I/O

EXAMPLES

%HELP *

prints a list of all initial key_words for whichthere is HELP.

%HELP DELETE

prints a description of the RIO "DELETE1 command.

- 88 -

5 29IMAGE IMAGE

SYNTAX

IMAGE file_name (first_location last_location)+[E=entry point] [RL=record length][ST=stack size]

DESCRIPTION

Copies memory images to a specified file. The resultantfile will be procedure type/ subtype 0. The first and lastlocations of each memory segment, optional entry pointaddress (default=0), record length (80H, 100H, 200H,400H, 800H, or 1000H; default=80H bytes) and stacksize (default=80H bytes) are given in hexadecimal. At leastone but no more than 16 segments may be specified. Whenwriting the file, the exact memory locations, includingfirst_location and last_location, are copied for eachsegment. The lowest and highest memory addressesreferenced by the file are saved in the descriptor record(refer to Appendix J) and are used by the RIO Executivewhen requesting memory allocation prior to loading.


Unit 0: file I/OUnit 2: error messages

EXAMPLE

IMAGE TWO.BLOCKS 4400 4425 7000 7FFO E=7000

Copies contents of memory locations 4400 to 4425and 7000 to 7FFO to file TWO.BLOCKS. The filewill contain 33 records of 80H bytes each, withan entry point = 7000 and stack size = 80H.

- 89 -

5.30INITIALIZE INITIALIZE

(Internal Command)

SYNTAX

Initialize [device_name [parameter list]]

DESCRIPTION

Sends an Initialize request to the master device or to theoptionally specified device (which must be active). Resultis device dependent. The supplemental parameter addressof the vector points to the delimiter after the commandor device_name, if given.


Unit 0: I/O request

EXAMPLES

INIT $MY.VIDEO.DRIVER BUFFER = COOO

Sends Initialize request to MY.VIDEO.DRIVER,with a pointer to the space preceding 'BUFFER1.

I

Sends Initialize request to master device.

- 90 -

5.31LADT LADT

SYNTAX

LADT

DESCRIPTION

Lists the currently active devices, their entry points,size, and which logical units are linked to each.

A size of zero implies that the device is in PROM or wasactivated with a preloaded entry point given. In eithercase, no memory is deallocated upon deactivation.


Unit 2yi listing output

EXAMPLE

LADT

DEVICE

ZDOS

CONNULLPCONFLOPPY

ADDRESS

2AOO

252B214DOBE8OBFD

SIZE

1AOO

0500000000000000

UNITS

0 412 131 2

20

5 6 7 8 9 10 1114 15 16 17 18 19

V 91 -

5.32MASTER MASTER

SYNTAX

MASTER [device_name]

DESCRIPTION

Displays the current master device or, optionally, makesanother currently active device the default source forunqualified files. This provides the user with thepotential to easily utilize multiple file systemsconcurrently without the burden of always fully specifyingfile names.


Unit 2: error messages

EXAMPLES

MASTER $NEW.DOS

Makes NEW.DOS the default device for unqualifiedfile names.

MASTERNEW.DOS IS THE MASTER DEVICE

- 92 -

r

5.33MOVE MOVE

SYNTAX

MOVE (match_string I T=typeD=destination_device IL=listing_dispositionCDATE rel date)*

I P=props | F=format |S=source_device IQ=query | DATE rel date

DESCRIPTION

The directory on the source device is searched and fileswhich match the specified option are copied from the sourcedevice to the destination device. Default destination andsource devices for MCZ are master device, drive 2, andmaster device, drive 0, respectively. For the DevelopmentSystem, the defaults are drive 1 and drive 0, respectively.

match_string

Fully or partially specified file names may be given, inwhich case only those directory entries which are identicalto one of the fully-specified file names or match one ofthe partially-specified file names are moved. Partially-specified refers to the use of the symbol '*' which denotesan-arbitrary character string. For example, '*XYZ' matchesany file which ends in 'XYZ1. 'ABC*XYZ' matches any namewhich starts with 'ABC1 and ends with 'XYZ1 but has any (orno) characters in the middle. The string '*' (which isequivalent to '**') matches any name. Match strings cannotbe qualified file names, i.e., no device or drive name maybe given.

- 93 -

MOVE MOVE

T=type

Only files of the given type will be moved. Type must beone of 'D1 (directory), 'A1 (ASCII), 'B1 (binary) or 'P1

(procedure). Subtype may also be specified immediately follow-ing the type (e.g. 'PO1 refers to files of prodecure type,subtype 0). If no subtype is given, all subtypes of thespecified type are moved.

P=props

Only files with exactly the specified properties will bemoved. Props must be from "W (write protected), "E 1

(erase protected), 'L1 (properties protected), 'S1

(secret), 'R' (random), 'F1 (force memory allocation), or'&'. Use of the '&' will allow any file with at least thespecified properties to be moved. One or more propertiesmay be concatenated, in which case only files with exactly(or at least, if '&' is included) the specified propertieswill be moved.

D=destination_device

Defines device to which files are copied. Any activedevice name or drive designation may be given. Only devicename and drive name are relevant. File names are ignored.Default is drive 2, master device (MCZ), or drive 1, masterdevice (ZDS).

S=source_device

Defines device from which files are copied. Any activedevice name or drive designation may be given. Only devicename and drive name are relevant. File names are ignored.Default is drive 0, master device.

- 94 -

MOVE MOVE

F=format

Specifies long (F=L) or short (F=S) listing format. Theshort form (default) consists of name and drive while thelong form gives name, drive, file type, record count,record length, file properties, starting address, date ofcreation, and date of last modification. Additionally, thenumber of files examined, the number of files moved, andthe number of sectors used by moved files is also given.

L=listing_disposition ' •

The listing is normally routed to SYSLST but can be routedto any device or file. For example, L=$CON would routeoutput to the console (SYSLST may also be asigned to thisdevice) or L=2/FILELISTING would route the output to file'FILELISTING1 on unit 2 of the master device. All outputgenerated to the specified device or file will be buffered,i.e., several lines will be transferred at one time. Whileoutput is active at the console, entering a '?' characterwill cause output to stop until another '?' character isentered. If the ESCape character (ASCII 1BH) is typed,output will be terminated and control will return to theExecutive.

• • • , " • - r / , -

Q=query r • •- ,-

Permits selective copying of files that match the otheroptions. Default is Q=N, which moves all fileswhich match the given criteria. If Q=Y is specified, amessage of the form:

MOVE source_device : source_drive / source_file name TOdestination_device : destination_drive / destination_filename(Y/N/A/Q)?

response of 'Y(es)' will move the file, 'N(o)' will not move itand go on to the next file, 'A(ll)' will move the file andsuppress the query for all subsequent files, and 'Q(uit) ' willnot move the file and will terminate the program. Any otherresponse will cause the query to be repeated.

- 95 -

MOVE MOVE

CDATE I DATE rel date

where rel is one of the relational operators '=','>', '<', '>=', '<=', or '<>', and date is up to 6digits or '*' representing a date to be compared againstin 'yymmdd1 form. '*' in a digit position specifies thatthat digit will be considered equal to anything. A dateexpressed with less than 6 digits is treated as beingfilled on the right with '*'s.DATE refers to the date of last modification.

the date of creation. The entire option should beCDATE refers

tospecified with no intervening blanks. For example:

CDATE>=7805


CDATE>=7805**



Unit 0: directoryUnit 3: default listing destinationUnit 4: source fileUnit 5: destination fileUnit 6: non-default listing destination

EXAMPLES

MOVE D=$NULL F=L P=&

Will copy all files from (default) drive 0 tothe Null device and print a long format listincluding the number of files moved and thenumber of sectors they occupy. This is aconvenient way to check the integrity ofeach file on a disk.

- 96 -

MOVE MOVE

MOVE T=P SYS* L=$LPRINTER S=2 D=0 CDATE<780915

Will copy all procedure files whose names startwith 'SYS' that were created before September 15,1978, from the master device, drive 2, to themaster device, drive 0. The listing willbe sent to the device LPRINTER.

- 97 -

5.34PAUSE PAUSE

SYNTAX

PAUSE

DESCRIPTION

Issues successive Read Status requests to unit 1 (CONIN)until either the ESCape Pending flag or the TIB Full flag isactive (see section 3.4.3). If a character is ready to be input,it is absorbed and the program executes a normal return. If anESCape is pending, subsequent commands in the commandstring are ignored.


Unit 1: read request

EXAMPLE

The content of the command file MOVE.IT is:

MOVE,;ECHO INSERT DISKETTES;PAUSE;I;X 4400

This command file will result in the following interactionwhen executed (Brief mode):

DO MOVE.ITINSERT DISKETTES

MOVE is loadedECHO is loaded and executedPAUSE waits for one character(not ESC) to be entered andthen MOVE is executed (MCZaddress). Entering ESC wouldhave resulted in directreturn to RIO without executingMOVE

- 98 -

5.35RELEASE RELEASE

(Internal Command)

SYNTAX* i

Release

- S*i ~ ', T r , **̂

DESCRIPTION( • i r *

As mentioned in Section 4.1, memory required for procedurefile loading is allocated immediately preceding execution,and deallocated after program completion. In the casewhere a file is loaded but no external file is executed(for example, after examination with the Debugger), itmay be necessary to deallocate the space it occupies.This command deallocates any memory allocated as a resultof procedure file loading since the last execution of anexternal command.

I / O UNIT UTILIZATION • . / « ' ,I - 7 i- '' >

None .- * * '/• .--

EXAMPLE

%MOVE,%STATUSMEMORY PROTECT VIOLATION%R%STATUS

DRIVE 0 RIO.MCZ.SYSTEM.DISK659 SECTORS USED1805 SECTORS AVAILABLE

- 99 -

5.36RENAME RENAME

SYNTAX

RENAME (oldfile newfile I deviceidrive ID='new_disk_name')*

DESCRIPTION

For each sequence, "oldfile newfile", changes the name of"oldfile" to "newfile" on the disk drive specified byoldfile. If in Verbose mode, the following message will beprinted for each name change.

oldfile >newfile

For each sequence, "device:drive ID=lnew_disk_name1",the name of the disk in the specified drive is changed to"new_disk_name". The device must be either $FLOPPY fordiskettes or $DISK for hard disks; no psuedonyms for thesedevices may be used. The "new_disk_name" may be up to 24characters for $FLOPPY or 100 characters for $DISK, andmay include any character except carriage return orsemicolon. If a single quote is to be part of the newname, it must be immediately followed by a second singlequote. The disk is renamed by first initializing theallocation maps, reading directly from the disk (via the floppyor hard disk driver) the map sector on which the disk ID issaved, altering it, and rewriting the sector. A secondinitialization is then made to update the disk name inmemory.


Unit 0: file I/O

- 100 -

RENAME RENAME

EXAMPLES

RENAME SMYDOS/FILE.X FILE.Y

generates Assign and Rename requests for deviceMYDOS changing name of FILE.X to FILE.Y.

RENAME $FLOPPY:2 ID='MY NEWEST RIO DISK1

renames the diskette in drive 2.

- 101 -

5.37RESTORE TABS RESTORE TABS

SYNTAX

RESTORE TABS file name

DESCRIPTION

Replaces the current 134-character console tabbing environmentwith the tabs in the specified file. The file_name may befully or partially qualified. The referenced file must havebeen previously created by the SAVEJTABS command.


Unit 2:Unit 4:

error messagesfile I/O

EXAMPLES

RESTORE_TABS $MYDOS:TAB.ASM

replaces the current console tabbing environment withthe tabs in the file TAB.ASM on device MYDOS.

- 102 -

5.38SAVE TABS SAVE TABS

SYNTAX -;;<

SAVEJTABS file_name / ' " 1 . . "• "';•'...-"' ' ' ;' - ' ' ' • • ';,''-' ~t

'• . ' " ••!••.•• '.:.- : •- . - : •-• '~. •'

• ' ^ '- - - . , " . » '

DESCRIPTION : . — '- "-' -'; : * '-" ""'

Stores the current 134-character console tabbing environmentinto the specified file for possible later retrieval by theRESTOREJTABS command. The file_name may be fully or partiallyqualified. If the file all ready exists, it is deleted andrecreated.


Unit 2: error messageUnit 4: file I/O

EXAMPLE

:• SAVEJTABS LETTER. TABS •' <'/ • "-'

stores the current console tabbing environment into' the file LETTER.TABS on the master device.

^:••:••• -• .?<,:, . . . . . . ' --•• : :.,-.. ' • :- ..- i ;«.

- 103 -

5.39SET SET

SYNTAX

SET (CHRDEL=C I LINDEL=C I NULLCT=n I SPEED=NN | LFCNT = nECHO ON | ECHO OFF | AUTOLF ON I AUTOLF OFF |PROPERTIES OF file_name TO plist ITYPE OF file_name TO type ISUBTYPE OF file_name TO subtype IENTRY_POINT OF file_name TO nn ILOW_ADDRESS OF file_name TO |HIGH_ADDRESS OF file_name TO ISTACK_SIZE OF file_name TO nn IBYTE_COUNT OF file_name TO nn ITABSIZE = n)*

DESCRIPTION

Sets a variety of system parameters. Any combination ofthe option list can be given in any order with each commandentry.

CHRDEL=c

Sets the console driver single character delete symbol to char-acter c. For example, typing 'SET CHRDEL=<control-H>' will causeall control-H's to be interpreted by the console input driveras a 'delete last character1 command. (The characters '<'and ">' are not typed, but serve to illustrate that'control-H1 is a non-printing character.)

LINDEL=c

Sets the console driver line delete symbol to character c.For example, typing 'SET LINDEL=<rubout>' will cause the consoledriver to interpret <rubout> as a 'delete current line1 command.(The characters '<' and '>' are not typed, but serve toillustrate that 'rubout1 is a non-printing character.)

- 104 -

SET SET

LFCNT = n

Sets to n the number of linefeed characters (OAH) the consoledriver automatically output after each carriage return if inAUTOLF=ON mode. Note that LFCNT=0 is equivalent to AUTOLF=OFF

NULLCT=n

Sets the number of null characters (ASCII 0) to output bythe system console driver after every carriage return todecimal value n. One null character is sufficient for CRToperation up to 19.2 Kbaud. Mechanical devices requirelonger head repositioning periods and thus a larger nullcount.

SPEED=nn\

(MCZ only) Changes the serial communication port baud rateto the value given as nn. This port typically is used forterminal I/O. Any value from 20 baud to 4800 baud which isan even divisor of 4800, or 110, 9600, 19200, or 38400, canbe selected.

TABSIZE=n

Redefines all tab settings to be every n columns,starting with the leftmost column as column 0. Thedefault is every 8 columns.

PROPERTIES OF file_name TO plist

Sets the properties of 'file_name' to those given in theproperties list plist. This list must be from W (writeprotect), E (erase protect), S (secret), L (locked), R(random), F (force memory allocation), or * (null, i.e.,no properties). Locked files cannot have their propertiesaltered.

- 105 -

SET SET

SUBTYPE OF file_name TO subtype

Sets the file subtype of file 'filename1 to value'subtype1. Only the least significant four bits of thevalue entered are used.

TYPE OF file_name TO type

Sets the file type of file 'file_name' to the type given -must be one of 'D1 (directory), 'A1 (ASCII), 'B' (binary)or 'P' (procedure).

ENTRY_POINT OF file_name TO nn

Sets the entry point field in the descriptor record offile_name to nn. This is the address to which control passes whenthe RIO Executive loads a procedure type file.

LOW_ADDRESS OF file_name TO nn

Sets to nn the lower boundary of the memory space whichmust be allocatable before a file name can be loaded.

HIGH_ADDRESS OF file_name TO nn

Sets to nn the high boundary of the memory space whichmust be allocatable before file name can be loaded.

STACK_SIZE OF file_name TO nn

Sets the size of the user stack which will be allocatedbefore execution of file_name begins. Setting thestack size to zero will result in no stack allocation;the system stack will be used instead.

BYTE_COUNT OF file_name TO nn

Sets the 'bytes in last record1 count for file_name to nn.This field is used by PLZ and BASIC to determine the numberof valid data bytes in the last record of a file.

- 106 -

SET SET

ECHO ON|OFF

Sets or resets the input character echo mode in CON (seesection 3.4.3).

AUTOLF ON|OFF

Sets or resets the automatic line feed insertion mode flagin CON (see section 3.4.3).


Unit 2: error messagesUnit 4: file I/O

EXAMPLES

SET LINDEL^! CHRDEL=@ NULLCT=2

Sets the line delete symbol to '!', thecharacter delete symbol to '@', and thenull count to 2.

SET PROPERTIES OF OS TO SWEL

Would give file 'OS1 the properties secret,write protect, erase protect, and locked.Therefore it could never be altered ordeleted without reformatting the disk.

SET SUBTYPE OF $DFS/TEXT TO 8

Sets subtype of file TEXT on device MICRO.80to 8H.

SET ECHO ON AUTOLF OFF

Sets the terminal mode to ECHO ON and AUTOLF OFF.

- 107 -

SET SET

SET SPEED=9600

Sets the serial communication port baud rate to 9600.

SET ENTRY_POINT OF STAR_TREK TO 4419 BYTE_COUNT OFSTARJTREK.S TO 38

Sets the entry point of STARJTREK to 4419H, and thenumber of bytes in the last record of STAR_TREK.Sto 38H.

- 108 -

5.40STATUS STATUS

SYNTAX

STATUS [0|1 ... 6|7]

DESCRIPTION

Lists statistics on how much of the disk on the specifieddrive has been used and how much of it remains availablefor new files. The default lists statistics on all driveswhich are ready.

Two error conditions are detected by the STATUS command.As part of the disk allocation maps kept on the disk,the number of free sectors and the number of allocatedsectors are maintained. In the event they do not sum upto the number of sectors on the disk, the message

WARNING: DISK STATISTICS ARE INCONSISTENT

is printed. If the total number of sectors marked asunallocated in the sector map do not equal the freesector count, then the following message is printed:

WARNING: ALLOCATION IS INCONSISTENT

This is somewhat more serious than the previous errorcondition and could mean that sectors which are logicallypart of a file are marked unallocated in the allocationmap. These errors may result from memory failure, diskwrite failure, deleting files with pointer errors, etc.,and generally indicate reformatting of the diskette.However, it may still be possible to read all files fromthe disk and avoid loss of data.


Unit 2: output listing

- 109 -

STATUS STATUS

EXAMPLES

%STATUS 0

DRIVE 0 RIO MCZ SYSTEM DISK659 SECTORS USED1805 SECTORS AVAILABLE

- 110 -

5.41VERBOSE VERBOSE

(Internal Command)

SYNTAX

Verbose

DESCRIPTION

Enter Verbose mode. Echo command strings as interpreted.Some commands test this mode before printing non-essentialmessages. See Brief command.


None

- Ill -

5.42XEQ XEQ

(Internal Command)

SYNTAX

Xeq [* I nn [parameter_list]]

DESCRIPTION

Begin execution of last loaded command with optionalparameter list, or begin execution at location nn withoptional parameter list.


None

EXAMPLES

XEQX *

Jumps to entry point of last loaded file.

X 5600 pi p2

Jumps to address 5600H with INPTR referencingdelimiter after '5600'.

X * pi p2

Jumps to entry point of last loaded file withINPTR referencing delimiter after '*'.

- 112 -

5.43EXPRESSION EVALUATION EXPRESSION EVALUATION

(Internal Command)

SYNTAX

: expression

DESCRIPTION

Evaluates hex constant expressions left to right andprints result. Allowable operators are +, -, *, and /,Overflow is not detected.

EXAMPLES

: FDOO-4400/800172

: 8732-4400/2000021

- 113 -

CHAPTER 6

ZDOS

6.0 ZDOS OPERATION

This chapter covers the program interface for the ZDOS-II floppydisk file access system used under Zilog's RIO operating system.It describes the general interface structure and callingsequence, and, for each of the different requests, givesthe details of the interface, a description of the actionstaken, and a list and interpretation of the errors thatcould occur with that operation.

ZDOS-II is an improved version of ZDOS, the diskette accesssystem which runs under earlier versions of Zilog software.For simplicity, in the remainder of this document ZDOS-IIwill be referred to as ZDOS.

ZDOS imposes a file structure on data stored on floppydisks. Data is stored as a sequence of records. All datarecords in a file are of the same length, and the lengthmust be an integral number of sectors of the diskette media,and an integral power of two (valid record sizes are 128,256, 512, 1024, 2048, and 4096 bytes). ZDOS maintains twopointers which are appended to each record. One is thedisk address of the following record, the other is thedisk address of the preceding record. The file is thusstored as a doubly-linked list of records.

Files are accessed by name through a directory. Thedirectory is itself a file, and can be accessed as such byits name, 'DIRECTORY1, which is the first entry in eachdirectory. Unlike other files, however, it has a knownfirst record so that it can be found; that is, it alwaysbegins at a fixed address known to the system. ZDOS'DIRECTORY' files are type directory, subtype 0.

A scratch file is a slight exception to this. A scratchfile is one which has existence only while it is active.

- 114 -

It is created by opening a file on a logical unit that hasan assignment to a zero-length name (all assignments areinitialized to scratch files, so opening a unit withoutmaking an assignment has the same effect). No directoryentry is created, and the descriptor information is onlystored internally rather than on the diskette. When the file isclosed, any records which have been created on it aredeallocated, and the file ceases to exist. Such a file isideal for temporary storage of intermediate data. Theprogrammer will find it advantageous to use scratch fileswhenever an application is suited to them, since openingthem does not involve the directory operations that openinga named file does, and is therefore faster.

The directory is made up of sectors. Each sector is, inturn, made up of one or more variable length entries. Eachentry consists of a single byte giving the length of thename, followed by the characters of the name, and a twobyte pointer to the descriptor record (described below).The file names can be from 1 to 32 characters in length.The last entry in a sector is followed by a byte of -1(OFFH). Directory entries do not span sector boundaries,so that if a new entry will not fit completely in a sector,it is put in the next one.

Occasionally, all the entries in a sector will be deleted.This happens relatively infrequently, and is indicated bythe first byte of the sector (normally a length byte, whichmust be from 1 to 32) being the terminator byte, OFFH.

The pointer contained in the directory entry for a filepoints to a special record, which is not one of the datarecords and is not included in the record count, calledthe file descriptor record. As its name indicates, itcontains information describing the file to the system.Some of the information is also available to the user.Regardless of the length of the data records, the descriptorrecord is always 1 physical sector, or 128 bytes long. Ofthese, ZDOS has defined 40 bytes, leaving 88 which areavailable for programmer definition. Note, however, thatthere are some system conventions on how these remainingbytes will be used for some files. Most notably, procedurefiles contain segment addresses and lengths in this area(see Appendix J).

- 115 -

The information contained in the descriptor record is asfollows:

Bytes 0-3 Reserved for future expansionBytes 4-5 File ID - currently unusedBytes 6-7 Pointer to directory sector holding

entry for this fileBytes 8-9 Pointer to first data record of fileBytes 10-11 Pointer to last data record of fileByte 12 File type and subtype - see

description with the OPEN requestBytes 13-14 Record countBytes 15-16 Record lengthBytes 17-18 Block length - currently unused,

and set to be same as record lengthByte 19 File properties - see description

with the OPEN requestBytes 20-21 Starting execution address for

procedure files (entry point)Bytes 22-23 Number of bytes in last recordBytes 24-31 Date of creationBytes 32-39 Date of last modificationBytes 40-127 Available for programmer definition

The Date of creation and Date of last modification are movedto the descriptor from the System Global Variable DATE at theappropriate times. Thus, if DATE is maintained to indicatethe current date, then the descriptor record can give somehistorical information about the file.

The information stored in the descriptor (except for thefirst 12 bytes) is available to the program accessing thefile at the time it is OPENed or while it is open by meansof a QUERY ATTRIBUTES request. It can also be supplied atthe time the file is created, or later by a SET ATTRIBUTESrequest, or when the file is UPDATED or CLOSED. See theappropriate request description for details.

Implicit in the description of accessing a file is theconcept of the file pointer. There are actually threepointers. The one referred to as the pointer is the"current record pointer", the disk address of the recordconsidered to be the current one. This is normally therecord last handled, as, for example, in reading orwriting. The "previous record pointer" contains the diskaddress of the record preceding the current one in thesequence of the file. The "next record pointer" contains the

- 116 -

disk address of the record following the current one in thesequence. A file is said to be active if these pointersare valid. OPENing a file consists of locating it in adirectory, reading its descriptor record, and initializingthese pointers. | I

A doubly-linked list provides some redundancy inestablishing the sequence of the records. This redundancyis used when traversing the file to check the fileintegrity. For example, the forward pointer of the currentrecord is used to establish the next record. When the nextrecord is read, its back pointer is checked to make sure itindicates the current record. A failure of this or asimilar check is what is referred to as a pointer error.

ZDOS is designed to operate with up to 8 floppy diskdrives, each holding approximately 300 Kbytes. Thestandard MCZ has two drives, configured as drive 0 (alsoreferred to as the system drive), and drive 2. The ZDSalso has two drives configured as drive 0 (referredto as the system drive), and drive 1. When a fileis to be located, and the drive is not specificallyindicated (equivalent to specifying '*'), the drives aresearched in order, starting with drive 1, and continuingthrough the highest disk which is attached and ready, andfinally, if still unsuccessful, concluding with drive 0.

Similarly, if a file is to be created without specifyingwhich disk it is to be on, it will be created on the firstdisk which is attached and ready in the same search order.

Under RIO, all I/O calls pass through the operating systemwhere they are routed to the required device driveraccording to the logical unit being requested and thecurrent routing for that unit. Calling parameters arepassed to the drivers via a 13-byte "parameter vector"which is pointed to by the IY register. There are two waysin which I/O calls are handled by the drivers. The drivermay perform the entire operation, then return to thecalling program (referred to as "return on completion"), orit may perform only the initial setup necessary, then returnto the calling program and let the operation proceed tocompletion under interrupt control (referred to as"immediate return"). A completion code is provided in theparameter vector to indicate when the operation is completeand signal any unusual circumstances of the completion.

- 117 -

The parameter is set up as follows:

(IY)

(IY+1)

(IY+2)

(IY+4)

(IY+6)

(IY+8)

Logical unit number (1 byte) -identifies the particular datasetbeing accessed. Used by OS toroute the call to the correct driver.

Request code (1 byte) - identifiesthe action to be taken. Two requestcodes are given for each operationin the following list. One is even,the other odd. If the first isused, the return will be on completionof the operation. If the second isused, then return will be immediate,with completion occurring underinterrupt control.

Data transfer area (2 bytes) - givesthe address at which data transferis to begin. If no data transfer isexpected for a given request, thisfield should be zero.

Length (2 bytes) - gives the lengthof the operation. For most operations,this is the number of bytes to transfer,but refer to specific operationdescriptions. If no data transfer isexpected, the length should be zero.On return, this gives the lengthactually completed.

Completion return address (2 bytes) -specifies address to branch to whenthe operation completes if the requestcode specified immediate return. Ifreturn on completion is specified,this element is ignored.

Error return address (2 bytes) - ifnon-zero, specifies the address tobranch to if an error occurs. Theerror will still be indicated in thecompletion return code. If theaddress is zero, return is as thoughthere were no error.

- 118 -

(IY+10)

(IY+11)

Completion code (1 byte) - indicateswhen the operation is complete.This byte is set to zero when thecall is made. Bit 7 is set when theoperation is complete. Bit 6 is setif an error occurred. The remainderof the byte will contain a codeindicating the nature of the difficultyor error. A normal completion willthus contain a code of '80'.

Supplemental parameter information -some requests require specialinformation which does not fit intothe general structure of the parametervector. This information is suppliedby the supplemental parameter vector.If two bytes or less (e.g., a diskaddress), it is normally put here.Otherwise an address pointer to anarea containing the information isplaced here.

- 119 -

Following is a list of error codes with their meaning.They will be discussed in detail under the description ofeach operation with which they can occur.

CODE MEANING(Base 16)

Cl Invalid operationC2 Not readyC3 ProtectionC4 Sector errorC5 Seek errorC6 Data transfer areaC7 File not foundC8C9 End of file errorCA Pointer check errorCB File not openCC Unit already activeCD Assign buffer fullCE Invalid disk driveCF Logical unit table fullDO Duplicate fileDl Diskette ID errorD2 Invalid attributesD3 Disk fullD4 File not in proper

directory recordD5 Beginning of file errorD6 File already open (on

another unit)D7 Invalid renameD8 File locked (attempt to

change attributes)D9 Invalid open requestDA Insufficient memory for

allocation maps

The following are warning codes. They do not have bit 6(the error bit) set, and do not cause transfer to the errorreturn address.

81 Directory format error82 Scratch file created83 File name truncated84 Attribute list truncated

- 120 -

There are some errors which are either not associated witha particular request, or can occur on almost every request,that are described in detail here. An INVALID OPERATIONerror (code Cl) will occur anytime the request code is notone of the valid operations for the device addressed. ZDOSwill respond with this code to operation READ LINE (OC),WRITE LINE (10), and WRITE DIRECT (14), as well asanything 32 or over.

Disk I/O errors can occur on almost any operation. Thereare 5 different errors that can occur, though some of themhave other meanings as well. A NOT READY error (code C2)indicates that an attempt was made to access a drive whichwas not asserting its READY signal. This may also signifydesignation of an operation to a drive which was recordedas being not ready at initialization. A WRITE PROTECTerror (code C3) indicates that an attempt was made to writeon a disk which is physically write protected. This couldalso indicate a request which would cause a change in afile which is (software) write protected, or a requestwhich would remove records from a file which is eraseprotected. A SECTOR error (code C4) is always a media orhardware problem, indicating that the sector headerinformation read did not agree with the location recordedon the disk. A TRACK ERROR (code C5) indicates thatthere was a hard seek error, or that the sector addressheader was destroyed, or else that an invalid track wasrequested from the floppy driver (a ZDOS software error!).A CRC ERROR (code C6) indicates that there was a dataerror in transmitting from the disk to memory, or that thedata was written incorrectly on the disk in the first place.

Another error which could conceivably occur almost anytimeis LOGICAL UNIT TABLE FULL (code CF). ZDOS maintains aninternal mapping between the 255 possible logical unitdesignations and the 16 for which it has space. The firstreference to a new unit causes it to be entered in thismap. If the unit given is not found in the map, and thereare no empty entries in it, then this error is returned.An entry is removed from this map when a file is closed, orwhen one is found to be not open when it should be. Thetable is also cleared when an INITIALIZE request is done.

- 121 -

6.1INITIALIZE INITIALIZE

Request vector:

Logical unit - ignoredRequest code - 00 or 01Data transfer area - ignoredLength - ignored. Zero will be returned.Completion return addressError return addressCompletion codeSupplemental parameter information - none

Action:

All 16 logical units are flagged as not open.The logical unit map is cleared. Memoryis allocated at the top of the availablespace for each map, and the maps are readin from the disk. A flag word is constructedindicating which drives are ready.

Possible errors:

Disk SECTOR, SEEK, or DATA TRANSFER errors(C4, C5, or C6). The initialization is notcompleted if one of these occur.

INSUFFICIENT MEMORY (code DA) - There wasinsufficient memory available to fulfillone or more of the requests for space forthe allocation maps.

- 122 -

6.2ASSIGN ASSIGN

Request vector:

Logical unitRequest code - 02 or 03Data transfer area - ignoredLength - ignored. Zero will be returned.Completion return addressError return addressCompletion codeSupplemental parameter information - pointer to

area containing the following:1st byte of area - ignored by ZDOS.

(This byte does control systemfunctions however. See Section 3.3.)

2nd byte of area - character designatingphysical disk drive, either '0' through'7' , or '*'.

3rd byte of area - length in bytes of filename. A 0 length name indicates ascratch file. The maximum length name is32 characters.

4th and following bytes - the filename.

Action:

The filename given is associated with(assigned to) the given logical unit forsubsequent I/O operations. Any previousassignment to the same logical unit isnullified. The filename is stored in abuffer for later use when the logicalunit is opened. When the file isopened, the filename is removed fromthe buffer. Thus, if a file isopened and closed, there must be anew assignment before it can bereopened.

- 123 -

ASSIGN ASSIGN

Possible errors:

FILE ALREADY OPEN (code CC) - an attemptto assign a file to a unit which iscurrently active. The assignment is notmade.

INVALID DRIVE (code CE) - some drive isspecified other than '*' or 'O'-'V.

ASSIGN BUFFER FULL (code CD) - the bufferused for storing filenames afterassignment prior to files being opened istoo full to hold the name assigned. Theassignment is not made.

NAME TOO LONG (code 83) - thiscircumstance is only a warning. The namegiven was indicated as being longer thanthe maximum length and was truncatedaccordingly.

- 124 -

6.3OPEN OPEN

Request vector:

Logical unitRequest code - 04 or 05Data transfer area - A pointer to an area

containing the attributes that the file is tobe created with, if it gets created, or wherethe attributes can be returned if the fileexists. See below for a detailed descriptionof these attributes. If this pointer is zero,a set of default attributes will be suppliedif the file is created. Nothing will bereturned if the file is found.

Length - The number of bytes to transfer to/fromthe attributes in the data transfer area. Ifthis is zero, or less than the minimum set ofattributes for a new file, and the file needsto be created, the balance will be suppliedfrom defaults. See below for a detaileddescription of attributes.

Completion return addressError return addressCompletion codeSupplemental parameter information - Pointer to an

area containing the following:1st byte of area - designation of the type of

action to be performed on the open. Seebelow for possibilities.

2nd byte of area - A byte for returning acharacter representing the disk drive thefile was opened on. A character 'O'-1?1

will be returned in this byte. If a newassignment is to be made, such acharacter or '*' should be supplied bythe calling program to indicate wherethe file is to be searched.

- 125 -

OPEN OPEN

3rd byte of area - length of file name. Theopen request can do its own assignment,removing the necessity for two calls toZDOS. If this is done, it will overrideany assignment done previously. Thissupplemental information should lookexactly like the supplemental informationfor an assign request. If no assignmentis to be made, however, this byte shouldbe -1 (OFFH).

4th byte and following - filename if there isone.

File attributes:

Each file has a 128-byte record referred to as the filedescriptor record. This contains information concerningthe type of file, where it is on the disk, how it isorganized, etc. Only 40 of the 128 bytes are used bythe system, leaving the remainder for possible use bythe user. When a file is created, the organization,etc., must be specified by the user, either explicitlyor by default. Similarly, when a file is opened, theinformation about the organization may be needed by theprogram. In order to accomplish both these ends, thatportion of the file descriptor record which may be ofuse to the programmer can be passed back and forth. Itis laid out as follows:

1 Type and subtype. There are 4 types of filesrecognized by the system. Each is assignedone of the top four bits of this word. Thebottom four bits are available for userdefined subtypes.Bit 7 - procedure type files.Bit 6 - Directory files.Bit 5 - ASCII files.Bit 4 - Data files.

The default is ASCII subtype 0 (20H).

2-3 Record count. Number of records in the file.

- 126 -

OPEN OPEN

4-5 Record length in bytes. The default is 128.If zero is specified, the default will beassumed.

6-7 Block length in bytes. This has to do withlogical blocking of records, which iscurrently unimplemented. This is thereforeset to the record length.

8 File properties. The following bits areassigned:Bit 7 - Write protection - the file cannot be

changed.Bit 6 - Erase protection - nothing can be

removed from the file. Writeprotection implies erase protection,but not vice versa.

Bit 5 - Locked - No attributes can bechanged.

Bit 4 - Secret - the file will not appear innormal directory listings.

Bit 3 - Random - file is set up for randomaccess. This has not been defined atthis time.

Bit 2 - FORCE file loading.Bit 1 - Reserved for system use.Bit 0 - Reserved for system use.

9-10 Start address - Address at which execution ofa procedure file should begin. Not used byZDOS itself.

11-12 Reserved for system use.

13-20 Date of creation. This is supplied by ZDOSfrom the system global DATE.

21-28 Date last written. This is supplied by ZDOSfrom the system global DATE.

29-116 Available for user definition.

- 127 -

OPEN OPEN

Types of open requests:

There are several ways the activation ofa file may be handled. These are specifiedby the 1st word of the supplemental parameterinformation. A file may be opened for eitherrandom or sequential access. Random accessis specified by setting bit 3 of this word.Currently, a file being open for randomaccess has two implications. One is that theREAD DIRECT request will be accepted (itwill be refused with an INVALID REQUEST errorotherwise). The other is that in each recordoriented operation, the disk address of thefirst record involved will be returned to thecalling program in the supplemental parameterinformation field of the parameter vector.

There are five mutually exclusive ways thatthe cases of file not found/ file found maybe handled. These are specified in thebottom 3 bits of this word. They are asfollows:

Open for input - 0 - if the file exists, it will be "—activated with the pointer ahead of the firstrecord. If it does not exist, a FILE NOTFOUND error (code C7) is returned.

Open for output - 1 - If the file exists, it isactivated and all its records are deleted. Ifit does not exist, it is created.

Open new file - 2 - (also referred to as open fornondestructive output) - if the file exists, aDUPLICATE FILE error (code DO) is returned,and the file is not activated. If the filedoes not exist, it is created.

Open for append - 3 - if the file exists, it is *activated with the pointer positioned at thelast record. If it does not exist, it iscreated.

Open for update - 4 - if the file exists, it isactivated with the pointer ahead of the firstrecord of the file. If it does not exist, itis created.

- 128 -

OPEN OPEN

Action:

If a filename assignment is specified (3rd byteof the supplemental information is not -1),the ASSIGN subroutine is called as though anASSIGN request had been made. If there is afilename assigned to the unit, i.e., if it is notassigned to a scratch file, the directory onthe specified drive is searched for thefilename. If the drive is specified as '*', acheck is made to determine the ready status ofall drives, then each ready drive is searched,from drive 1 to drive 7, followed by drive 0,until the file is found or all drives havebeen searched.The ID of the diskette which holds orwill hold the file is read into a buffer andcompared against the ID on the correspondingmap in memory. If they do not match, and noother unit has a file open on the samephysical drive, a new map (and ID) will beread into memory. If another unit is open onthat drive, a WRONG DISKETTE error will bereturned and the file will not be activated.If the file is found, its descriptorrecord is read, the relevant parts are movedinto the active file table entry for the unit,and, if requested, moved to the user's datatransfer area. The file is then flagged asopen. If the file is to be created, thedescriptor record is created in a buffer, thenmoved to the active file table, and, ifrequested, to the user's data area. If thefile is not a scratch (no-name) file, thedescriptor record is written out to the diskand a directory entry is created.

Possible errors:

All DISK ERRORS are possible. NOT READY (codeC2) may indicate designation of a specificdrive that was recorded as 'not ready1 thelast time the ready status was checked.

- 129 -

OPEN OPEN

PROTECTION (code C3) - may occur as a diskerror if the diskette is wr ite-protected , ormay occur by an attempt to open an existingfile which is write- or erase-protected foroutput (thus deleting its records) . In thatcase, the file is opened but its records arenot deleted.

UNIT ALREADY OPEN (code CC) - the logical unitis already active. It must be closed, or aninitialize operation must be performed, beforeit can be OPENed again. No action is taken.

WRONG DISKETTE (code Dl) - the disk ID of thediskette in the drive does not match the ID inmemory. Usually indicates that the disks havebeen switched since an INITIALIZE operationwas performed, or that a program hasoverwritten the maps in memory. The file isnot opened.

FILE NOT FOUND (code C7) - the open requestwas for input, and the file designated doesnot exist. /

POINTER ERROR (code CA) - could occur if thepointers linking the segments of the directorytogether have been destroyed or overwritten,or if the file exists and the pointers for thedescriptor record are incorrect, or, indeleting the records of an existing file, apointer mismatch occurs.

DUPLICATE FILE (code DO) - request to open anew file when the file already exists. Thefile is not activated.

INVALID ATTRIBUTE (code D2) - one of theattributes specified for the creation of thefile was invalid. This may be that more thanone (or none) of the four mutually exclusivetypes was specified, or that an invalid recordsize was specified. The file is activated withthe defaults substituted for the erroneousattributes.

- 130 -

OPEN OPEN

DISK PULL (code D3) - there was no space toallocate a descriptor record, or a newdirectory record if one needed to beallocated. Can only occur if the file isbeing created.

FILE ALREADY OPEN (code D6) - the filerequested to be opened on this unit is alreadyactive on another unit. The unit is notactivated.

PROPERTIES PROTECTION (code D8) - an attemptto change attributes on a locked file. Theattributes are not changed.

INVALID OPEN REQUEST (code D9) - a type ofopen request which was not input, output,newfile, append, or update was specified. Noaction is taken.

INSUFFICIENT MEMORY (code DA) - if additionaldisks have been inserted prior to the openrequest and insufficient memory is availablefor additional allocation maps, this errorwill be returned.

The following are warning codes, and will not causethe error return branch to be taken.

DIRECTORY FORMAT ERROR (code 81) - Indicatesthe format of one or more directory records iserroneous. The record can still be read, butits data is suspect.

SCRATCH FILE (code 82) - informative messagethat a scratch file has been created.

ATTRIBUTES TOO LONG (code 84) - more than 116bytes of attribute information were requested.Only 116 bytes were transferred.

In addition, if an assign is implicit inthe open request, any error that can occurwith assign could occur.

- 131 -

6.4CLOSE CLOSE

Request vector:

Logical unitRequest code - 06 or 07Data transfer area - a pointer to an area which may

contain attributes to replace those of thefile. The format is the same as for the OPENrequest. If no replacement of attributes isdesired, the data transfer area should bezero.

Length - Number of bytes to move to the descriptorrecord from the data transfer area. If nodata is to be moved, it should be zero. Themaximum is 116 decimal bytes.

Completion return addressError return addressCompletion codeSupplemental parameter information - none

Action:

If the logical unit is a scratch file, the fileis erased. If there have been any changes inallocation to the file, or if new attributesare to be written, its descriptor record isread, updated, including moving in any newattributes supplied by the calling program,and rewritten, and the allocation map isrewritten. The file is then flagged as beingclosed, and indicators are set to indicate anassignment to a scratch file.

Possible errors:

FILE NOT OPEN (code CB) - the logical unit isnot active. No action is taken.

- 132 -

6.6READ BINARY READ BINARY

Request vector:

Logical unitRequest code - OA or OBData transfer area - the address to which data

should be transferredLength - the number of bytes to transfer. If this

number is not an integral multiple of therecord size, it will be rounded up until itis. On return, this will contain the actualnumber of bytes transferred.

Completion return addressError return addressCompletion codeSupplemental parameter information - if the file is

open for random I/O, this field should containthe address of a three-byte area where thedisk address of the first record read will bereturned. Otherwise, it is unused.

Action:

Data is read from the file, starting at thenext record, into the data transfer area. Thepointer is left on the last record read. Ifthe file is open for random I/O, the diskaddress of the first record read is returnedin the field pointed to by the supplementalparameter information. The third byte ofthis address will always be zero.

Possible errors:

All DISK ERRORS except PROTECTION (code C3)are possible.

- 135 -

6.5REWIND REWIND

Request vector:

Logical unitRequest code - 08 or 09Data transfer area - ignoredLength - ignoredCompletion return addressError return addressCompletion codeSupplemental parameter information - none

Action:

The file pointer is positioned at thedescriptor record, with the first record asthe next record. This is the position thefile pointer assumes when the file is openedfor other than append, or when it is created.If there are no records in the file, the nextrecord pointer is null.

Possible errors:

FILE NOT OPEN (code CB) - the logical unitbeing accessed is not active. No action istaken.

- 134 -

6.7 tWRITE BINARY WRITE BINARY

Request vector:

Logical unitRequest code - OE or OFData transfer area - the address from which data is

to be transferred.Length - the number of bytes of data to transfer.

If this number is not an integral multiple ofthe record size, it will be rounded up untilit is. On return, this will contain theactual number of bytes transferred.


open for random I/O, this field should containthe address of a three-byte area where thedisk address of the first record written willbe returned. If not, it is unused.

Action:

New records are created and filled with datafrom the data transfer area. The new recordsare inserted after the current one. Thepointer is left at the last record written.The next record pointer remains on the samerecord it was prior to the operation.

Possible errors:

All DISK ERRORS are possible except CRC (codeC6). PROTECTION (code C3) will also bereturned by ZDOS if the file is writeprotected.

- 137 -

READ BINARY READ BINARY


END OF FILE (code C9) - the last record of thefile was read and the given length had notyet been fulfilled. The length returnedreflects the number of bytes actually read.

POINTER ERROR (code CA) - a pointer mismatchoccurred. The reading stops at the point itis detected. The length returned will includethe record which had the error.

- 136 -

6.8WRITE CURRENT WRITE CURRENT

Request vector:

Logical unitRequest code - 12 or 13Data transfer area - the address from which data is

to be transferred.Length - if the length is zero, no data will be

transferred. Otherwise, one record will betransferred. On return, length will containthe number of bytes transferred.

Completion return addressError return addressCompletion codeSupplemental parameter information - if the unit is

open for random I/O, this field shouldcontain the address of a three-byte areawhere the disk address of the record willbe returned. Otherwise, it is unused.

Action:

Data is moved from memory to the file,replacing the data in the current record. Nonew records are created, and the recordpointer is not moved.

Possible errors:

All DISK ERRORS except CRC (code C6) arepossible. PROTECTION (code C3) will also bereturned by ZDOS if the file is writeprotected.


- 139 -

WRITE BINARY WRITE BINARY


DISK FULL (code D3) - there is no room on thedisk to allocate a new record. Records whichwill fit are written. The length returnedreflects the number of bytes written beforethe disk filled up.

- 138 -

DELETE DELETE

END OF FILE (code C9) - the last record of thefile was deleted, and the length specified hadnot yet been exhausted. The number of bytesreturned will indicate the number deleted,including the last record. The pointer isleft at the record preceding the first onedeleted, with the next record pointer beingnull.

POINTER ERROR (code CA) - a pointer mismatchoccurred while traversing the records of thefile in deleting them. Records are deleted upto the one preceding the mismatch.


- 141 -

6.9DELETE DELETE

Request vector:

Logical unitRequest code - 16 or 17Data transfer area - ignored.Length - the number of bytes of data to be removed

from the file. If this number is not anintegral number of records, it will be roundedup to the next full record. On return, lengthwill contain the number of bytes deleted.

Completion return addressError return addressCompletion codeSupplemental parameter information - none.

Action:

Starting at the current record, records areremoved from the file, and the space taken upby them deallocated (made available), untilthe given number of bytes have been removed.The current record pointer is left on therecord preceding those deleted. The nextrecord pointer is left at the record followingthose deleted.If the file is currently positioned onthe descriptor record (top of the file), thepointer will be advanced to the first recordbefore the operation is started. This is notcounted as one of the records deleted. Afterthe operation, the pointer will again be onthe descriptor record.

Possible errors:

All DISK ERRORS are possible. PROTECTION(code C3) will also be returned by ZDOS if thefile is either write or erase protected.

- 140 -

6.11 , , .ERASE , ERASE

Request vector:

Logical unitRequest code - 1A or IBData transfer area - ignoredLength - ignored. The total number of bytes

deleted is returned.Completion return addressError return addressCompletion codeSupplemental parameter information - none

Action:

All records of the file are deallocated (theirspace is made available), the descriptorrecord is deallocated, and the directory entryfor the file is removed from the directory,thus rendering the file completelyinaccessible. The file does not have to beopen, but it must have been assigned.

Possible errors:

All DISK ERRORS are possible. In addition,PROTECTION (code C3) will be returned by ZDOSif the file is write- or erase-protected. NOTREADY (code C2) will be returned if thespecified drive for the file is not loaded andready.

FILE NOT FOUND (code C7) - The named filecannot be located on the drive specified.Will not occur if the file is open when therequest is given.

- 143 -

6.10DELETE REMAINING RECORDS DELETE REMAINING RECORDS

Request vector:

Logical unitRequest code - 18 or 19Data transfer area - ignoredLength - ignored. The total number of bytes

deleted is returned.Completion return addressError return addressCompletion codeSupplemental parameter information - none

Action:

All records from the current one to the end ofthe file are removed. The pointer is left onthe record preceding those deleted. The nextrecord pointer is null. If the pointer is onthe descriptor before the operation, it ismoved forward before deletion begins.

Possible errors:

All DISK ERRORS are possible. PROTECTION(code C3) will also be returned if the file iswrite- or erase-protected.

POINTER ERROR (code CA) - will occur if, intraversing the records of the file, a pointermismatch is found. The records will bedeleted up to, but not including, the recordpreceding the mismatch.

FILE NOT OPEN (code CB) - the requestedlogical unit is not active. No action istaken.

- 142 -

6.13READ CURRENT READ CURRENT

Request vector:

Logical unitRequest code - IE or IFData transfer area - address to which data should

be readLength - number of bytes to read. If this is zero,

no data will be transferred. Otherwise, onerecord of data will be transferred. Thenumber of bytes actually transferred will beindicated here on return.


open for random I/O, this field should containthe address of a three-byte area where theaddress of the current record will be returned.Otherwise, it is unused.

Action:

Unless the length specification is zero, onerecord's worth of data is transferred from thecurrent record. The pointer is left unmoved.

Possible errors:


POINTER ERROR (code CA) - if the back pointer ofthe current record does not indicate theprevious record, a pointer error is reported.The data is still transferred.

- 147 -

ERASE ERASE

POINTER ERROR (code CA) - A pointer mismatchoccurred either while locating the file orwhile traversing the records of the file. Allrecords beyond the pointer mismatch willremain allocated and thus be unavailable forfurther use.

INVALID DRIVE (code CE) - The drive specifiedin the assignment was something other than '0'- '71. '*' is not a valid specification for afile being erased.

WRONG DISKETTE (code Dl) - the ID for thediskette the file is on does not match the IDin memory for that diskette. Usuallyindicates that the diskette has been changedor that a program has overwritten the ZDOS maparea. The file is not erased.

FILE NOT FOUND IN DIRECTORY (code D4) - thiserror indicates that no directory entry forthe file could be found in the segment of thedirectory indicated by the descriptor record.The records will be deallocated, but adirectory entry may remain somewhere else. Ifthis error occurs, it is best to copy allremaining files to another diskette andreformat the one in question, as any furtheraccess to the bad file is liable to causepointer errors and other complications.

FILE ALREADY OPEN (ON ANOTHER UNIT) (code D6)- this error will result from an attempt toerase on one unit a file which is currentlyactive on another unit. No action will betaken.

- 144 -

6.14READ PREVIOUS READ PREVIOUS

Request vector: ,

Logical unitRequest code - 20 or 21Data transfer area - address to which data should

be readLength - number of bytes to read. If this is zero,

no data will be transferred. Otherwise, onerecord of data will be transferred. Thenumber of bytes actually transferred will beindicated here on return.


open for random I/O, this field should containthe address of a three-byte area where thedisk address of the previous record will bereturned. Otherwise, it is unused.

Action:

Unless the length is zero, the record precedingthe current one is read. In either case, thepointer is backed up one record. The currentrecord will become the next record, theprevious one the current record, and the onepreceding the previous record will become thenew previous record.

Possible errors:

ALL DISK ERRORS except PROTECTION (code C3)are possible.

POINTER ERROR (code CA) - if the forwardpointer on the previous record does notindicate the current one, a pointer error isreported. The data is still transferred.

- 149 -

READ AND DELETE READ AND DELETE

Possible errors:

All DISK ERRORS are possible. In addition,PROTECTION (code C3) will be returned by ZDOSif the file is write- or erase-protected.

END OF FILE (code C8) - the last record of thefile was read without exhausting the lengthspecification. The number of bytes read isreturned in the length field, and the nextrecord pointer is null.

POINTER ERROR (code CA) - a pointer mismatchoccurred in going from one record to the next.The data transfer stops with the record inerror. The length field indicates how manybytes were transferred prior to the error.

FILE NOT OPEN (code CB) - the logical unitbeing requested is not active. No action istaken.

- 146 -

6.15READ DIRECT READ DIRECT

Request vector:in

Logical unitRequest code - 22 or 23Data transfer area - memory address to which data

is to be transferred.Length - number of bytes of data to transfer. If

this number is not an integral number ofrecords, it will be rounded up until it is.The number of bytes actually transferred willbe reported in this field.

Completion return addressError return addressCompletion codeSupplemental parameter information - a pointer

to a three-byte area containing the diskaddress of the first record to be read. Thethird byte of this area should be zero. Itis the calling program's responsibility tobe certain this sector is a part of the filebeing accessed. This field will be unchangedon return.

Action:

The record whose disk address is given is readas though it were the next record, but nopointer checking is done on it. If more thanone record is specified for the length,subsequent records are read just as in theread binary request. This request is onlyvalid if the file has been opened for randomI/O.

- 151 -

READ CURRENT READ CURRENT


BEGINNING OF FILE (code D5) - the pointer ison the descriptor record, which cannot beread. No data is transferred, and a nulladdress is returned if open for random I/O.

- 148 -

6.16SKIP FORWARD SKIP FORWARD

Request vector:

Logical unitRequest code - 24 or 25Data transfer area - ignoredLength - the number of records (not bytes) to be

skipped. On return, the number of recordsskipped will be reported.

Completion return addressError return addressCompletion codeSupplemental parameter information - if file is

open for random I/O, this field should containthe address of a three-byte area where thedisk address of the first record skipped willbe returned. Otherwise, none.

Action:

The current record pointer is advanced throughthe file by the number of records indicated.No data is transferred.

Possible errors:


END OF FILE (code C9) - the last record of thefile was reached while there remained recordsto skip. The pointer is left at the lastrecord of the file, with a null pointer forthe next record.

POINTER ERROR (code CA) - a pointer mismatchoccurred while traversing the records of thefile. The current record pointer is left atthe record preceding the mismatch.

- 153 -

READ PREVIOUS READ PREVIOUS


BEGINNING OF FILE (code D5) - if the recordindicated is the descriptor record of thefile, the pointer is positioned at thebeginning and a previous record ismeaningless. No action is taken. A null diskaddress is returned if the file is open forrandom I/O.

- 150 -

6.17SKIP BACKWARD SKIP BACKWARD

Request vector:

Logical unitRequest code - 26 or 27Data transfer area - ignoredLength - the number of records (not bytes) to be

skipped. On return, the number of recordsskipped will be reported.


open for random I/O, this field should containthe address of a three-byte area where thedisk address of the record preceding thecurrent one will be reported. Otherwise, none,

Action;

The current record pointer is moved backwardthrough the file by the number of recordsindicated. No data is transferred.

Possible errors:


POINTER ERROR (code CA) - a pointer mismatchoccurred while traversing the records of thefile. The current record pointer is leftindicating the record following the error.


- 155 -

READ DIRECT READ DIRECT

Possible errors:

INVALID REQUEST (code Cl) - if the file is notopen for random I/O, the read direct requestwill be rejected with this error.

All the errors of the READ BINARY requestapply for the READ DIRECT request as well.

- 152 -

6.18SKIP TO END SKIP TO END

Request vector:

Logical unitRequest code - 28 or 29Data transfer area - ignoredLength - ignored. Zero will be returned.Completion return addressError return addressCompletion codeSupplemental parameter information - if the file is

open for random I/O, this field should containthe address of a three-byte area where thedisk address of the last record in the filewill be returned. Otherwise, it is unused.

Action:

The file is positioned with the current pointerindicating the last record of the file.

Possible errors:

All DISK ERRORS are possible with theexception of PROTECTION (code C3).

POINTER ERROR (code CA) - the forward pointerof the last record was not null, indicating itwas not, in fact, the last record.


- 157 -

SKIP FORWARD SKIP FORWARD


- 154 -

RENAME RENAME

POINTER ERROR (code CA) - the back pointerfrom the descriptor record did not point tothe directory. No further action is taken.

DUPLICATE FILE (code DO) - a file of the samename as the new name already exists. The fileis not renamed.

DISK FULL (code D3) - it was necessary tocreate a new directory record to contain thenew name, and the disk was too full to allowit, or too full to allow creation of thedescriptor record if renaming a scratch file.

FILE NOT IN PROPER DIRECTORY RECORD (code D4)- no directory entry for the file exists inthe directory record indicated by itsdescriptor. No action is taken.

FILE ALREADY OPEN ON ANOTHER UNIT (code D6) -the file assigned to the unit being accessedis currently active on another logical unit.No action is taken.

INVALID RENAME (code D7) - attempt to rename afile either to a scratch file (zero lengthname) or to a name longer than the maximumname length (32 characters). The file is notrenamed.

- 159 -

SKIP BACKWARD SKIP BACKWARD

BEGINNING OF FILE (code D5) - the beginning ofthe file was reached without exhausting thegiven record count. The pointer is leftpositioned on the descriptor, with the firstrecord of the file being next.

- 156 -

UPDATE UPDATE

WRONG DISKETTE (code Dl) - the diskette ID forthe drive for this file does not agree withthe ID in memory for that drive. Usuallyindicates the diskette has been changed sincethe file was opened, or that a program wroteacross the allocation maps. No action istaken.

INVALID ATTRIBUTES (code D2) - one or more ofthe attributes being supplied either is or wasinvalid. The attributes checked are type(there should be exactly one of the mostsignificant bits on) and record length. Theattribute which was wrong is left as it was,and the remainder of the process is carriedon.

PROPERTY PROTECTION (code D8) - if the file islocked, no attributes are to be changed. Anattempt to do so results in this error.

- 161 -

6.19RENAME RENAME

Request vector:

Logical unitRequest code - 2A or 2BData transfer area - ignoredLength - ignoredCompletion return addressError return addressCompletion codeSupplemental parameter information - a pointer to

an area configured as follows1st byte - length of name2nd and following bytes - new name

Action:

The file on the unit requested is given the newname which is contained in the supplementalparameter vector. The file may be open. Ifit is not, there must be a pending assignmentfor it, so that it can be opened. If it isnot already open, it will be activated, thenits directory entry removed from the directoryand a new one created. An open scratch filemay be recovered (requiring its descriptorrecord to be created) , but a named file cannotbe renamed to a scratch file. Finally, if thefile was not open at the start of theoperation, it is deactivated.

Possible errors:

All DISK ERRORS are possible.

FILE NOT FOUND (code C7) - the unit beingaccessed was not open and the file assigned toit does not exist. Will also occur if theunit is assigned to a scratch file which hasnot yet been created. No action is taken.

- 158 -

SET ATTRIBUTES SET ATTRIBUTES

INVALID ATTRIBUTES (code D2) - one or more ofthe attributes being supplied either is or wasinvalid. The attributes checked are type(there should be exactly one of the mostsignificant bits on) and record length.The attribute which was wrong is left as itwas, and the remainder of the process iscarried on.

PROPERTY PROTECTION CODE (code D8) - if thefile is locked, no attributes are to bechanged. An attempt to do so results in thiserror.

- 163 -

6.20UPDATE UPDATE

Request vector:

Logical unitRequest code - 2C or 2DData transfer area - address of attributes to be

assigned to the file. Format is describedunder the OPEN request.

Length - number of bytes of attribute informationto be used.


Action:

If there have been any changes to the file, orif there are attributes to be updated, thedescriptor is read, updated, and rewritten,and the allocation map is rewritten. Theattributes of the file can be changed with theupdate request in the same way as by the closerequest. The file remains active.

Possible errors:


POINTER ERROR (code CA) - will occur if theback pointer for the descriptor does notindicate the directory record for the file.

FILE NOT FOUND (code CB) - the logical unitbeing accessed is not active. No action istaken.

- 160 -

QUERY ATTRIBUTES QUERY ATTRIBUTES

ATTRIBUTE LIST TRUNCATED (code 84) - this codeis a warning and will not cause an errorbranch. It indicates that more than 116 bytesof attribute information were requested.Only 116 bytes were transferred.

- 165 -

6.21SET ATTRIBUTES SET ATTRIBUTES

Request vector:

Logical unitRequest code - 2E or 2FData transfer area - address of attributes to be

assigned to the file. Format is describedunder the OPEN request.

Length - number of bytes of attribute informationto be used.


Action:

The descriptor record is read and updated fromthe current information and the attributessupplied and rewritten.

Possible errors:


POINTER ERROR (code CA) - will occur if theback pointer for the descriptor does notindicate the directory record for the file.

FILE NOT FOUND (code CB) - the logical unitbeing accessed is not active. No action istaken.

- 162 -

The MCZ 1/35 bootstraps directly from DPS. The 4K monitorproms for this system contain the system residentportion of the DFS driver and the system bootstrap.ZDOS is supplied on the disk for use with optional floppydisk drives and is linked to run at the top of memory.There is a separate entry point for the FLOPPY driver attwo greater than the entry point for ZDOS. When activatingZDOS, FLOPPY should be activated with an address in the samemanner as was described above for DISK, i.e.

ACTIVATE $ZDOS;X * $FLOPPY E002

Command files for these systems are normally linked at 2AOO.

- 167 -

6.22QUERY ATTRIBUTES QUERY ATTRIBUTES

Request vector:

Logical unitRequest code - 30 or 31Data transfer area - address for return of

attributes of the file.Length - number of bytes of attribute information

to be returned.Completion return addressError return addressCompletion codeSupplemental parameter information - none

Action:

This command is used for obtaining attributeinformation, such as the record count, while afile is open. The descriptor record is read,the current information merged into it, and asmany bytes of attribute information as havebeen requested are returned to the user. Seethe OPEN request for the format of thereturned bytes.

Possible errors:


POINTER ERROR (code CA) - the back pointer ofthe descriptor record does not indicate thedirectory record. No data is returned.


- 164 -

programs which access the directory, becausethere are now 3-byte pointers at the endof each entry instead of 2-byte pointers. Tofacilitate differentiation between the two formats,the DPS directory file is subtype 1.

4) There are three commands which apply exclusively to DFSdisks. They are described in the following sectionsof this manual:

Command Section

DISK.FORMAT 5.16DISK.REPAIR 5.17DISK.STATUS 5.18

5) For systems with floppy disks, software updates will besupplied on floppy diskettes as required. For systemswithout diskette drives, software updates are suppliedon disk cartridges at an additional cost.

6) The GET/SAVE Debug commands have not yet been implementedfor DFS hard disks.

7) The user and system operator should be familiar withthe disk manufacturer's recommended operations pro-cedures provided in separate manuals. Theseparagraphs are not intended to substitute for thosedocuments. Nevertheless, we will briefly discussdisk start-up and shut-down procedures. These pro-cedures apply to the Caelus Model 206R front-loadingcartridge disks. Similar procedures would apply toother drives of the same class.

Prior to bootstrapping the system, turn power on tothe disk drive and disk controller. After a delayof perhaps 10-15 seconds, the "stop" light on the diskfront panel will be illuminated. At this time openthe door and slide in the cartridge to be used for thesession. Close the door and turn the run/stop switchto run. After a delay of about a minute, the readylight will come on. At this point the bootstrapfile from the disk is read into the controller memory.The disk is now ready for operation. Bootstrap the system.

- 169 -

CHAPTER 7

DPS

7.1 ZILOG DISK CONTROLLER

The interface from a Zilog Z-80 System to high-speed diskunits consists of an intelligent disk controller in amodule separate from the system, and a high speed serialinterface link from the system to the controller. Thecontroller contains its own Z-80 CPU, sockets for 8K of ROM (ofwhich only 3K is currently used), 16K of static RAM, Direct MemoryAccess (DMA) control circuitry, the data decode/encode interfacecircuitry and miscellaneous control signal interface logic. Theinterface is to Caelus Model 206R or similar units. It willsupport up to four disk drives with appropriate daisy-chainedcabling.

The software for this configuration makes the diskappear as another file system, functionally identicalto the ZDOS file system which exists for the floppy disks.

The Disk File System (DFS) software is capable of running intwo versions. On the MCZ 1/20, the system is bootstrapped fromthe floppy disks as a standard system. The system residentportion of DFS must be loaded from ZDOS by the command ACTIVATE$DFS. ZDOS is at 2AOO, immediately above the console driverfor RIO, and DFS is placed at the top of memory.DFS contains an entry point for DISK, the low leveldisk controller used by some utilities; it is 2 greaterthan the entry point for DFS, and should be activatedwith an address at the same time DFS is activated,thus:

ACTIVATE $DFS;X * $DISK E002

If DFS is to be run as the master device, then the commandMASTER $DFS should follow these. At this point ZDOS can bedeactivated, thus effecting a large savings in memory space,unless it is needed for transfers to diskette.

- 166 -

7.3 SOFTWARE ORGANIZATION

The Disk File System driver is divided into two parts tocorrespond to the division of the hardware interface.One part is resident on the host system and contains themessage interface link to communicate with the controller,It is used to pass I/O requests to the controller andto send and receive data.

The second, and larger part, is the software whichresides in the memory of the intelligent controller.Most of this is loaded from the disk whenever thecontroller is reset. The software in ROM includes theinitial start-up and serial message interface logic,the bare disk controller, which gives access to thedisk by sector number for reads and writes, and theself-bootstrapping logic to read the rest of the filesystem from the disk. The disk file system, whichis an adaptation of the ZDOS-II file system, and aninterface for handling the request vector across theremote serial interface, are loaded from the disk.

There are two entry points to the resident software,each of which takes a standard I/O vector. One, DFS,causes the vector to be taken as a request to the DiskFile System on the controller, and the other, DISK(located at address of DFS + 2), causes it to betaken as a request to the bare disk controller.

- 171 -

7.2 DPS OPERATION

Except where noted otherwise, the information contained inChapter 6 regarding ZDOS also applies to DPS.

The following are the major differences between the twofile systems:

1) The DPS descriptor record differs from the ZDOS des-criptor record:

Bytes 0-3 UnusedBytes 4-7 File IDBytes 8-10 Pointer to directory sector holding

entry for this fileBytes 11-13 Pointer to first data record of fileBytes 14-16 Pointer to last data record of fileByte 17 File type and subtypeBytes 18-19 Record countBytes 20-21 Record lengthBytes 22-23 Block length - currently unused, and set to

be same as record lengthByte 24 File propertiesBytes 25-26 Starting execution address for procedure

type files (entry point)Bytes 27-28 Number of bytes in last recordBytes 29-36 Date of creationBytes 37-44 Date of last modificationBytes 45-132 Undefined by DFS - used by RIO for

procedure filesBytes 133-511 Available for programmer definition

2) While ZDOS accepts records of several lengths(multiples of 128 (80H) bytes), the record lengthon DFS must be equal to the physical sector length(512, or 200H bytes). A request to set it to anyother record length results in an invalid attributeerror (code D2H). However, a request for recordlength 0 is treated as a request for the default,or 200H.

3) Because some of the disks to be interfaced to thissystem have more than 65535 sectors, three bytesare used for all disk addresses. This affects

- 168 -

NSECS -- byte 423 — number of sectors per track

SECMAP — bytes 424-487 — sector interlacemap. Used by the disk controller tooptimize track layout for access time.

ERRPTR — bytes 488-490 — pointer to a sectorcontaining the list of sectors in errorafter the initial format.

BTPTR — bytes 491-493 — pointer to the descriptorrecord for the bootstrap file. Used by thebootstrap process to avoid a directory search,

The remainder of the sector is reserved for future use.

7.4.2 DPS ALLOCATION ALGORITHM

FREEfO] is a pointer to a sector whose contents are addressesof the next 100 elements of the free chain. To allocate asector, decrement NFREE, and the new sector isFREE[NFREE]. If this element is zero, then there areno sectors left. If NFREE becomes 0, then read thecontents of the designated sector into NFREE and FREE.To deallocate a sector, if NFREE is 100, copy NFREE andFREE to the deallocated sector and set NFREE to zero.Set FREE[NFREE] equal to the sector address and incrementNFREE.

- 173 -

To change disk cartridges during a session, turn therun/stop switch to stop, wait for the stop light, openthe door, remove the cartridge and insert the new one,close the door and turn the switch to run, and waittor the ready light. The door is always locked exceptwhen the scop light is on. Also, a cartridge must bein place arid the door closed to spin the disk up.

Any time there is a change in disks or a change in theready status, give an Initialize (I) command. This isnecessary to make the controller aware of the new status,

When shutting down for a period of time, as overnight,it is best to remove the cartridge and close the door,to prevent dust from gathering in either the cartridgeor the drive.

- 170 -

cylinder 0. Sector 23 will access sector 11, surface 1,cylinder 0. Sector 1000 will access sector 4, surface 1,and cylinder 41. The highest addressable sector will be9743.

The same addresses on drive 1 would access sectors in thesame relative position, but on the removable cartridgeinstead of the fixed platter.

The requests which the bare disk controller willhandle are as follows:

INITIALIZE (00) — initializes all controlsand issues a recalibrate request toeach disk. This causes each head tomove to cylinder 0.

READ BINARY (OAH) — transfers data fromthe disk starting at the requestedsector until the byte count issatisfied, then continues to theend of the sector. The sectorheaders are not transferred.

WRITE BINARY (OEH) — transfers data to therequested sector. The sectorheader of the sector precedingthe selected one is read andchecked for consistency before thesector is written. The first tenbytes of the data transfer area arethe backward pointer, the forwardpointer, and the file ID of thesector. They will be written inthe sector header, not in the dataarea. Because of the necessity toprovide a new set of pointers andfile ID for each subsequent sector,only one sector can be written ata t itne.

- 175 -

7.4 DPS ALLOCATION

7.4.1 SECTOR 0 FORMAT

As opposed to the floppy-disk system, which uses a RAM bit map,allocation is maintained as a list of free sectors. The firstpart of this list, plus the volume ID (Disk ID) andstatistics on disk usage, are maintained on sector 0of each unit. The format of that sector is as follows:

VOLUME ID — bytes 1-100

MAXSIZ — bytes 101-103 — the total numberof sectors on that unit, and thus1 more than the highest accessiblesector address.

MAXID — bytes 104-107 — the current highestfile ID. This is incremented every timea new file is created.

ROOTPT — bytes 108-110 — the pointer to theroot directory descriptor for the unit.

TFREE — bytes 111-113 — the total number ofsectors remaining on the free list.

NERR — bytes 114-116 — the number of sectorsunusable because of errors. This isgenerated during the read pass of theformat routine.

<NUSED — bytes 117-119 — total number of

sectors on the unit which have beenallocated.

NFREE — bytes 120-121 — an index into thefree array to follow.

FREE — bytes 122-421 — an array of 1003-byte pointers, each to anunallocated sector.

FMOD — byte 422 — internal use.

- 172 -

7.6 CONTROLLER BOOTSTRAP OPERATION

The bootstrap of the controller occurs after the system isreset. At reset time a flag is set indicating that thecontroller is awaiting bootstrap; any request from thehost system prior to controller bootstrap is answered byreturning with a device not ready (Error C2) completioncode.

All control variables and control ports are initialized.At this time, if drive 1 is ready, the reading of thebootstrap starts. If it is not ready, the STATUS PIO isset up to give an interrupt when drive 1 becomes ready,and transfer is made up to the wait-for-request loop.When the interrupt signals that drive 1 has entered theready state, the reading of the bootstrap starts.

When reading the bootstrap, interrupts from the SIO aredisabled to prevent any interference with the disk operation.Any request messages received during this time are ignored,causing them to be repeated until they are acknowledged.

The first step in reading the bootstrap is to read sector 0of drive 1 (the removable cartridge) into a buffer. (If anerror occurs at any point in reading the bootstrap fromdrive 1, the process is repeated on drive 0.) A variablein block 0, BTPTR, gives a pointer to the descriptor recordof the bootstrap file. If this pointer is null, thebootstrap fails on drive 1, and bootstrap from drive 0 isinitiated.

This descriptor record is read into the buffer. For eachsegment listed in the descriptor record, successive datarecords are read into a buffer and transferred to thecorrect address in the controller memory. As each datarecord is read in, its back pointer is checked againstthe address of the previous record. Any failure to comparecauses failure of the bootstrap read on that drive.

When the last segment has been completely read, the flagis cleared indicating that the bootstrap has completed. Thestarting address from the descriptor is placed in a variablefor indirect jumping on receipt of a DPS request.

- 177 -

7.5 THE BARE DISK CONTROLLER

The bare disk controller is analogous to the subroutineFLOPPY in floppy-disk based systems. It accepts astandard RIO vector and reads or writes a sector ofthe disk. It accepts only a very limited set ofrequests, and requires a supplemental parameter vectorspecifying the disk address of the sector and thedisk drive to be accessed. The drive is specified inthe most significant three bits of the 3-bytedisk address. The sectors are addressed by3-byte integers. Sector 0 is cylinder 0, surface 0,sector 0. Since disks with various numbers of sectorsper track, various numbers of surfaces, and variousnumbers of cylinders can all be used with the same interface,it is difficult to say on what cylinder, surface, andsector any given sector address would lie, or what thehighest sector address is. However, with increasingsector address, the sector number varies most rapidly,then the surface, then the cylinder.

On drives which have one or more fixed platters and oneremovable platter, the removable platter is consideredto be a different physical drive than, and thus to havea different sector address space from, the fixedplatter or platters. If there are four drives on acontroller, the fixed platters on them will bereferenced as drives 0, 2, 4, and 6. It is notnecessary that any drive have a removable platter, butif it does, the removable platter is referenced asdrive n+1, where n is the drive by which the fixedplatter is referenced. It is also not necessary thatmultiple drives be of the same configuration; i.e.,the drives need not be in fixed-removable platter pairs.

The typical installation will have a single drive withone fixed platter, one removable platter, 12 sectorsper track and 406 tracks, and will be connected asdrive 0. This means that drive 0, sector 0 will addresssector 0, surface 0, and cylinder 0 of the fixedplatter. Sector 1 will access sector 1, surface 0,cylinder 0. Sector 12 will access sector 0, surface 1,

- 174 -

7.7 SYSTEM BOOTSTRAPPING on the MCZ-1/35

Since the entire file system is available in ROM at bootstraptime, bootstrapping consists of issuing I/O requests to DPS,as follows:

1) Initialize2) Open named file */OS for input, returning all

attributes3) For each segment, issuing read binary requests

for the data address and data length indicatedin the segment table.

4) Close file

and jumping to the entry point given by the attributes.

- 179 -

READ HEADER (32H) — The 24 bytes of thesector header of the requested sectorare transferred back to the user.These are as follows:

byte 1 — flag byte, always 80Hbyte 2 -- cylinder address, low orderbyte 3 — cylinder address, high orderbyte 4 -- surfacebyte 5 — sectorbyte 6-8 — backward pointerbyte 9-11 — forward pointerbyte 12-13 — data length, always 200Hbyte 14-17 — file IDbyte 18-19 — header CRCbyte 20-24 — zero

WRITE WITHOUT PRECHECK (34H) -- performsexactly as a write request, but skipsthe check of the header of thepreceding sector. This permitsinitial formatting of the disk as wellas repair of a damaged format.

- 176 -

APPENDIX A

RIO/ZDOS/DFS ERROR CODES

RIO

Completion Code

404142434445464748494A4B4C

Meaning

Invalid Drive NameInvalid or Inactive DeviceInvalid UnitMemory Protect ViolationMissing or Invalid Operand(s)System ErrorIllegal File NameNon-existent CommandIllegal File TypeProgram AbortInsufficient MemoryMissing or Invalid File PropertiesI/O Error (IY->Vector)

ZDOS/DFS

Completion Code

8081828384ClC2C3C4C5C6C7C9CACBCCwwwCDCECF

Meaning

Operation CompleteDirectory Format ErrorScratch File CreatedFile Name TruncatedAttribute List TruncatedInvalid Operation (Request)Device Is Not ReadyWrite ProtectionSector Address ErrorSeek ErrorData Transfer ErrorFile Not FoundEnd of File ErrorPointer Check ErrorFile Not Open

Unit Already Active (Open)Assign Buffer FullInvalid Drive SpecificationLogical Unit Table Full (>16 Open)

A-l

Should the bootstrap read from drive 1 fail to completefor any reason (disk error or failure of a required condition),the entire process will be repeated on drive 0. Should italso fail on drive 0, it will again try drive 1, continuingto alternate between drives until the condition correctsitself or the operator turns off the disk.

- 178 -

APPENDIX B

RIO COMMAND SYNTAX SUMMARY

NAME

ACTIVATE

Allocate

Brief

CAT

Close

COMPARE

COPY

COPY. DISK

COPYSD

DATE

DEACTIVATE

DEAllocate

Debug

DEFINE

PARAMETERS

device name [address]

low boundary high boundaryblock size

(match_string I T=type I P=propsD=drive 1 F=format |L=listing disposition I DATE rel1 CDATE rel date)*

u|*

fileJL file_2

file 1 file 2 (A | U 1 0 |RL=record length i T=type) *

[s_drive TO d_drive] [V]

f ile_name

[yymmdd]

device name

block address block_size

(unit file name 1 unit

REFERENCE

5.1

5.2

5.3

1 5.4

date

5.5

5.6

5.7

5.8

5.9

5.10

5.11

5.12

5.13

5.14

DELETE

DISK.FORMAT

device_name I unit * I *)+[A | 0 | U | I | NF | NO](match_string | T=type IP=props I D=drive | Q=query IDATE rel date I CDATE rel date)*

(S I D=driveQ=query)*

ID='disk name1

5.15

5.16

B-l

RENAME

RESTOREJTABS

SAVEJTABS

SET

STATUS

Verbose

Xeq

(oldfile newfile Idevicerdrive ID="new_disk_name')*

file_name

file_name

(CHRDEL=c I LINDEL=c I NULLCT=n ISPEED=nn | LFCNT=n | TABSIZE=n IECHO ON | ECHO OFF |AUTOLF ON | AUTOLF OFF IPROPERTIES OF file_name TO pi1st ITYPE OF file name TO type ISUBTYPE OF fTle_name TO subtype IENTRY_POINT OF file_name TO nn |LOW_ADDRESS OF file_name TO |HIGH_ADDRESS OF file_name TO ISTACK_SIZE OF file_name TO nn IBYTE_COUNT OF file_name TO nn)*

[Oil ... 6|7]

[* | nn [parameter_list]]

expression

5.36

5.37

5.38

5.39

5.40

5.41

5.42

5.43

B-3

DODlD2D3D4

D5D6D7D8

D9DA

Duplicate FileDiskette ID ErrorInvalid AttributesDisk Is FullFile Not Found in Proper DirectoryRecordBeginning of File ErrorFile Already Open on Other UnitInvalid Rename to Scratch FileFile Locked (Attempt to ChangeAttributes)Invalid Open RequestInsufficient Memory forAllocation Maps

A-2

APPENDIX C

RIO SYSTEM CONSTANTS

The following are the current values of RIO symbols.In some cases, however, address values vary from thoselisted below. To be certain you are using the valuesappropriate to your system, check the NOTE.TO.USER fileon your system disk.

Symbol

ERKFLGBRKRTNCHRDELCONIBFCONIVCCONOBFCONOVCDATEDEBUGDISKENTRYERCODEEXTRETFLOPPYINITIALIZATION

COMMAND AREAINPTRINTERRUPT VECTORLINDELMEMMGRNULLCTOUTPTRPROMPTPCONSYSFLGSYSTEMSYSTEM REENTRY

POINT

MCZ Address

13CD13CE13CC118912931103128813ABOBFAOBFD17DE13BD13BEOBFD

18DF13C4130013CB140913C813C613CAOBE8140E1403

1400

ZDS Address

OFC4OFC5OFC3OD8AOECEOD04OEC3OFA2OBFAOBFD13DEOFB4OFB5OBFD

14DFOFBBOFOOOFC21009OFBFOFBDOFC1OBEE100E1003

1000

C-l

DISK.REPAIR

DISK.STATUS

DISPLAY

DO

DUMP

ECHO

ERROR

ERRORS

EXTRACT

Force

FORMAT

HELP

IMAGE

Initialize

LADT

MASTER

MOVE

DFS_drive_number level_number

[Oil ... 6|7]

command_file [parameter list]

file_name [m[n]]

string

[error_codeI*]

file_name

command parameter_list

(S I D=drive I ID='disk_name' IQ=query)*

(key_word|*)*

file_name (first_locationlast_location)+ [E=entry point][RL=record length] [ST=stack size]

[device_name] [parameter list]]

[device_name]

(match_string I T=type I P=props IF=format I D=destination_device IS=source_device IL=listing_disposition I Q=query IDATE rel date I CDATE rel date)*tion | Q=query | DATE rel date I CDATErel date)*

5.17

5.18

5.19

5.20

5.21

5.22

5.23

5.24

5.25

5.26

5.27

5.28

5.29

5.30

5.31

5.32

5.33

PAUSE

Release

5.34

5.35

B-2

APPENDIX D

CONVERTING FILES TO RIO FORMAT

Files which have been created by MCZ or ZDS 2.1 Systemsoftware (hereafter reference is made only to OS 2.1) arenot compatible with RIO format. File conversion can beeffected in two ways: a series of RIO commands can convertone or more files, or a Zilog utility program can be usedwhich converts all files on a given diskette. In eithercase, the conversion is non-destructive, that is, theconverted file always resides on a second disk, leaving theOS 2.1 type disk unaffected.

To manually convert one or more files to RIO format, enterthe following command sequence:

%ACTIVATE $ZDOSI ;Activates the OS 2.1 ZDOS emulator%COPY, ;Load, but do not execute, COPY

At this point, the diskette containing the file or filesto be converted is inserted in one drive and the formattedRIO diskette on which the converted file is to reside isinserted in another. For this example, drive 2 has the RIOdiskette, and drive 0 has the OS 2.1 type diskette.

%I;I $ZDOSI ;Initialize the disk allocation maps%XEQ * $ZDOSI:0/TEMP.S 2/TEMP.S

The above two commands may be repeated as necessary. TheINITIALIZE command need be executed only when the diskettesare changed. The last command causes execution of the lastloaded file, which in this case is COPY. (If a formattedRIO disk was in drive 0 with the COPY command on it, theuser can alternatively enter 'COPY..!.) The firstparameter is the source file name; note that it will alwaysbe qualified with '$ZDOSI' indicating that the OS 2.1 ZDOSemulator (ZDOSI) is the device on which the file exists.The second parameter is the destination file name, whichdoes not have to be the same as the source file name; it may

D-l

APPENDIX E

ALTERING DEFAULT RIO

The file OS contains the resident RIO programs plus thedefault system console driver. Altering the file consistsof GETting OS from the 3K Monitor, making the desiredmodifications and SAVing it. The examples will use MCZaddresses; for ZDS addresses, refer to Appendix C.

Example 1: MODIFY SYSTEM FLAG TO INHIBIT EXTERNALINITIALIZATION

%SET PROPERTIES OF 0/OS TO * ;remove write protectionfrom file OS

%D ;enter 3K Monitor Debugger>GET 0/OS ;load file OS from drive 0>D 140E ;display and modify SYSFLG140E 04 0 Q ;turn off EXTERNAL

INITIALIZATION FLAG>SAV 0/OS 1400 2BFF E=17DE RL=400

;save new OS>OS ;bootstrap new OSRIO%SET PROPERTIES OF 0/OS to SW ;restore protection to file OS

Example 2: MODIFY SYSTEM EXTERNAL INITIALIZATION COMMAND AREATO EXECUTE THE COMMAND 'BASIC1 (ONLY) ON EXTERNALINITIALIZATION

%SET PROPERTIES OF 0/OS TO * ;remove write protection%D>GET 0/OS>D 140E

140E 00 4 Q>D 18DF

18DF 4418EO18E118E218E3

424F 4120 5330 492F 43

;enter 3K Monitor Debugger;load file OS from drive 0;turn on external initializationflag

;display and open initializationmessage area;Change to 'B1

; 'A1

E-l

APPENDIX F

I/O REQUEST VECTOR FORMAT

and

I/O REQUEST CODES

I/O Request Vector Format

Byte Contents

0 Logical Unit Number1 Request Code2-3 Data Transfer Address4-5 Data Length6-7 Completion Address8-9 Error Return AddressA Completion CodeB-C Supplemental Parameter

Vector Address

ZDOS/DFS Supplemental Parameter Vector

0 Flag Byte (ASSIGN),Open Type (OPEN)

1 Drive Designation2 File Name Length3 File Name

I/O Request Codes

0 Initialize2 Assign4 Open6 Close8 RewindA Read Binary

F-l

or may not be qualified with '$ZDOS' as long as ZDOS is themaster device.

After file conversion and verification of conversionis concluded, the following command will free thememory occupied by ZDOSI.

%DEACTIVATE $ZDOSI jRemove ZDOSI from Active Device Table

Alternatively, all files on a diskette may be convertedusing the utility program CONVERT. Execution of thatcommand results in the prompt message,

INSERT DISKS (OLD DISK IN DRIVE 2, FORMATTED RIO DISKIN DRIVE 0)TYPE RETURN (OR 'Q1 TO TERMINATE)

The OS 2.1 diskette is inserted into drive 2 and the RIOdiskette is inserted into drive 0, after which carriagereturn (or 'Q' to abort) is entered. The names of thenew RIO files will be the OS 2.1 type name concatenatedwith the file type as an extension. For example, the 'C'type file 'ABC' would be named 'ABC.C' on the RIO diskette.There is no provision to rename files as they are converted.

After all files on the OS 2.1 diskette are converted, theprompt message is repeated, at which time diskettes maybe changed.

D-2

APPENDIX G

PROGRAM EXAMPLES

Following are sample programs which the user is encouragedto edit, assemble, link, and execute. They illustratesome of the concepts introduced in previous sections,including console I/O, parameter string processing, andfile I/O.

In each case the following commands may be used to edit,assemble, and link the example program:

%EDIT filename.SEDIT 1.6NEW FILEINPUT

;invoke the editor;the file does not already;exist, so it is created;editor automatically enters;input mode

>QUIT%ASM filename (X)ASM 5.7PASS 1 COMPLETE0 ASSEMBLY ERRORSASSEMBLY COMPLETE%LINK $=4400 PRINTLINK 1.5LINK COMPLETE

;assemble (w/cross reference option)

;and link

All system addresses are given for MCZ.Appendix C for ZDS equivalents.

Refer to

6-1

18E4 4F OD Q ;carriage return and quit>SAV 0/OS 1400 2BFF E=17DE RL=400

;save new OS>OS ;bootstrapping at this point

will result in executionof the file BASIC

E-2

SYMBOL VAL M DEFN REFS

AVLUNAVREQCONOUTLMSGMSGSYSTEMWRTLIN

0008000900020024001314030010

RR

R

11122430282325

111513612

30

G-3

C Read LineE Write Binary10 Write Line12 Write Current14 Write Direct16 Delete18 Delete Remaining1A Erase File1C Read and DeleteIE Read Current20 Read Previous22 Read Direct24 Skip Forward26 Skip Backward28 Skip to End2A Rename2C Update2E Set Attributes30 Query Attributes40 Read Status42 Write Status44 Deactivate

F-2

LOG OBJ CODE M STMT SOURCE STATEMENT ASM 5.7

00340036

000000

0037

45464748495051525354555657

AVERA:AVCC:

SYSTEM:CONOUT:WRTLIN:

INPTR:

BUFFER:

DEFWDEFB

EQUEQUEQU

EQU

DBFSEND

00

1403H210H

13C4H

80

;ADDRESS;ERROR RETURN ADDRESSCOMPLETION CODE

;SYSTEM ENTRY POINT;CONSOLE OUTPUT UNIT;WRITE LINE REQUEST; CODE;PARAMETER LIST POINTER

CROSS REFERENCESYMBOL VAL M DEFN REFS

EXAMPLE2.MCZ

ADDCHRAVCCAVCRAAVDLAVDTAAVECAVERAAVLUNAVREQBUFFERCONOUTINPTRSCANSYSTEMWRTLIN

0016003600320030002E002C0034002C002D0037000213C4000914030010

RRRRRRRRRR

R

204744434239464041565154105052

13

31

33

7405

183441

15

42

6-5

LOGEXAMPLE1.MCZ

OBJ CODE M STMT SOURCE STATEMENT ASM 5.7

000000040007

00080009OOOA

OOOCOOOE

00100012

00130036

FD210800 RCD0314C9

02101300 R

24000000

000000

454E4F52OD

123456789

1011121314151617181920212223242526272829303132

; EXAMPLE 1 -

AVEC:AVLUN :AVREQ:AVDTA :

AVDL:AVCRA:

AVERA:AVCC:

LDCALLRET

DEFBDEFBDEFW

DEFWDEFW

DEFWDEFB

; EQUATES AND

SYSTEM:CONOUT:WRTLIN:

MSG:

LMSG:

EQUEQUEQU

DEFMDEFBEQU

END

— MAKE A i

I Y, AVECSYSTEM

CONOUTWRTLINMSG

LMSG0

00

CONSTANTS

1403H210H

1 ENORMOODH$-MSG

; IY -> I/O VECTOR

LOGICAL UNIT NUMBERREQUEST CODEDATA TRANSFERADDRESSBYTE COUNTCOMPLETION RETURNADDRESSERROR RETURN ADDRESSCOMPLETION CODE

; SYSTEM ENTRY POINT; CONSOLE OUTPUT UNIT; WRITE LINE REQUEST; CODE

ENORMOUS CHANGES AT THE LAST MINUTE1


AVCCAVCRAAVDLAVDTAAVECAVERA

0012 ROOOE ROOOC ROOOA R0008 R0010 R

191615131018

EXAMPLE1.MCZ

G-2


004100440047004A004D00500052

00550058005A005C005E00600063

00660068006B006E0071007400760077

0079

007B007E

008000830084008500860089

225101210100225301CD03143A5901CB77C2D700

3A7F01E6FOFE2028083E4832BD13C3F900

3EOO21000011FFFF01FFFFCD0914OEOO78E6FO

2009

CDF9003E4A

32BD13C947AFCD0914224B01

R 4546

R 4748

R 4950

R 515253545556

R 575859606162

R 636465666768697071727374757677787980

R 81828384858687888990

R 91

LDLDLDCALLLDBITJP

;FILE IS OPEN

LDANDCPJRLDLDJP

(AVDTA) ,HLHL,LASV(AVDL) ,HLSYSTEMA, (AVCC)6, ANZ, ERROR

TEST FILE TYPE,

A, (ASVFT)OFOHASCIIZ,PRT100A,ILLFT(ERCODE) ,ACLOSEF

COMPLETION CODE; ERRORS?

COPY TO SYSLST

;FILE TYPE; STRIP SUBTYPE;BETTER BE ASCII

;OR ILLEGAL FILE TYPE

;FILE IS OF TYPE ASCII

PRT100:LDLDLDLDCALLLDLDAND

JR

CALLLD

LDRET

GETIT: LDXORCALLLD

A,0HL,0DE,-1BC,-1MEMMGRC,0A,BOFOH

NZ, GETIT

CLOSEFA,INSMEM

(ERCODE) ,A

B,AAMEMMGR(BUFFER) ,HL

;ALLOCATE

; LOCATE LONGEST BUFFE

;SEE IF AVAILABLE;SPACE >= 1000H;IF SO, ALLOCATE;IT

; OTHERWISE, OUTPUTjINSUFF. MEM. ERROR,;CLOSE FILE AND; RETURN

;SAVE BEGINNING

LOGEXAMPLE2.MCZ


0000

0003

00060009

OOOAOOOCOOOE00100012

0014

001600170019

001A001B001C001D001E001F

0020

00240028

002B

002C002D002E00300032

2AC413

113700 R

0100007E

FE3B2808FEOD2804EDAO

18F3

EB360DOB

792F4F2F4703

ED433000 R

FD212COO RCD0314

C9

02103700 R00000000

123456789

1011121314151617181920212223242526272829303132333435363738394041424344

; EXAMPLE 2/

/

LD

LD

LDSCAN: LD

CPJRCPJRLDI

JR

ADDCHR: EXLDDEC

LDCPLLDCPLLDINC

LD

LDCALL

RET

AVEC:AVLUN: DEFBAVREQ: DEFBAVDTA: DEFWAVDL: DEFWAVCRA: DEFW

MAKE A SYS1STRING TO

HL, (INPTR)

DE, BUFFER

BC,0A, (HL)

1 . 1/

Z , ADDCHRODHZ, ADDCHR

SCAN

DE,HL(HL) ,ODHBC

A,C

C,A

B,ABC

(AVDL) ,BC

I Y, AVECSYSTEM

CONOUTWRTLINBUFFER00

;ADDRESS OF THE;PARAMETER LIST;MOVE PARAMETER LIST;INTO BUFFER;KEEP A CHARACTER COUNT;NEXT CHARACTER IN;PARAMETER STRING;TEST FOR END

;MOVE CHARACTER AND INC;POINTERS

;COULD HAVE BEEN A

;GET STRING LENGTH

;DATA LENGTH

;MAKE THE SYSTEM CALL;TO WRITE IT

;CONSOLE OUTPUT;WRITE LINE;DATA TRANSFER ADDRESS;DATA LENGTHCOMPLETION RETURN

G-4


OOCB

OOCC

OOCE

OODO

OOD3OOD5

OOD7OOD9OODCOODEOOE1

OOE4OOE7

OOEAOOEDOOFOOOFSOOF6

OOF9OOFBOOFE010001030106

0109010C010F

Fl

FEC9

2829

3A5901

CB7728CO

3EOE3250013E02324F01214801

3A5901CD2401

213E01225101210DOO225301CD0314

3E063250013E04324F01210000225101

225301225A01CD0314

R

R

RR

RR

RR

R

R

R

R

RR

139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184

POP

CP

JR

LD

BITJR

;AN ERROR HAS

AF

EOF

Z, CLOSEF

A, (AVCC)

6, AZ,READ

OCCURRED, PRINT; MESSAGE, CLOSE FILE, AND RETURN

ERROR: LDLDLDLDLD

LDCALL

LDLDLDLDCALL

CLOSEF: LDLDLDLDLDLD

LDLDCALL

A,WRTBIN(AVREQ) ,AA,CONOUT(AVLUN) ,AHL,EMSGN

A, (AVCC)BTOHEX

HL,EMSG(AVDTA) ,HLHL,LEMSG(AVDL) ,HLSYSTEM

A, CLOSE(AVREQ) ,AA, 4(AVLUN) ,AHL,0(AVDTA) ,HL

(AVDL) ,HL(AVSVP) ,HLSYSTEM

;RESTORE READCOMPLETION CODE;DID LAST READ REQUEST;REACH END OF FILE?

;HAS WRITTEN;SUCCESSFULLY?

;WRITE BINARY

;TO CONSOLE OUTPUT UNIT

;CONVERT ERROR CODE TO;ASCII

;PRINT MESSAGE

;CLOSE FILE

;ON UNIT FOUR

;DON'T UPDATE;DESCRIPTOR RECORD

DEALLOCATE THE;ALLOCATED SPACE

185

G-9

LOGEXAMPLES.MCZ


0000000200050007OOOAOOOBOOOE

00110014

0017001A

001D

002000240027002A002C

002F0031003400360039

003B003E

3E023250013E04324F01AF325C012AC413

225101215C01

225A01210000

225701

FD214F01CD03143A5901CB77C2D700

3E043250013EOO325C013EFF

325E01217F01

R

R

R

RR

R

R

R

R

R

R

R

RR

123456789

1011121314151617181920212223242526272829303132333435363738394041424344

;PROGRAM 3 — PRINT — COPY AN ASCII FILE TO SYSLST

;MAKE A SYSTEM CALL TO FORMAT;VECTOR

LDLDLDLDXORLDLD

LDLD

LDLD

A, ASSIGN(AVREQ) ,AA, 4(AVLUN) ,AA(SPVFB) ,AHL, (INPTR)

(AVDTA) ,HLHL,SPV

(AVSVP) ,HLHL,0

LD

LDCALLLDBITJP

(AVERA),HL

IY,AVECSYSTEMA,(AVCC)6,ANZ, ERROR

SUPPLEMENTAL PARAMETEF

;ASSIGN REQUEST

;ON UNIT 4

/•PARAMETER STRING;ADDRESS

;-> SUPPLEMENTAL;PARAMETER VECTOR

;CLEAR ERROR RETURN;ADDRESS;FOR NORMAL ERROR;RETURN

COMPLETION CODE;ERROR

;OPEN THE FILE AND TEST FILE TYPE

LDLDLDLDLD

LDLD

A, OPEN(AVREQ),AA,OPNINP(SPVOR),A

(SPVFNL),AHL/ASVFT

;OPEN REQUEST

;FOR INPUT

;UNIT PREVIOUSLY/•ASSIGNED

;REQUEST SOME OF THE/•DESCRIPTOR RECORD

6-6


013E0148014A

014B014D

014F0150015101530155

01570159015A

492F4F20

OD

0000

233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279

RDBIN:WRTBIN:WRTLIN:ASSIGN:OPEN:CLOSE:

OPNINP:

EOF:ILLFT:

INSMEM:

ASCII:

EQUEQUEQUEQUEQUEQU

EQU

EQUEQU

EQU

EQU

OAHOEH10H246

0

OC9H48H

4AH

2 OH

;RIO ADDRESSES

INPTR:

ERCODE:SYSTEM:MEMMGR:

EMSG:EMSGN:

LEMSG:

BUFFER:BUFSIZ:

AVEC:AVLUN :AVREQ:AVDTA :AVDL:AVCRA:

AVERA:AVCC:AVSVP :

SPV:

EQU

EQUEQUEQU

DEFMDBFSDEFBEQU

DEFWDBFS

DBFSDBFSDBFSDBFSDBFS

DBFSDBFSDBFS

13C4H

13BDH1403H1409H

'I/O2ODH$-EMS(

02

11222

212

;READ BINARY;WRITE BINARY;WRITE LINE;ASSIGN;OPEN; CLOSE

;OPEN TYPE: OPEN FOR;INPUT;EOF ERROR CODE;RIO ERROR CODE -;ILLEGAL FILE TYPE;RIO ERROR CODE -INSUFFICIENT MEMORY;ASCII FILE TYPE

;PARAMETER STRING;POINTER;ERROR CODE LOCATION;SYSTEM CALL ADDRESS;MEMORY MANAGER ADDRESS

;ADD A CARRIAGE RETURN

;READ/WRITE BUFFER

;LOGICAL UNIT NUMBER;REQUEST CODE;DATA TRANSFER ADDRESS;DATA LENGTHCOMPLETION RETURN;ADDRESS;ERROR RETURN ADDRESSCOMPLETION CODESUPPLEMENTAL PARAMETER;VECTOR POINTER

;THE SUPPLEMENTAL

G-ll


008C

0090

0093

00970099009C009EOOA1OOA5OOA8OOABOOADOOAF

OOB1OOB3OOB6

OOB7OOB8

OOBAODBCOOBFOOC1OOC4OOC7

OOC8

ED434D01 R

225101 R

ED435301 R

3EOA325001 R3E04324F01 RFD214F01 RCD03143A5901 RCB77280BFEC9

20242A5301 R7C

B5283F

3EOE325001 R3E03324F01 R3A5901 RF5

CD0314

9293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138

LD

LD

LD

(BUFSIZ) ,BC

(AVDTA) ,HL

(AVDL) ,BC

;READ NEXT BUFFER LOAD

READ : LDLDLDLDLDCALLLDBITJRCP

JRLDLD

ORJR

;WRITE A BUFFER

WRITE: LDLDLDLDLDPUSH

CALL

A,RDBIN(AVREQ) ,Aft, 4(AVLUN) ,AIY,AVECSYSTEMA,(AVCC)6, AZ, WRITEEOF

NZ, ERRORHL, (AVDL)A,H

LZ,CLOSEF

LOAD TO SYSLST

A,WRTBIN(AVREQ) ,AA, SYSLST(AVLUN) ,AA, (AVCC)AF

SYSTEM

;ADDRESS;SAVE SIZE OF BUFFER

INITIALIZE DATA;TRANSFER ADDRESS;LOAD BUFFER SIZE

;READ BINARY

;FROM UNIT 4

;READ ERROR?

;YES, HAS IT AN END;OF FILE?

;YES, ANY DATATRANSFERRED?

;IF NOT, CLOSE FILE

;WRITE BINARY

;ON SYSLST

;SAVE COMPLETION CODE

;DATA TRANSFER ADDRESS;AND DATA LENGTH WERE;SET BY THE READ;OPERATION

G-8

SYMBOL VAL M DEFN REFS

HBTHEXILLFTINPTRINSMEMLASVLEMSGMEMMGROPENOPNINPPRT100RDBINREADSPVSPVDRVSPVFBSPVFNSPVFNLSPVORSYSLSTSYSTEMWRITEWRTBINWRTLIN

0132004813C4004A0001OOOD1409000400000066OOOA0097015C015D015C015F015E015C00031403OOBAOOOE0010

R

R

RRRRRRR

R

21724425324629326225723824169234103279284282286285281228256125235236

20561168246

1677436386010314919

15

423912727

111125

209

90

48

156

191

108 137 169 181

6-13


01120115011601170119011D0120

0123

012401250126012701280129

012C012D012E

0131

0132

013401360138013A013C013D

2A4B01 R7CB43E01ED4B4D01 RC4091432BD13

C9

F5IFIFIFIFCD3201 R

Fl23CD3201 R

C9

E60F

FEOA3802C607C63077C9

186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232

186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232

LDLDORLDLDCALLLD

RET

;B T 0 H E X*t

BTOHEX: PUSHRRARRARRARRACALL

POPINCCALL

RET

;H B T H E X•t

HBTHEX: AND

CPJRADD

HB10: ADDLDRET

CONOUT: EQUSYSLST: EQU

;I/0 REQUEST

HIAHAB<N:0

_____ (

sr

A:

HI

A!H]HI

i01

Oi

1cAA(1

23

CODE;

HL,(BUFFER)A,HHA,lBC, (BUFSIZ)NZ,MEMMGR(ERCODE),A

;WAS BUFFER ALLOCATED?

DEALLOCATE

CONVERT 8 BITS OF REG A TO HEX ASCII,STORE AT (HL)

;SAVE A

HBTHEX

HBTHEX

;CONVERT HIGH ORDER;4 BITS;RESTORE A

;CONVERT LOW ORDER 4;BITS

CONVERT 4-BIT BINARY LOW ORDER 4 BITSOF REG A TO HEX ASCII CHARACTER AT (HL)

;MASK OFF LOW ORDER 4;BITS;DECIMAL CHARACTER?

C,HB10A,7A,30H(HL),A

;NO

;CONSOLE OUTPUT UNIT;SYSTEM VOLUME OUTPUT;UNIT

G-10

APPENDIX H

INTERNAL COMMAND TABLE CONTENTS

DebugInitializeBriefVerboseXeqAllocateDEAllocateReleaseForceClose: (expression evaluation)

H-l


015C

015D015E015F

017F

280281282283284285286287288289290291292293294295

SPVOR:SPVFB: DBFS

SPVDRV: DBFSSPVFNL: DBFSSPVFN: DBFS

;AREA IN WHICH;FILE OPEN

ASVFT: DBFSLASV: EQU

END

1

1132

TO MOVE THE

1$ -ASVFT

; PARAMETER VECTOR;OPEN REQUEST TYPE; ASSIGN REQUEST FLA<;BYTE; DRIVE DESIGNATION;FILE NAME LENGTH;FILE NAME

DESCRIPTOR RECORD ON THE


EXAMPLES.MCZ

ASCIIASSIGNASVFTAVCCAVCRAAVDLAVDTAAVECAVERAAVLUNAVREQAVSVPBTOHEXBUFFERBUFSIZCLOSECLOSEFCONOUTEMSGEMSGNEOFERCODEERRORGETITHB10

00200002017F0159015501530151014F0157014F0150015A0124014B014D0006OOF90002013E0148OOC913BDOOD70084013A

RRRRRRRRRRRRR

R

RR

RRR

24823729227527227127026727426826927620026426523917222725926024325515688222

59104328

47182624131121

163919317263158165160112623079220

5749

9745107

10637180

186190

81

262

1418651

293109 129 146 162

115 168 17995 166 177

128 159 175104 126 157 173

119 143

192114

6-12

APPENDIX I

RIO MEMORY MANAGER

This appendix describes register contents before and aftera MEMMGR call. Appendix C has the MCZ and ZDS addressesof MEMMGR. Example 3 of Appendix G includes calls toMEMMGR to allocate and deallocate buffer space.

ALLOCATE

Before MEMMGR CALL:A=0 (allocate)

HL = lower address boundaryDE = upper address boundaryBC = required size (bytes)

After MEMMGR CALL:A=80 (operation complete)

HL = beginning address of holeDE = ending address of holeBC = size of hole (bytes)

A=4A (insufficient memory)HL = beginning of largest hole within boundariesBC = size of largest hole within boundaries (bytes)

(if BC=0, then HL=undefined)

DEALLOCATE

Before MEMMGR CALL:A=l (deallocate)

HL = beginning address of holeBC = hole size (bytes)

After MEMMGR CALL:A=80 (operation complete)A=43 (not all blocks in area were allocated)

1-1

APPENDIX J

DESCRIPTOR RECORD OF PROCEDURE TYPE FILE

Byte #

0..3 : Reserved for future expansion

4..5 : File ID - currently unused

6..7 : Pointer to directory sectorholding entry for this file

8..9 : Pointer to first data record of file

10..11 : Pointer to last data record of file

12 : Type of file - see description underthe OPEN request

13..14 : Record count

15..16 : Record length

17..18 : Block length - currently unused,and set to be same as record length

19 : Protection properties - seedescription in OPEN request

20..21 : Starting execution address forprocedure files

22..23 : Number of bytes in the last recordof the file

24..31 : Date of creation

32..39 : Date last written

J-l

APPENDIX K

ZDOS/DFS COMMAND SUMMARY

Name Request Code Ref

ASSIGN 02,03 6.2CLOSE 06,07w 6.4DELETE 16,17 6.9DELETE REMAINING RECORDS 18,19 6.10ERASE 1A,]B 6.11INITIALIZE 00,01 6.1OPEN 04,05 6.3QUERY ATTRIBUTES 30,31 6.22READ AND DELETE 1C,ID 6.12READ BINARY OA,OB 6.6READ CURRENT IE,IF 6.13READ DIRECT 22,23 6.15READ PREVIOUS 20,21 6.14RENAME 2A,2B 6.19REWIND 08,09 6.5SET ATTRIBUTES 2E,2F 6.21SKIP BACKWARD 26,27 6.17SKIP FORWARD 24,25 6.16SKIP TO END 28,29 6.18UPDATE 2C,2D 6.20WRITE BINARY OE,OF 6.7WRITE CURRENT 12,13 6.8

K-l

APPENDIX L

RELINKING RIO COMMANDS

Most RIO commands are linked to execute at the lowestavailable memory. Those which may be expected to beloaded concurrently under some circumstances (i.e.,when executed from DO) are linked elsewhere. The objectfiles for these commands (listed below) are provided onthe system disk in order that they may be relinked toexecute elsewhere to fit the user's needs.

DOECHOPAUSEIMAGE

The command files RELINK.MCZ.COMMAND and RELINK.ZDS.COMMANDare on the MCZ and ZDS system disks, respectively. Thesecommand files use the specified object file and linkthe command at the specified address using system objectfiles on the system disk.

A command may be linked as follows:

DO RELINK.MCZ.COMMAND #1 #2 #3 #4 #5 #6 #7

or

where

DO RELINK.ZDS.COMMAND #1 #2 #3 #4 #5 #6 #7

#1 is the name of the command to be linked

12 is the address the command is to be linked at

#3,#4,#5,#6,#7 are the optional link parameters(see RIO Relocating Assembler and Linker User'sManual for more details).

L-l

40..40+4*n

122..123

124..125

126..127

Where n is the number of segmentdescriptors (0 <= n <= 16)Each segment descriptor is 4 bytes--the first 2 bytes are the startingaddress of the segment and thesecond 2 bytes are the length ofthe segment in bytes. After thethe last segment descriptor is anull descriptor where each of the4 bytes are zero.

Lowest segment starting address(LOW_ADDRESS)

Highest segment ending addressrounded up to the end of the record(HIGH_ADDRESS)

Stack size

J-2

fEXAMPLES

DO RELINK.MCZ.COMMAND DO OCOOO

DO RELINK.ZDS.COMMAND IMAGE OFOOO RL=400

L-2

i*

Documents

Z80-RIO OPERATING SYSTEM USER'S MANUAL · option can be issued. STATUS [0 I 1 ... engineer/programmer in Z80-based hardware/software system design. ... macro assembler, and