NEWDOS/80 v2.0 Reference - Chapters 1-3

Chapters

Library Commands

Supplied Programs

As soon as you receive your NEWDOS/80, fill out and mail the registration card. Apparat will limit its assistance and patches (zaps) to registered owners only. In your communications with Apparat, always state your name, address and your NEWDOS/80's registration number. For Version 1 of NEWDOS/80 we had many complaints of not receiving zaps from users who had not sent in the registration card. Apparat does not require the owner to agree to anything when filling out the NEWDOS/80 Version 2 registration card; just let us know who you are.

Throughout this manual certain trademarked names will be used to refer to those trademarked products. Since our printers do not have the tm symbol, we will acknowledge the trademarked names here. If we have missed rendering an acknowledgement, please forgive us as we do not mean for any trademarked name to be used to refer to anything that the trademark holder does not mean it to refer to. In some cases, such as VTOS, the primary manual for that system shows the name trademarked but does not say who it is trademarked to.

1. TRS-80 is a registered trademark of Radio Shack, Inc.

2. TRSDOS is a registered trademark of Radio Shack, Inc.

3. VTOS is a registered trademark.

4. LDOS is a registered trademark of Lobo Drives International.

5. DOUBLER is a registered trademark of Percom Data Company, Inc.

6. SCRIPSIT is a registered trademark of Radio Shack, Inc.

Almost all disk based computer systems use a Disk Operating System (known as a DOS) to provide a software interface between the user program performing disk I/O and the actual disk drives and their controllers. Usually these operating systems perform many other functions as well such as controlling what user program is executing and the allocation of disk files and file space. Believe it or not, the primary function of a DOS is to make life easier for the computer users and programmers. NEWDOS/80 is one of a number of DOSs that operate with the TRS-80; in this case only the Model I and Model III are supported.

NEWDOS/80 Version 2 is the replacement for NEWDOS/80 Version 1 that was released in June, 1980 and for NEWDOS/21 that was released in March, 1979. NEWDOS/80 Version 2 is a disk operating system designed to operate on the TRS-80 Model I and the TRS-80 Model III. A particular NEWDOS/80 Version 2 master diskette is tailored to operate on only one of the two TRS-80 models; if you wish to operate on both the Model I and the Model III, you must purchase different NEWDOS/80's for each. The TRS-80 model being used must have at least 32K of RAM and at least one 5 inch, single sided, 35 (40 for the Model III) track disk drive (mounted on drive 0). Model 1 NEWDOS/80 Version 2 is distributed on a 35 track, single sided, single density diskette, and Model III NEWDOS/80 Version 2 master diskette is distributed on a 40 track, single sided, double density diskette. You must have a disk drive capable of handling the master diskette.

NEWDOS/80 Version 2 for the Model I and NEWDOS/80 Version 2 for the Model III are mostly downward compatible with NEWDOS/80 Version 1, NEWDOS/21 and Model I TRSDOS 2.3, but it will be necessary to maintain certain programs with different copies for all four systems for incompatibilities do exist. NEWDOS/80 Version 2 is more incompatible with the Model III TRSDOS than it is with the Model I TRSDOS, and most programs and files will have to he maintained differently in the two systems. In the past, while TRSDOS was largely dormant, attempts were made to limit the incompatibilities between NEWDOS and TRSDOS, but now that TRSDOS is being actively updated more and more incompatibilities are appearing between the two systems. TRSDOS is going one way; NEWDOS/80 is going another. If this limits and eventually destroys NEWDOS's usefulness to the users, so be it. NEWDOS cannot and should not exist to be a mirror image of TRSDOS; if the user wants that, then please use TRSDOS. NEWDOS was accidentally created in the huge vacuum left by Model I TRSDOS, has always incorporated features not in TRSDOS and, in Version 2, has not implemented many of the newer features of the Model III TRSDOS. Chapter 12, sections 12.1 through 12.5 give some of the incompatibilities of NEWDOS/80 Version 2 with NEWDOS/80 Version 1 and with the Model I and III TRSDOSs.

The DOS and DISK BASIC portions of NEWDOS/80 are total rewrites from that offered in NEWDOS/21. The requirement that the user purchase TRSDOS as a precondition of use of NEWDOS/21 is not required for NEWDOS/80. It is still recommended that the user purchase TRSDOS, and NEWDOS/80 users are expected to have purchased the TRSDOS manual and be knowledgeable of its contents as use of NEWDOS/80 assumes this user knowledge. Users of the EDTASM module are still required, as a precondition of use of NEWDOS/80's EDTASM, to have purchased Radio Shack's tape editor/assembler.

Though NEWDOS/80, Version 2 was tested more extensively than Version 1, there will still be errors, and many programs will require at least a zap to work with NEWDOS/80 Version 2. Error reporting procedures are discussed in chapter 11, and the outstanding zaps are in chapter 13.

NEWDOS/80 is not a simple system. When the NEWDOS/80 user is ready to initially use NEWDOS/80, he/she should spend one to two hours studying the documentation before doing anything with the NEWDOS/80 diskette.

When ready, put a write protect tab on your NEWDOS/80 Version 2 master diskette. Then power up your computer, place the master diskette in drive 0 and press reset. The NEWDOS/80 banner should appear optionally followed by requests for date and time. If date and time are requested, please give realistic values. Next, NEWDOS/80 READY will be displayed to indicate DOS is waiting for something to do.

It is good practice to never mount on a disk drive the NEWDOS/80 master diskette except to make copies of the diskette and to very carefully apply mandatory zaps (see chapter 11). When zapping, you should first apply the zaps to a working Version 2 system diskette and test them out before applying them to the master diskette. Keep the master diskette stored away in a safe place; do not keep it in your NEWDOS/80 manual and do not use it in normal operations. Apparat will not replace a lost master diskette though it will, under the terms for the diskette update service offered in section 11.9, replace a damaged diskette.

Enter, via the keyboard, the DOS command:

LIB

A list of all the DOS library commands will be displayed to you. These commands are defined in chapter 2 with examples.

Enter the DOS command:

DIR,0,S,I

A list of all the files on the NEWDOS/80 Version 2 master diskette will be displayed. These files, except for NWD82V2/ILF and NWD82V2/XLF, are discussed in chapter 5.

Enter the DOS command:

SYSTEM,0

NEWDOS/80 offers the user certain system options which are specified via the DOS library command SYSTEM (see section 2.46) and activated during each computer reset. The DOS command SYSTEM,0 you just executed has displayed the state of all SYSTEM options, and you should compare these value carefully against the specifications. You may decide that your system is to use different SYSTEM specifications. You may change them now if absolutely necessary; otherwise you should wait until after you have made a few backup copies of the master diskette. Whenever you decide to update the master diskette, don't forget to take off the write protect tab.

Enter the DOS command

PDRIVE,0

NEWDOS/80 can operate with a limited mixture of disk drive and interface types. The characteristics of each of the physical drives 0-3 must be specified to the system via the DOS library command PDRIVE (see section 2.39). These characteristics are then read by DOS during each computer reset. The PDRIVE command you just executed has displayed the existing drive specifications plus 6 psuedo drive specifications. You may want to change the specifications for one or more drives. You may do so now if absolutely necessary; otherwise you should wait until you have a few backup copies of the master diskette.

Now you must make three or more copies of the NEWDOS/80 Version 2 master diskette. If possible, perform these initial backups without changing any of the SYSTEM or PDRIVE parameters. If not possible, change them the minimum necessary and do a reset when done. You should carefully study sections 2.14, 7.39 and 2.46.

NEWDOS/80 does NOT have a BACKUP module; format 5 or 6 of DOS library command COPY (see section 2.14) is used instead. For each of the backups you are about to do, the master diskette is both the system and the source diskette while the destination diskette is the diskette to contain the new working copy of the NEWDOS/80 system. Some examples of the COPY command you will use to make copies of the NEWDOS/80 Version 2 master diskette are:

COPY,0,0,,FMT,USD For a single drive system where the master and copy diskettes have the same PDRIVE characteristics.

COPY,0,1,,FMT,USD For a multiple drive system where the master and copy (mounted on drive 1) diskettes have the same PDRIVE characteristics.

COPY,0,0,,FMT,USD,CBF,DPDN=4 For single drive system wherein the destination diskette has PDRIVE characteristics different from the master diskette. You must have previously altered the master diskette PDRIVE specification for drive 4 (remember to use the A option or to reset the computer after changing the drive 4 specification).

COPY,0,1,,FMT,USD,CBF For a multiple drive system where the drive 1 drive will be moved to drive 0 after the copy and the destination drive has different PDRIVE characteristics than does the current drive 0. You must have previously altered the master diskette's PDRIVE specification for drive 1.

Each system diskette has its own set of SYSTEM and PDRIVE characteristics. Therefore, for each working copy of NEWDOS/80 Version 2 you make, after the copy is completed, you need to set that system diskette's SYSTEM and PDRIVE characteristics for the operating conditions it is to operate with.

The NEWDOS/80 owner is authorized to make as many copies as necessary of the NEWDOS/80 diskette or individual programs thereon for his/her own personal use. NEWDOS/80 owners and users are specifically prohibited from copying the NEWDOS/80 diskette or individual programs thereon for use by others. See COPY, formats 2 and 4, in section 2.14.

Before your NEWDOS/80 is ready to run user programs, review the outstanding zaps to both NEWDOS/80 modules and to other modules (such as EDIT/CMD and SCRIPSIT) that require patches to work properly with NEWDOS/80. Chapter 11 explains how to apply zaps (patches), and with your NEWDOS/80 should have come a chapter 13 which contains the zaps. If part or all of chapter 13 is not in the proper place in the manual, please put it there. Mandatory zaps must be applied; optional zaps are at user discretion.

Mandatory zaps to NEWDOS/80 modules should be applied to all copies of the NEWDOS/80 Version 2 master diskette and to the NEWDOS/80 Version 2 master diskette. DO NOT start applying the zaps until you have at least 2 or 3 good backup copies made of the NEWDOS/80 diskette.

Once all backup copies of the NEWDOS/80 Version 2 system are made, zaps applied, system options and drive characteristics specified, you are now ready to use NEWDOS/80.

Put away the master diskette and mount in drive 0 one of the system diskette just made. Then press reset to re-initialize DOS using the new diskette. NEWDOS/80 READY will then appear. The user may now type in a DOS command, which is either a DOS library command as discussed in chapter 2 or the name or name/ext of a user program to be loaded and run. If a user program does not have a name extension, name extension CMD is assumed. Examples:

BASIC causes the load and execution of program BASIC/CMD.

SCRIPSIT/LC causes the load and execution of program SCRIPSIT/LC.

If the DOS library command or the user program requires or allows for parameters within the DOS command, one or more spaces or a comma must follow the command name and precede the parameter(s). Examples':

BASIC,5,65000
DIR 1 A

For virtually all programs to be executed under NEWDOS/80, there are instructions on how to use the program that usually comes with the program when you buy it. For NEWDOS/80 program modules, the instructions are in chapter 6 except for BASIC which is covered in chapters 7 and 8.

Those users upgrading from NEWDOS/80 Version 1, NEWDOS/21 or TRSDOS to NEWDOS/80 Version 2 should read sections 12.1 through 12.5 carefully.

Over forty persons throughout the United States and Canada were involved in the testing of NEWDOS/80 Version 2, finding errors, suggesting enhancements and providing criticism. Apparat and the NEWDOS/80 author thank each one of these beta testers for the long hours spent working with the three beta releases that were sent out. It is Apparat's policy that each beta tester receive a complimentary copy of the final release of NEWDOS/80 Version 2.

All DOS commands terminate with an ENTER. In subsequent specifications, the ENTER is not shown, but the user is to supply it.

DOS commands are limited to a total of 80 characters, including the concluding ENTER.

[] A set of brackets are used to enclose an optional parameter. When using the optional parameter in a DOS command, the [] are not included.

Example:

[ ,PROT=xxx][,ASE=yn][,ASC=yn]

could be coded as

,PROT=READ,ASC=N

Upper case A - Z and non alphanumeric characters are to be included exactly as shown. See the above example.

Lower case letters or words with or without trailing decimal digits. These represent prototype values for which the user is to substitute the appropriate actual values. See the above example.

In some cases where the prototype will be replaced by one and only one character, the prototype word contains, in lower case, all the characters legal for that value. This helps serve as a reminder of which characters are legal replacement for that prototype value. For example, if ASC=Y and ASC=N are the only two legal ASC values, then the prototype will usually be written as ASC=yn.

Where commas are used in DOS commands, they may be replaced by one or more consecutive spaces.

Numeric values without a suffixed H are considered decimal values unless otherwise specified. Hexadecimal values must be suffixed with an H unless otherwise specified. Example:

4000E and 16384 are the same value.

When specifying a disk file, the term 'filespec' is used. A filespec is of the form:

name1[/ext1][.password1][:dn1]

Parameters must be specified in the above order.

name1 is the file's name consisting of 1 - 8 chars of which the first must be A - Z and the others A - Z or 0 - 9.

ext1 is the name extension (i.e., CMD, BAS, OBJ, CIM, TXT, DOC, COM, etc.) which classifies a file. A file need not have a name extension, but if it does it must be 1 - 3 chars of which the first must be A - Z and the others A - Z or 0 - 9. If a file has a name extension, all filespecs referencing the file must include the name extension, unless a default name extension is provided for (i.e., /CMD).

password1 is 1 - 8 chars of which the first must be A - Z and the others A - Z or 0 - 9. password1 is the value given to both the access and update passwords for a file when it is created. password1 is value used in password checking when an existing file is opened. password1 is required in a filespec if passwords are enabled and the file has passwords assigned; otherwise it is not.

dn1 is the drive # of the drive which has the diskette containing the file. Examples:

MYFILE80/BAS.YOURPW80:0
MYFILE:3
YOURFILE.YOURPW

NEWDOS/80 will accept lowercase in all DOS library commands and any further input that might be queried for.

For each DOS library command, the command keyword is stated along with a brief definition. Next, if the command is allowed parameters, a prototype of the command is given listing all required and optional parameters. Next comes explanations of the command, parameters and options. Lastly, some examples of the DOS command are given.

For documentation ease, the prototype command is sometimes shown spread over multiple lines in this document; however, the user should consider each command as one contiguous statement.

Unless otherwise stated, a DOS library command is executable under MINI-DOS (see section 4.2).

NEWDOS/80 differs from TRSDOS in NOT using parenthesis to enclose parameters. In NEWDOS/80 version 1, parenthesis around the operands were optional for BREAK, CLOCK, DEBUG, DIR, PROT, and VERIFY; they are NOT allowed in version 2.

In the same vein, version 1 allowed the keywords ON or OFF to be used instead of Y or N in the DOS commands BREAK, CLOCK, DEBUG and VERIFY; this is NOT allowed in version 2.

APPEND,filespec1,[TO,]filespec2

This command will append the file filespec1 onto the end of the file filespec2. The EOF from file filespec2's directory FPDE determines the point at which file filespec1 is appended. This may be trouble if file filespec2 had explicit EOF characters, such as in BASIC program files or assembler source files.

File filespec1 is not altered. The original content of file filespec2 are not altered the file is only added to.

APPEND is not executable under MINI-DOS.

APPEND examples:

1. APPEND,XXX:1,YYY/DAT:0

The contents of file XXX on drive 1 are appended onto the end of file YYY/DAT which is on drive 0.

2. APPEND AAA TO BBB

The contents of file AAA are appended onto the end of file BBB. DOS searches the currently mounted diskettes to find both files.

ATTRIB,filespec1[,INV][,VIS][,PROT=xxx][,ACC=password1][,UPD=password2][ ,ASE=e] [ ,ASC=c] [ ,UDF=u]

This command assigns attributes to the filespec1 file. At least one of the optional parameters must be specified.

If passwords are enabled in your system, then filespec1 must specify the existing update password, if any, for that file.

INV gives the file the invisible attribute. Unless the I option is specified in DIR, the file will not be listed by DIR.

VIS takes away the invisible attribute, whether the file had it or not.

PROT=xxx specifies the access level to be used during file I/O if passwords are enabled (see system option AA) and the access, not the update, password was used to open the file. The levels are defined for values of xxx as:

LOCK Level 7. No access allowed to the file at all, except by the system's overlay loader.

EXEC Level 6. Access allowed only to execute the file as a program. BASIC will require either RUN or LOAD with R option, and will disable the BREAK key, thereby preventing the user from stopping the RUN and disallowing direct statement execution.

READ Level 5. Access allowed for execute or to read the file's contents.

WRITE Level 4. Access allowed for execute, read or write of the file.

RENAME or NAME Level 2. Access allowed for execute, read, write or to rename the file.

KILL Level 1. Access allowed for execute, read, write, rename or to kill the file.

FULL Level 0. All operations are allowed on the file.

ACC=password1 password1 is assigned as the access password for the file. If null, a value of all blanks is assumed; otherwise the value must be 1 - 8 characters with the 1st = A - Z and the others A - Z or 0 - 9. Assigning the access password via this parameter of ATTRIB is the only way that will enable use of the PROT=xxx protection and then only if the access password is different from the update password. If a password is specified when the file is created, it is assumed both the update and the access password, and the update password has priority at open time. If passwords are enabled, the password specified in the filespec at open time is not the update password, and it is the access password, the current protection level is stored into the FCB for later use by the DOS read, write, load, etc. routines. Subsequently, if an access is attempted in violation of the access level, 'ILLEGAL ACCESS TRIED TO A PROTECTED FILE' error will occur.

UPD=password2 Password2 is assigned as the update password for the file. The update password is of the same configuration as the access password. During file open where passwords are enabled, the password specified in the filespec is checked first against the file's update password. If they match, then FULL access is allowed to the file.

ASE=e where e is either Y or N. This parameter has been added to allow DOS to automatically allocate diskette space to a file if ASE=Y or to disallow further allocation if ASE=N. ASE=Y is the default condition when a file is created.

ASC=c where c is either Y or N. This parameter has been added to allow DOS to automatically deallocate file diskette space beyond the EOF during a CLOSE operation if ASC=Y is specified, and to disallow this deallocation if ASC=N. ASC=Y is the default setting when a file is created.

UDF=u where u is either Y or N. This parameter has been added to mark the file as updated if UDF=Y is specified or to clear the updated mark if UDF=N is specified. The DOS system marks a file as updated whenever it is about to update a sector to that file and it finds the file's directory entry not marked as updated.

ATTRIB command examples:

1. ATTRIB,XXX/CMD:1,UPD=ZXCVB,ACC=NMLKJ,PROT=EXEC

Assigns to file XXX/CMD located on drive 1 the update password ZXCVB, the access password NMLKJ and protection level 6 which allows the program to be executed but not read or written to. Since the filespec XXX/CMD:1 did not specify a password, we must assume that either password checking was disabled (SYSTEM option AA=N) or the file did not have an update password prior to the ATTRIB command.

2. ATTRIB YYY/DAT.QZBV INV ASE=N ASC=N UDF=N

This command tests if file YYY/DAT has update password QZBV, and if so, assigns the file the invisible attribute, flags that extra space allocation and excess space deallocation are not to be allowed, and lastly clears the file's updated flag.

AUTO[,doscmd]

This command allows the user to specify a 1 - 31 character DOS command to be invoked automatically at reset time. This command is stored in the last 32 bytes of GAT sector of the current system diskette.

If doscmd is not specified, then a null command is stored in the GAT sector to indicate to reset/power-on that no AUTO command exists.

If SYSTEM option AB = N and BC = Y, by pressing ENTER during reset, the auto command in the GAT sector will be ignored, and the system will go to DOS READY.

AUTO is useful to the user who usually executes the same command or chain of commands (see CHAIN, sections 2.9 and 4.3, and DO, section 2.19) at reset time. By setting system option AB=Y or BC=N, the user is forced to this command or chain of commands, thus allowing the person(s) controlling a computer to restrict the activity of users of the computer.

AUTO command examples:

1. AUTO BASIC RUN"XXX/BAS"

causes subsequent reset/powerons to activate BASIC and to start the execution of the BASIC program XXX/BAS.

2. AUTO DO RSACTION

causes subsequent reset/power-ons to activate chaining from file RSACTION/JCL, thus executing the DOS and other program commands contained therein.

3. AUTO

causes subsequent reset/power-ons to go to the normal DOS READY, awaiting the next DOS command to be inputted from the keyboard.

This command puts the system into non-disk BASIC. NEWDOS/80 is no longer in the system.

BLINK[,yn]

BLINK or BLINK,Y Blinking of the display cursor is turned on.

BLINK,N Blinking of the display cursor is turned off.

SYSTEM option BH can be used to set the cursor blinking state at reset/ power-on.

On the Model I, this command deselects the drives and then executes Z-80 instruction HALT, which causes both a hardware and a software reset. For the Model III, since HALT does not cause a hardware reset, this instruction causes a jump to location 0 to execute a software reset.

BREAK[,yn]

BREAK or BREAK,Y The BREAK key is enabled as a normal input key (hexadecimal code 01) until the next normal DOS READY, when it is set according to system option AG.

BREAK,N The BREAK key is disabled as a normal input key until the next normal DOS READY, when it is set according to system option AG.

The BREAK command is useful for those programs that want the BREAK key enabled, and enable it via a DOS-CALL (vector 4419H). The same applies to programs that definitely want BREAK disabled. NOTE: Executing BREAK from DOS READY is useless since the immediate return to DOS READY resets the BREAK key according to system option AG.

In NEWDOS/80 the BREAK key may also be enabled by storing a 0C9H byte in Model I location 4312H (Model III location 4478H) and may be disabled by storing a 0C3H byte in that location. In NEWDOS/80 version 1, the break key was also manipulated by changing bit 4 of location 4369H (Model I only); in version 2 for the Model I, setting or clearing this bit does nothing and is harmless. However, programs on the Model III must NOT alter that bit, as that location is now in the system buffer.

CHAIN,filespec1[,sectionid]

DOS command DO performs exactly the same as CHAIN.

The purpose of the CHAIN command is to cause a predefined set of characters to be treated as input from the keyboard. This predefined set of characters has been previously stored in the file filespec1.

The CHAIN command places NEWDOS/80 in chaining mode, if not already there. The file filespec1 is opened. If sectionid is not specified, the file is positioned at the beginning. If sectionid is specified, the file is searched for the matching sectionid record, leaving the file positioned at the byte following the section ID record.

Subsequently, input that is supposed to come from the keyboard comes from the chain file until chaining is terminated by the encounter of either end of file or end of section or until chaining is temporarily halted by the execution of the DOS command CHNON,N.

Keyboard data is input from the chaining file in one of two modes.

If SYSTEM option AT = N, chaining operates in record mode. In this mode, whenever NEWDOS/80, BASIC or any program requests a new record from the keyboard via the standard ROM keyboard record input routine at 05D9H, the record will come from the chain file. Any other requests for keyboard input are honored from the keyboard and not the chain file.

If SYSTEM option AT = Y, chaining operates in byte mode. In this mode, all requests for keyboard input characters via the standard keyboard input routine are honored from the chain file.

The CHAIN command may be issued via DOS-CALL or via BASIC'S CMD function. When so, DOS does not immediately return to the calling program but instead continues to execute commands from the chain file until either end of file, end of section, command CHNON,N or command CHNON,Y is encountered.

CHAIN is not legal under MINI-DOS.

The chain file creator/maintainer is responsible for assuring that chaining does not create impossible situations for the system or user programs.

NEWDOS/80 cannot have more than one chain file active at a time. If the new DOS command from the current chain file is itself a CHAIN or DO command, processing in the current file ceases and the new chain file is opened, becoming the new current chain file.

When the system opens a chain file, name extension in the filespec defaults to JCL if the filespec doesn't give one.

CHAINING is discussed further in section 4.3.

CHAIN or DO command examples:

1. CHAIN,XXX:0

Chaining starts at the beginning of file XXX/JCL:0.

2. DO YYY/CHN:1

Chaining starts at the first byte of the chain section named QQQ within file YYY/CHN.

CHNON,ynd

The CHNON command is used during chaining. An error will occur if a chain file is not currently open. A CHNON command should not be the last entry in an un-sectioned chain file or the last entry in a chain file section as the command will be meaningless.

CHNON,N

The current position within the chain file is remembered and chaining is temporarily suspended so that subsequent keyboard characters to come from the keyboard. If chaining was being done under DOS-CALL, the current DOS-CALL level is exited.

CHNON,Y

causes subsequent keyboard characters to come from the chain file, starting at the current position within the chain file. If CHNON,Y was executed as a DOS-CALL, the current DOS-CALL level is exited.

CHNON,D

causes subsequent keyboard characters to come from the chain file, starting at the current position within the chain file. If CHNON,D was executed as a DOS-CALL, DOS remains at that level and executes subsequent commands from the chain file until either CHNON,Y or CHNON,N or end of section or end of file is encountered.

See sections 2.9 and 4.3 for further discussion of chaining.

CLEAR[,START=addrl][,END=addr2][,MEM=addr3]

The CLEAR command performs the following functions:

1. Performs ROUTE,CLEAR DOS command function.

2. Dequeues all user routines in the timer interrupt routine chain that were enqueued by the 4410H (Model I) or 447BH (Model III) call to DOS. This includes turning the clock display off.

3. Dequeues all *name routines that were enqueued by a 4461H call to DOS. This includes the NEWDOS/80 spooler, if active, but not its graceful termination. The spooler, if in use, should be fully terminated before executing CLEAR.

4. Resets HIMEM to addr3 or, if addr3 not specified, to the highest memory address.

5. Zeroes memory from addrl or 5200H, which ever is greater, through addr3 or HIMEM, whichever is lower. addrl must be greater than or equal to 5200H and less than or equal to addr3.

CLEAR command examples:

1. CLEAR,START=6000H,MEM=0DFFFH

All routes are cleared, and all timer and *name routines dequeued. HIMEM is set to 0DFFFH. The main memory between 6000H and 0DFFFH is zeroed.

2. CLEAR

All routes are cleared, and all timer and *name routines dequeued. HIMEM is set to the highest main memory location, and all memory from 5200K to HIMEM

CLOCK[,yn]

CLOCK or CLOCK,Y The current value of the clock is displayed every second in positions 53-60 of the display's top line in HH:MM:SS format.

CLOCK,N The displaying of the clock ceases.

Users are warned that the clock will continuously lose time. There is no hardware clock in the sense of seconds, minutes and hours. Computation of clock time is done from the 25ms interrupt chain in the Model I (in the Model III, it is done in the ROM from the timer interrupt). Whenever the interrupts are left off for more than 25ms (33 or 40 ms on the Model III), one or more interrupts are lost and for each one lost, the clock loses 25ms (33 or 40 ms on the Model III). Lost interrupts are very frequent when disk I/O is being done, is massive when tape I/O is done, and can also be frequent if other routines hung off the 25ms chain are more than a few milliseconds long.

CLS simply clears the display, resetting it to 64 character mode. On the Model III, reserved top display lines are not cleared.

The COPY command is used to copy a single file, multiple files or a full diskette. COPY has 6 formats:

1. COPY,filespec1[ ,TO] ,filespec2[ ,SPDN=dn3][,DPDN=dn4]
2. COPY,$filespec1[,TO],filespec2[,SPDN=dn3][,DPDN=dn4]
3. COPY,[:]dn1,filespec1[,TO],filespec2[,SPDN=dn3][,DPDN=dn4]
4. COPY, [:]dn1 ,$filespec1 [,TO] ,filespec2[ ,SPDN=dn3][ ,DPDN=dn4]
5. COPY, [:]dn1 [=tc1 ][ ,TO], [: 3dn2[=tc2] ,mm/dd/yy [ ,Y] [ ,N][ ,NDMW][,FMT][,NFMT][,SPDN=dn3 ][,DPDN=dn4][,SPW=password1] [,NDPW=password] [,DDND] [,ODN=name1] [,KDN3] [,KDD] [,NDN=name23 [,SN=name3] [,USD] [,BDU3] [,UBB]
6. COPY, [:]dn1 [,TO],[:]dn2[=tc2] ,mm/dd/yy,CBF[ ,Y] [ ,N][ ,USR] [,/ext][,UPD][,ILF=filespec3][,XLF=filespec4][,CFW03 [ ,HDMW] [,FMT] [,NFMT] [,SPDN=dn3] [,DPDN=dn4] [,SPW=password1] [,0DPW=password2] [,NDPW=password3] [,DDND] [,ODN=name1 ] [ ,KDN] [ ,KBD] [ ,NDN=name2] [ ,SN=name3 ] [ ,USD] [ ,UBB3 [,DDSL=ln1][,DDGA=gcl]

The COPY command has been significantly changed in NEWDOS/80 version 2; all users, new and old, should carefully read this section.

COPY cannot be executed under MINI-DOS; however for simple single file copies, DOS library command MDCOPY is available.

dn1 and dn2 are drive numbers and may be equal. The colon preceding dn1 and / or dn2 is optional.

filespec1 is the source file's filespec. Filespec2 is the destination file's filespec.

filespec1 prefixed with $ means that either the source or the destination file or both are to be on drive 0 and are on diskette(s) that either (1) do not contain a NEWDOS/80 system identical to the one on drive 0 when COPY was initiated, (2) do not contain a NEWDOS/80 system, or (3) contain no system at all.

During processing for formats 2, 3, 4, 5 and 6, the system may ask for various diskette mounts; do what the prompts ask!!

1. When prompted for the system diskette, mount the NEWDOS/80 diskette that was on drive 0 at the start of the COPY command execution.
2. When prompted for the source diskette, mount the diskette containing file filespec1 (formats 1, 2, 3 and 4) or the data to be copied (formats 5 and 6).
3. When prompted for the destination diskette, mount the diskette to contain file filespec2 (formats 1, 2, 3 and 4) or to receive the data being copied (formats 5 and 6).

SPDN=dn3 Source PDrive Number. SPDN=dn3 tells the system that for all source drive I/O, the system diskette's PDRIVE specifications (see DOS command PDRIVE, section 2.37) for drive dn3 are to be used instead of the source drive's normal PDRIVE specifications. dn3 is a value 0 to 9, referring to a drive number listed by the PDRIVE command.

DPDN=dn4 Destination PDrive Number. DPDN=dn4 tells the system that for all destination drive I/Os, the system diskette's PDRIVE specifications for drive dn4 are to be used instead of the destination drive's normal PDRIVE specifications. dn4 is a value 0 to 9 referring to a drive number listed by the PDRIVE command.

Note that use of SPDN and DPDN for a drive 0 single drive COPY (formats 4, 5 or 6) means that three different PDRIVE specifications (one for the system diskette, one for the source diskette and one for the destination diskette) will apply during the COPY even though only one drive is used.

Format 1 is the single file copy. It is used to copy the contents of file filespec1 to file filespec2. The diskette(s) involved in the COPY must already be mounted; the system gives no mount prompts. The contents of file filespec1 are not altered. The previous contents of file filespec2, if any, are lost. If the leading part of filespec2 equals that of filespec1, filespec2 may be shortened by leaving off the leading part, the remainder of filespec2 starting with / or . or :. For example:

COPY,USERFILE/DAT:0,TO,USERFILE/DAT: 1

can be shortened to:

COPY,USERFILE/DAT:0,TO,:1

Remember, the keyword TO is optional, and spaces may be used instead of commas. Thus the command could be written:

COPY USERFILE/DAT:0 :1

Format 2 is the same as format 1 except that the $ sign prefixed onto filespec1 indicates that a conflict exists with drive 0, the system drive, and DOS will prompt for the proper diskettes to be mounted on drive 0. If the source and destination drive numbers are both zero but the source and destination files are on separate diskettes, use format 4 instead of format 2.

Format 3 again is similar to format 1, except that the user has only 1 drive available for the copy and file filespec1 resides on a diskette different from that of file filespec2. Neither filespec can specify a drive number. DOS will prompt for the mount of the source and destination diskettes as they are needed. If drive 0 is specified, both the source and destination diskettes must contain a NEWDOS/80 system identical to the one mounted on drive 0 at the start of the COPY command; otherwise use format 4.

Format 4 performs similar to format 3 except that either file or both reside on diskettes with different NEWDOS/80 systems, non-NEWDOS/80 systems or no systems at all. DOS will prompt for the mount of the system, source and destination diskettes as they are needed. Format 4 should only be used when dn1 equals 0; otherwise you are wasting time with diskette swaps that are not needed.

Formats 2 and 4 allows suppliers of programs, whether free or purchased, to send their program products on diskettes that do not contain NEWDOS systems. Aside from the supplier's programs and/or data files, the diskette need only contain the directory and the BOOT/SYS file, both created on each diskette during formatting. Suppliers must not include a NEWDOS system on their diskettes unless they have made explicit arrangements with Apparat.

NEWDOS/80 does not have a diskette BACKUP program. Instead, either formats 5 or 6 is used. Format 5 is a full diskette sector by sector copy without concern for the number and type of files. Format 6 copies some or all of the source diskette's files onto the destination diskette. Of the two, for the same amount of data transmitted, format 5 is faster while format 6 allows greater variation between source and destination diskette types and tries to reassign files to contiguous space.

Format 5 is a full diskette copy. The default specifications for the two drives are the PDRIVE specifications currently being used by DOS. The drives must have the same number of sectors per track, granules per lump and sectors per granule (five is the current NEWDOS/80 standard); otherwise format 6 must be used. The destination diskette may have more tracks than the source; if so, the destination directory is adjusted to account for the extra free granules (not done if BDU option specified). Format 5 options are defined as follows:

=tc1 DOS is to use the value tcl as the source diskette's track count during the COPY rather than the source drive's default value.

=tc2 DOS is to use the value tc2 as the destination diskette's track count during the COPY rather than the destination drive's default value.

mm/dd/yy is the date to be placed in the destination diskette date field. The mm/dd/yy may be null, and if so the system date is used. The only time mm/dd/yy may be entirely left out of the format 5 COPY command is when the command has only the two drive number parameters (example: COPY 0 1 ). Otherwise mm/dd/yy must be the 3rd parameter even if it is null or to be overridden by either the KDD or the USD parameter. If the mm/dd/yy is null, this must be so indicated by separating commas (not spaces) (example: COPY 0 1,,FMT CBF ).

Y The user doesn't care what was previously on the destination diskette. Y is mutually exclusive with N, ODN, ODPW, DDND, KDN or KDD. Y is the default (for COPY) if none of its mutual exclusions are specified.

N At the start of the COPY or FORMAT the destination diskette must not contain recognizable data, i.e., should be in a bulk erase state. COPY will be terminated if the diskette is found to contain data. N is mutually exclusive with Y, ODN, ODPW, DDND, KDN or KDD.

NDMW No Diskette Mount Waits. DOS is to assume that all needed diskettes are already mounted on the specified drives. No mount prompts or error prompts are displayed. If an error occurs that otherwise would have caused a prompt, the copy will be terminated. If NDMW is specified and neither FMT nor NFMT are specified, FMT is assumed. NDMW is intended for use when COPY (or FORMAT) is invoked via DOS-CALL (i.e., from BASIC) and the calling program does not want operator interaction. Since NDMW causes the COPY or FORMAT to bypass error and disk mount queries, it is recommended that NDMW normally not be used when the operator is keying in the COPY (or FORMAT) command.

FMT Format. DOS formats the destination diskette before copying data. FMT is mutually exclusive with NFMT. If neither FMT or NFMT is specified and NDMW was not specified, the operator will be queried 'FORMAT DISKETTE? (Y OR N). If neither FMT or NFMT is specified and NDMW was specified, FMT is assumed.

NFMT No Format. DOS does not format the destination diskette before copying data. The user must assure that the destination diskette is already formatted correctly. NFMT is mutually exclusive with FMT.

SPW=password1 Source Password. If passwords are enabled (system option AA = Y) and system option AR = N, then COPY requires a source diskette master password match. If password1 does not match the source diskette's password, the copy function will be terminated.

NDPW=password3 New Destination Password. Password3 must conform to rules for passwords and is assigned as the destination diskette's new password. NDPW is mutually exclusive with BDU.

DDND Display Destination old Name and Date. The destination diskette's old name and date are prompted to the display, allowing the operator to decide whether or not to proceed with the copy. DDND is mutually exclusive with Y, N, and NDMW.

ODN=name1 Old Destination Name. If the destination diskette's old name is not equal to name1 , then the system prompts, allowing the operator to decide whether to proceed with the copy. ODN is mutually exclusive with Y, N and NDMW.

KDN Keep Destination diskette Name. The destination diskette keeps its old name rather than receive the source diskette's name. KDN is mutually exclusive with Y, N, BDU and NDN.

KDD Keep Destination diskette Date. The destination diskette keeps its old date rather than receive the mm/dd/yy parameter from the COPY command. KDD is mutually exclusive with Y, N, BDU and USD.

NDN=name2 New Destination Name. The destination diskette takes name2 as its name, rather than receive the source diskette's name. Name2 must conform to the specification for diskette names. NDN is mutually exclusive with BDU and KDN.

USD Use Source Date. The destination diskette uses as its date the source diskette's date, rather than receive the mm/dd/yy parameter from the COPY command. USD is mutually exclusive with KDD and BDU.

SN=name3 Source diskette Name. If the source diskette's name is not equal to name3, a prompt is issued, allowing the operator to decide whether or not to proceed with the copy.

BDU Bypass destination Directory Update. Aside for simply copying the source sectors onto the destination diskette, the format 5 COPY also updates the boot and PDRIVE data in the destination file BOOT/SYS and, as necessary, the name, date, password and extra granule information into file DIR/SYS. There are times, however, when this file updating is not wanted, and by specifying option BDU these updates are bypassed. BDU is useful when the source diskette has a bad directory, has a non-standard directory (such as a TRSDOS Model III directory) or has no directory at all or when the user wants a full diskette copy with no alterations. BDU is mutually exclusive with KDN, NDN, NDPW and USD.

UBB Use Big Buffer In NEWDOS/21 and NEWDOS/80 version 1, COPY was restricted to using main memory below 7000H unless it was a two diskette, single drive COPY, in which case all of memory to HIMEM was used. If a user wanted to force the usage of all memory to HIMEM, the UBB parameter had to be specified. However, in NEWDOS/80 version 2, all of main memory to HIMEM is used unless the COPY was invoked under DOS-CALL (i.e., from BASIC), in which case only main memory below 7000H is used. Thus, in NEWDOS/80 version 2, UBB is a useless parameter left in existence only for upward compatibility from Version 1.

Format 6 is the multiple file COPY and is distinguished from format 5 by the inclusion of the CBF (Copy By File) option. Though format 5 is the faster way to backup a diskette, format 6 offers more flexibility, allowing files to be copied between diskettes and drives of widely varying characteristics. The choice of files to be copied can be limited by the combined effect of options USR, /ext, UPD, ILF, XLF and CFWO; if one or more criteria are specified, only those files satisfying all the criteria are copied. Format 5's options, except BDU, are used in format 6 as well as the following additional options.

If NFMT is specified, then none of Y, N, KDN, KDD, NDN, BDU, USD, NDPW, DDSL, DDGA or tc2 may be specified, ODPW may be required, and system files are not copied unless already existent in the destination file directory.

If NFMT is not specified, then the destination file is formatted as if the command was FORMAT, including establishing BOOT/SYS and DIR/SYS. Then, before any files are copied, all files to be copied are entered into the destination diskette's directory. This is necessary as system files must occupy the same directory FPDEs in order for DOS to work at all.

CBF Copy By File CBF, required for and used only in format 6, indicates the copy will be done by files rather than in straight sequential order of diskette sectors.

USR copy user files. Only user files are copied; system and invisible files are excluded.

/ext copy files having name extension ext. Only files with name extension ext are copied. ext is a 0 to 3 character name extension. Examples of this parameter are /CMD, /, /BAS, /X.

UPD copy updated files Only files that have the updated flag on in the source diskette directory are copied. This flag is turned on by the standard DOS sector write routine to indicate that at least one sector has been written or re-written to this file since the last time the updated flag was cleared. This flag is turned off by specific request via the PROT or ATTRIB commands and is NOT turned off by COPY. Since the standard DOS sector write routine is used to write the file's sectors to the destination diskette, the updated flag is turned on for the copied destination files.

ILF=filespec3 Include List File Filespec3 specifies a file containing a list of files to be copied. If a file is not in the list, it is not copied. It is not an error if an included file is not on the source diskette. Within the list, each file to copied is specified by its name/ext followed by a EOL char ( 0DH). If a specification begins with a semicolon, it is bypassed as a comment. Each specification, except comment, is limited to a maximum of 13 characters, including the EOL. On reading, the file's bytes are modulated into the ASCII range 0 to 127. The file can be made using SCRIPSIT, but the user must assure that no characters other than null ( 00H) follow the last EOL character; SCRIPSIT tends to leave extraneous characters so a delete-to-end-of-text should be done. ILF is mutually exclusive with XLF.

XLF=filespec4 Exclusion List File. The file filespec4 is the same structure as specified for ILF above and specifies the files to be excluded from the COPY. It is not an error if an excluded file is not on the source diskette. XLF is mutually exclusive with ILF.

CFWO Check File With Operator. For the qualifying files, DOS asks the operator, one file at a time, if the file is to be copied to the destination diskette. Reply Y if the file is to be copied, reply N if not to be copied, reply R if to restart entire CFWO query sequence, or reply Q if no more files to be copied. No files are copied until the querying is completed.

ODPW=password2 Old Destination diskette Password. If NFMT is specified, if passwords are enabled and if system option AR = N, then copy requires a destination diskette password match. If password2 does not match the destination diskette's password, the copy is terminated.

DDSL=ln1 Destination diskette Directory Starting Lump. Formatting will start the directory on the 1st sector of lump lnl if DDSL is specified; otherwise the default starting lump number for the drive (see PDRIVE command) will be used. DDSL is mutually exclusive with NFMT.

DDGA=gc1 Destination diskette Directory Granule Allocation. Formatting will allocate gcl (value 2-6) granules to the directory if DDGA is specified; otherwise it will assign the default # of granules for that drive (see PDRIVE command). DDGA is mutually exclusive with NFMT.

If during a format 6 COPY, the destination diskette has insufficient space to contain a file, "DISKETTE FULL = name/ext" is displayed and the destination file's EOF is set to 0. Though EOF is set to 0, any space the file may have allocated to it is not deallocated.

A single drive format 5 or 6 COPY cannot be executed under DOS-CALL (i.e., from BASIC) since COPY under DOS-CALL restricts itself to main memory below 7000H and this would necessitate too many diskette swaps.

During a COPY or FORMAT where NDMW was not specified, pressing right arrow at any time will cause the function to pause, awaiting ENTER to continue or up-arrow to cancel. Pressing up-arrow at any time will terminate the function; however, be careful as the state of the destination diskette will be unknown, especially if the cancel comes during the actual formatting.

The COPY command and standard 40 track, double density, single sided, 5 inch TRSDOS Model III diskettes may be used to transfer TRSDOS Model III diskette files into or out of the NEWDOS/80 system. There are a number of restrictions to this operation.

NEWDOS/80 cannot be used to format a TRSDOS Model III diskette; however, once the user has a formatted empty TRSDOS Model III diskette, he/she may duplicate it repeatedly under NEWDOS/80 using format 5 COPY with the NFMT and BDU options, thus obtaining a stock of formatted, empty TRSDOS Model III diskettes.

The user must assure that where the source and/or destination is a TRSDOS Model III diskette the proper PDRIVE specs are invoked, either implicitly or directly by the SPDN and/or DPDN parameter (see PDRIVE command example 3, section 2.37 for the exact PDRIVE specification).

A file need not previously exist on a TRSDOS Model III diskette in order for it to be copied. NEWDOS/80 will allocate the proper directory entry and diskette space.

Any of COPY formats 1, 2, 3, 4 or 6 may be used to copy files to or from TRSDOS Model III diskettes. Remember, FMT must not be specified. If format 6 is used and one of the source or destination is a TRSDOS Model III diskette, then files marked as SYSTEM files (FPDE 1st byte, bit 6=1) are NOT copied.

Files copied between NEWDOS/80 and TRSDOS Model III are always readable though not necessarily usable on the receiving system.

Examples of COPY:

1. COPY XXX:1 YYY:1
   In this format 1 COPY, file XXX on the diskette already mounted on drive one is copied as file YYY on that same diskette.
2. COPY,AAA,BBB:2
   In this format 1 COPY, the currently mounted diskettes are searched for the file AAA. If found, it is copied as file BBB to the diskette already mounted in drive 2.
3. COPY SUPERZAP/CMD:0 :3
   In this format l COPY, the file named SUPERZAP/CMD is copied from diskette already mounted in drive 0 to the diskette already mounted in drive 3. Since the file name and name extension are the same for both files, they were dropped from the second filespec.
4. COPY XXX:1 2 SPDN=9
   In this format 1 COPY, SPDN=9 causes, for the duration of the COPY only, all source file I/O to assume that drive 1 has the characteristics specified for drive 9 in the PDRIVE specifications. If we assume that the PDRIVE drive 9 specifications were those for a Model III TRSDOS diskette (see PDRIVE example 3, section 2.37), this COPY will copy file XXX from the TRSDOS Model III diskette already mounted on drive 1 to the NEWDOS/80 diskette already mounted on drive 2.
5. COPY $XXX:1,YYY:0
   In this format 2 COPY, the destination diskette to contain file YYY is not the same diskette as was mounted on drive 0 when the COPY command was initiated. DOS will ask for the mount of the destination and the system diskettes as it needs them.
6. COPY,$XXX:0 YYY:1
   In this format 2 COPY, the source diskette containing file XXX is not the same diskette as was mounted on drive 0 when the COPY command was initiated. DOS will ask for the mount of the source and system diskettes as it needs them.
7. COPY 1 XXX YYY/DAT
   In this format 3 COPY, the diskette containing file XXX is not the same diskette as the one to contain file YYY/DAT yet both the source and destination diskettes are to use drive 1. DOS will ask for the mount of the source and destination diskettes as it needs them. Note that, as required for format 3 and 4, neither filespec contains a drive number.
8. COPY 0 XXX/DAT /DAT
   In this format 3 COPY, file XXX/DAT on one diskette is to be copied as file XXX/DAT on another. Both diskettes are to be mounted on drive 0, and DOS will ask for them as needed. Since drive 0 is used and this is format 3 rather than format 4, both the source and destination diskettes must contain NEWDOS/80 systems identical to that mounted on drive 0 when the COPY command was initiated.
9. COPY 0 $XXX/DAT /DAT
   This format 4 COPY accomplishes essentially the same thing as the previous example. The difference is that DOS assumes that neither the source nor the destination diskette contains the proper NEWDOS/80 system; so DOS will ask for the mount of the system, source and destination diskettes as it needs them.
10. COPY 0 $XXX XXX SPDN=9
    This format 4 COPY accomplishes the same thing as in example 4 above excepting that only drive 0 is used. For the duration of this COPY, drive 0 uses two sets of PDRIVE specifications. The standard drive 0 specifications are used for the system and destination diskette I/Os, and the system diskette's PDRIVE's drive 9 specifications are used for the source diskette I/Os. Note, in this example, the second filespec was not foreshortened as there was nothing to foreshorten.
11. COPY 0 1 06/01/80 FMT
    This format 5 COPY is an example of one of the simplest and most commonly used forms of the full diskette COPY. This COPY copies one diskette to another using drive 0 as the source drive and drive 1 as the destination drive. Default track counts for the associated drives are used as diskette track counts. Both drives, other than possibly having different track counts (destination must be greater than or equal to source), have the same characteristics. The operator will be prompted for diskette mounts and error choices, if errors occur. Default parameter Y is in effect, indicating the operator does not care if the destination diskette previously contained data or not. The destination diskette will be formatted before the entire source diskette is copied to it, and it will receive the source diskette's name and password. Its date will be set to 06/01/80. If the destination diskette is to have more tracks than the source, they will be formatted and properly accounted for in the directory such that the destination diskette will be ready for use.
12. COPY 0 1,,NFMT
    This format 4 COPY is an example of another form of the simplest and most common full diskette copy. The only difference between this example and the one above is (1) the destination diskette is assumed already formatted, and (2) the current system date will become the destination diskette's date.
13. COPY, 0,0,06/01/80, NFMT, USD, KDN,ODN=WATCHDOG,SN=GOODDATA
    This format 5 COPY is somewhat the same as the previous example except (1) this is a single drive, two diskette copy, (2) a prompt will be given if the source diskette does not have the name specified, (3) a prompt will be given if the destination diskette does not have the name specified, (4) the destination diskette will retain its old name, (5) it will receive its date from the source diskette. Being a single drive, two diskette copy, more mount prompts will be necessary than for a two drive COPY. Also, because of the large number of diskette mounts that would be involved, this single drive COPY cannot be executed via DOS-CALL (i.e., from BASIC).
14. COPY 0,1,,FMT,CBF
    This format 6 COPY is an example of one of the simplest and most commonly used forms of multiple file COPY. The destination diskette (to be mounted on drive 1) is to be formatted, and it receives its name and password from the source diskette (to be mounted on drive 0) and its date from the system date. Next, all of the source diskette's files, excepting BOOT/SYS and DIR/SYS, are copied to the destination diskette.
15. COPY 0,1,,NFMT,CBF
    This format 6 COPY is an example of another of the simplest and mostly commonly used forms of multiple file COPY. The differences between this and example 14 are (1) the destination diskette is not to be formatted, (2) its name, password and date are not changed, and (3) any source diskette system files (other than BOOT and DIR) that did not already exist on the destination diskette are not copied.
16. COPY 0 1,,NFMT,CBF,USR
    This format 6 COPY is similar to the previous example except that system and invisible files are not copied.
17. COPY,0,1,,NFMT,CBF,USR,UPD
    This format 6 COPY is similar to the previous example except that the only source files copied are those marked as updated as well as not being either a system or an invisible file. In this manner, only the files changed since the last backup are backed up now. Remember, COPY does not clear the updated flags on the source diskette; use DOS commands PROT or ATTRIB to do this.
18. COPY,2,3=60,06/01/80,FMT,NDMW,CBF,DDSL=29,DDGA=4
    During this format 6 COPY no diskette mount prompts or error choices are to be displayed; the system is to assume the diskettes are already properly mounted. The destination diskette is to be formatted with 60 tracks. The directory will start on lump 29, and will be allocated 4 granules. All source diskette files, except BOOT/SYS and DIR/SYS, will be copied to the destination diskette.
19. COPY 2 3 06/01/80,CBF,CFWO,NFMT
    For this format 6 COPY, the destination diskette is assumed previously properly formatted and may contain existing files. For each source diskette file, excluding BOOT/SYS and DIR/SYS, the operator will be asked if the file is to be copied to the destination diskette. When all queries are done, the selected files are copied, excepting that system files that did not previously exist on the destination diskette are not copied. If the file already existed on the destination diskette, the file's old data on the destination diskette is lost.

CREATE, filespec1[,LRL=ln1][,REC=count1][,ASE=yn][,ASC=yn]

The CREATE command allows a user to create a file and optionally to write to

the file a specified number of null records, thereby allocating the file's

space as contiguously as possible, given the layout of the free space on the diskette.

There are times when a user program expects one or more of the files it uses to already exist, even though the files may not have any usable data in them; therefore, the user must create the file prior to the program's first use. Also, there are times when the efficiency of a program is reduced if a file's diskette space is scattered all over the diskette; to avoid this, the user should preallocate the needed file space to reduce this scattering.

The CREATE DOS command creates new file filespec1 or alters the state of existing file filespec1.

LRL=ln1 specifies the length of each record of the file. lnl must be a value between 1 and 256; the default value is 256.

SEC=count1 specifies the number of records to be initially assigned to a file.

ASE=yn This parameter indicates whether, subsequent to the CREATE command, DOS may automatically allocate more diskette space to this file as necessary. ASE=Y allows this; ASE=N disallows this. The default is ASE=Y.

ASC=yn This parameter indicates whether the DOS close function will be allowed to automatically deallocate excess diskette space. ASC=Y allows this; ASC=N disallows it. The default is ASC=Y.

Enough diskette space is allocated to the file to provide for count1 records each of length lnl. lnl records of all zeroes are then written to the file, establishing the file EOF at the end of those records. If ASE=N is specified, the file is inhibited against further diskette space allocation, and if ASC=N the file is inhibited against automatic deallocation of excess diskette space.

CREATE command examples:

1. CREATE,XXX:1,LRL=30,REC=2000
   File XXX is created, if it did not already exist, on the drive 1 diskette. The record length is 30 and 2000 of these records, containing all 00H bytes, are written to the file. The EOF is left at 60000. Subsequent DOS automatic space allocation and deallocation for this file are allowed.
2. CREATE,YYY:2,200,ASE=N, ASC=N
   File YYY is created, if it did not already exist, on the drive 2 diskette. The record length is 256 and 200 of these records, containing all 00H bytes, are written to the file. The EOF is left at 51200. Subsequent DOS automatic space allocation and deallocation for this file are not allowed.
3. CREATE,ZZZ:0
   File ZZZ is created, if it did not already exist, on the drive 0 diskette. The record length is 256, and the EOF is set to 0. Subsequent DOS automatic space allocation and deallocation for this file are allowed.

DATE[,mm/dd/yy]

If no parameters are specified, the DATE command displays the current system date in mm/dd/yy format.

If mm/dd/yy is specified, the date mm/dd/yy becomes the system date and is set into the real time clock. mm is the month (value 01 - 12). dd is the day (value 01-31). yy is the year (value 00 - 99). No check is made on the validity of the 3 values except to limit them to 2 decimal digits. As the clock reaches 24:00:00, it is reset to 00:00:00 and the date's day within month value is incremented. For the Model I, no adjustment is made for end of month or end of year. For the Model III, end of month and end of year adjustments are done by the ROM.

At reset time, the date is set according to SYSTEM options AY or AZ.

DATE command examples:

1. DATE
   display the system date.
2. DATE,08/01/81
   set system date to August 1, 1981.

DEBUG[,yn]

DEBUG or DEBUG,Y DEBUG is enabled (but not entered). This enabling causes a DEBUG entry whenever a user program (such as BASIC, SCRIPSIT, PROFILE, EDIT, etc.) is activated. The DEBUG entry occurs after the program load is completed but just before its first instruction is executed. The purpose of this pre-execution DEBUG entry is to allow the debugging programmer to change the state of a program or its initialization parameters before the program commences execution.

DEBUG,N The above enabling is disabled. At reset/power-on time, DEBUG is disabled.

This command has no effect on the operation of '123' (the simultaneous depressing of the 1,2 and 3 keys) to enter the DEBUG facility.

Refer to the section 4.1 for the DEBUG facility specifications.

DIR[:][dn1][,A][,S][,I][,U][,/ext][,P]

This command displays directory information for the diskette mounted on drive dn1 or if dn1 not specified, on the drive specified by system option AN.

The first display line contains the drive number, the diskette name, its date, the number of tracks, the number of free FDEs and the number of free granules. The values for track count and free granules are based on the current active PDRIVE specification for that drive and if those specifications are not proper, these displayed values may be in error.

The rest of the display contains file information.

If A is not specified, the files are displayed four to a line, giving for each its name and name extension, if any.

If A is specified, DIR will list one file per display line with the display line containing:

1. The file's name.
2. The file's name extension, if any.
3. The file's EOF value in xxx/yyy format where xxx is the relative sector number within the file and yyy is the relative byte number within that sector.
4. The file's logical record size (LRL) in bytes.
5. The number of logical records (RECS) in the file including any partial last record.
6. The number of granules (GRANS) allocated to the file.
7. the number of diskette space extents (EXT) allocated where that number divided by four and rounded up gives the number of directory entries used by the file.
8. 12 flags providing file information, defined as follows:

1. S = system file.

2. I = invisible file, see ATTRIB DOS command.

3. U = file updated since last time update flags cleared by PROT DOS command.

4. E = file will not be allowed to allocate more space that it already has.

5. C = excess file space beyond EOF is not automatically released during DOS close.

6.-9. Reserved for future definition.

10. U = non-blank update password exists.

11. A = non-blank access password exists.

12. L = protection Level, see ATTRIB DOS command.

System files are not displayed unless S is specified.

Invisible files are not displayed unless I is specified.

If U is specified, only files marked as updated are displayed. Files marked as updated are those files changed via the standard DOS I/O write routine since the last time the update flags were cleared on the target diskette by the PROT or ATTRIB DOS command.

If /ext is specified, only those files having the name extension ext are displayed. ext is 0 to 3 characters. Example: DIR,1,/CMD will list all files having extension CMD such as EDTASM/CMD.

If both U and /ext are specified, then only files satisfying both conditions are listed.

When the display screen is full, DIR displays a '?' and waits for the user to respond ENTER to continue or BREAK to terminate the DIR function.

If P is specified, the directory information is sent to the printer rather than to the display. Caution, if the printer is not ready, the system will hang waiting for it.

If $ is specified, DIR will ask for the mount of the target diskette before the listing and will ask for the remount of the system diskette before exiting. $ should only be used when drive dn1 =0. There is no provision for changing the PDRIVE specifications internal to the DIR command.

The user must remember that if dn1 is not specified, the default drive number is that specified by SYSTEM option AN which is not necessarily 0.

DIR command examples:

1. DIR 0
   Display the name and name extension of all non-system, non-invisible files on the diskette currently mounted in drive 0. The files will be listed four per display line.
2. DIR 0,S,I,P
   Same as the previous example except that system and invisible files are also listed and that the listing is sent to the printer instead of the display.
3. DIR 1,/DAT,U
   Display the name and name extension of all of the current drive 1 files that are marked as updated and have name extension DAT.
4. DIR 2,A
   All of drive 2's non-system, non-invisible files are displayed, one file per display line. This display will usually involve more than one display page with the user stepping from one page to the next by pressing ENTER and, if desired, terminating the DIR function by pressing BREAK.
5. DIR $0
   Same as example 1 except the system will ask for the mount of the target diskette on drive 0 and when DIR is done, it will ask for the remount of the system diskette.

DO,filespec1[,sectionid]

The DO command executes exactly the same as the DOS command CHAIN (see section 2.9).

DUMP,filespec1,start-addr,end-addr[,entry-addr[,rel1oc-addr ] ]

The DUMP command writes main memory image data from main memory to the file fiiespecl, starting with the byte at start-addr and ending with the byte at end-addr.

Start-addr, end-addr, entry-addr and relloc-addr are each numeric values less than 65536 decimal or 10000 hex. If the value is hexadecimal it must be suffixed with a H (i.e. 8000K); otherwise the value is considered decimal. Start-addr and relloc-addr may be any value 0 - 0FFFFH.

This command operates in two modes, depending on the entry-addr value. If the entry-addr value = 65535 (0FFFFH), then an exact image of memory is dumped.

The start-addr value is stored in the file's first 2 bytes, and the rest of the file is the memory dump without any interspersed control bytes. This memory dump file may be displayed or printed via SUPERZAP's DMDB feature, thus allowing debugging to occur later or on another TRS-80 computer.

If entry-addr is less than 65535 (0FFFFH) or is not specified, then the specified area of memory is assumed to be machine executable code and is sent to the file in loader format so that it can be later read back in by the NEWDOS/80 loader, either for execution or simply for load (see LOAD command). If entry-addr is not specified, a value of 402DH (causing return to DOS READY) is used. CAUTION!! If the user attempts to run or load a file whose start-addr is less than 5200H, DOS will be clobbered.

relloc-addr specifies where the start-addr to end-addr range of bytes is to be loaded to by the LOAD command or when the program file is executed. During write of the object file, the value (relloc-addr) - (start-addr) is added to every load address placed in the object file. This value is also added to the entry-addr if entry-addr is within the start-addr to end-addr range. The actual object code is NOT altered; only the loader control information is.

If filespec1 does not specify an name extension, one is not automatically supplied as is done in TRSDOS.

DUMP command examples:

1. DUMP,PROGRAM/CMD:1,5200H,9ABCH,54EDH

dumps the contents of memory from and including 5200H to and including 9ABCH to the file PROGRAM/CMD to exist on drive l's current diskette. The dump will be in loader format with entry address equal to 54EDH. Subsequently, the file may be loaded back into memory via the DOS command:

LOAD,PROGRAM/CMD

or executed via DOS command:

PROGRAM[,parameters]

2. For this next example, assume that a user program is looping for some reason or has crashed, the personnel to debug the problem are not immediately available, and it is necessary to continue using the computer for other purposes. If a spare formatted diskette is available with sufficient free space, and if 'DFG' can activate MINI-DOS or if the computer is already at DOS READY, then issue the following command:

DUMP,TROUBLE/MEM:2,0,65535,65535

which will dump 65536 bytes of main memory, including ROM, the display, and all of RAM to file TROUBLE/MEM. The first 2 bytes of the file will contain 0000H which is the dump start address; the rest of the file is the memory contents with no interspersed control characters. Once the dump is completed, the operator should set aside the dump diskette for later use by the debugging personnel, optionally press reset, and go on with other tasks. At some later time, debugging personnel can inspect the problem using SUPERZAP's DMDB feature to display or print the contents of file TROUBLE/MEM as if it were actually in memory at the current time. The debugger must remember that the DOS areas 4000H - 51FFH were altered by DOS actions, including DUMP, after the error occurred and before the dump actually occurred.

ERROR,xx

Displays the DOS error MSA associated with the error number xx where xx is an integer between 0 and 63. Example:

1. ERROR,24
   will display 'FILE NOT IN DIRECTORY'.

FORMAT,dn2[=tc2],name2,mm/dd/yy,password3[,N][ ,Y][,NDMW][ ,DDND][ ,ODN=name1 ][ ,KDN] [ ,DDSL=ln1 ][ ,DDGA=gcl] [ ,DPDN=dn4] l,PFST=tn3[,PFTC=tc3]]

Diskettes as they are received from the manufacturer cannot be used with NEWDOS/80. They must first be magnetically divided into tracks with each track divided into sectors of 256 bytes each. Between 15 and 30 percent of the diskette's bytes are used as format control information and are not available to contain user data.

The DOS command FORMAT does this diskette formatting, setting up the tracks and sectors properly and building the two system files, BOOT/SYS and DIR/SYS, required on every diskette. When done, the diskette is ready to be used as a data diskette with NEWDOS/80.

Formatting can also be done as part of the COPY command, formats 5 and 6 (see section 2.14).

FORMAT cannot be executed under MINI-DOS.

In NEWDOS/80 version 2, a track's sectors are read immediately after the track is formatted and before the disk arm is stepped to the next track. Then, after all tracks are formatted, if SYSTEM option BM = Y, the entire diskette is read during the VERIFYING phase. However, if BM=N, this verifying phase is skipped. The user can decide whether or not the verify-at-track format is sufficient and set option BM accordingly.

FORMAT does not allow the user to specify tracks to be locked out, and when an unverifiable sector is encountered, the associated track's lockout byte is not set to FF to indicate lockout. The lockout table is in the standard diskette directory only for compatibility with TRSDOS; NEWDOS/80 does not use it. Remember, NEWDOS/80 does not account for tracks in the directory, it accounts for lumps which can span tracks. NEWDOS/80 operates under the philosophy, however wrong, that if a diskette cannot be fully formatted it should be

FORMAT requires all parameters be specified in the command. It does not prompt the user for any.

dn2 is the number of the destination drive to be used during format. Name2 is the name to be assigned to the diskette unless KDN is specified to retain the old name, in which case name2 must still be specified but will be ignored. mm/dd/yy is the date to be assigned to the diskette unless KDD is specified as the diskette date, in which case mm/dd/yy must still be specified but will be ignored. Password3 is the password to be assigned to the diskette. Passvord3 must conform to the rules for passwords.

Null parameters may be used to invoke default values for diskette name, date and password, using the name NOTNAMED, the system date and the password PASSWORD respectively. Any combination of the 3 null values may be used but where used the null parameters must be delimited by commas, not spaces. See examples 2, 3 and 4 below.

Since FORMAT and COPY share the same NEWDOS/80 code wherever possible, the specifications for the optional parameters are nearly the same as those specified for COPY, formats 5 and 6, the main difference being that only a format is done rather than both a format and a copy. The reader should read the sections for COPY, formats 5 and 6 (see section 2.14) to basically understand FORMAT'S optional parameters. Only the differences and two additional options will be given here.

N is the default if neither it nor any of its mutually exclusive keywords are specified.

If =tc2 specified, the diskette will be formatted with tc2 number of tracks; otherwise the diskette will be formatted with the default number of tracks for that drive (see PDRIVE command). If =tc2 value is greater than the number of tracks the drive can handle, format will probably hang trying to step to the non-existent track.

PFST=tn3 and PFTC=tc3 optional parameters are added to allow the formatting of a range of tracks rather than the entire diskette. If PFST is specified, =tc2 must not be specified, and if PFTC is specified, PFST must be specified. PFST means Partial Format Starting Track, and tn3 specifies the first track to format. If PDRIVE TI flags J or K are applicable for drive dn1, DOS will add one to tn3. PFTC means Partial Format Track Count, and tc3 specifies the number of consecutive ascendingly numbered tracks to format. If PFTC is not specified and PFST is specified, tc3 is assumed equal to 1. After tc3 number of tracks have been formatted and if SYSTEM option BM = Y, the entire diskette will be verified. If this full diskette verify is a problem, cancel the format after verify starts (by pressing up-arrow); remember, each track's sectors were already verified once immediately after the track was formatted.

FORMAT command examples:

1. FORMAT,0,AAA0,08/01/81,PSWD,Y
   The diskette to be mounted, at DOS's request, on drive 0 will be formatted according to the PDRIVE specifications current for that drive. DOS does not care whether the format diskette previously contained data or not. The diskette is named AAA0, dated August 1, 1981, and receives PSWD as its master password.
2. FORMAT,0,,,,Y
   This example is identical to the previous example except that default values are used for the diskette name, date and password. The diskette is named NOTNAMED, is dated with the current system date and is assigned PASSWORD as its password.
3. FORMAT,1,XXX,,PSWD,N,NDMW,DPDN=4,DDSL=40,DDGA=6
   The diskette already mounted on drive 1 must not contain recognizable data. It is formatted according to the system diskette's PDRIVE drive 4 specifications (and not according to the existing drive 1 specifications). It is assigned name XXX and password PSWD; its date is taken from the current system date. The directory starts at the beginning of lump 40 and consists of 6 granules (allows for a maximum of 222 files). Due to NDMW, DOS does not ask for the mount of the format diskette nor does it allow error retry.
4. FORMAT,1,,,,Y,PFST=22,PFTC=2
   Suppose a power failure destroyed the format of tracks 22 and 23 on a diskette. Using SUPERZAP, you have verified that indeed SECTOR NOT FOUND error occurs on at least one sector on each of those tracks and, using the CDS or SCOPY functions of SUPERZAP, you have saved in free sectors elsewhere, either on this diskette or another, the readable sectors of those two tracks. Executing this FORMAT command will cause only those two tracks to be reformatted; the rest of the information on the diskette is not affected. When done, you can now move back the saved sectors and recreate the. ones that were not savable.

FORMS[,WIDTH=xxx][,LINES=yyy]

The FORMS command optionally changes some printer parameters and always lists out the printer parameters.

WIDTH=xxx specifies the number of characters per line where XXX must be a value between 9 and 255. If WIDTH is not specified, the number of characters per line is not changed.

LINES=xxx specifies the number of lines per page, and must be a value between 1 and 254, where 254 indicates no limit on the lines per page. If LINES is not specified, the lines per page value is not changed.

FORMS command examples:

1. FORMS,WIDTH=80,LINES=60
   character per line is set to 80 and lines per page to 60.
2. FORMS,WIDTH=255,LINES=254
   Unlimited characters per line and lines per page.
3. FORMS
   Displays current values for characters per line and lines per page.

FREE[,P]

For each drive with a diskette mounted, FREE will display the drive number, the diskette name, the diskette date, the number of tracks for the diskette, the number of free FDEs and the number of free granules.

If P is specified, the information will be sent to the printer instead of the display.

FREE command examples:

1. FREE
   For each diskette currently mount the number of free granules and free directory entries is listed on the display.
2. FREE,P
   Same as above except the listing is sent to the printer.

HIMEM[,addr1]

DOS maintains a high memory address in the two bytes at Model I location 4049H (Model III location 4411H). This high memory value is used by COPY, BASIC, EDTASM, DISASSEM and LMOFFSET as the upper limit of the memory they can use. User programs should also use this 2 byte HIMEM value as their upper limits. Caution! The loader does not use HIMEM as its upper limit during program load.

If no parameters are specified, the HIMEM command displays in hexadecimal the current high memory value.

If addr1 is specified, the DOS high memory address is set to addr1 which must be an integer between 28672 and 65535 decimal (7000H - 0FFFFH hexadecimal).

HIMEM command examples:

1. HIMEM
   Displays the current DOS high memory address.
2. HIMEM,49000
   Set DOS's high memory value to 49000 (0BF68H).

JKL has no parameters. This command uses the same routine used by the 'JKL' triple key function (see section 4.5). JKL simply dumps the display contents to the printer. If system option AK=Y, hex codes >= 80H (which includes the graphics) will be transmitted unchanged; otherwise a period will be substituted for them. Hex codes < 20H will be displayed as periods. Pressing BREAK during JKL print will terminate the JKL function.

JKL's main use will be either via CMD"JKL" from BASIC or via DOS-CALL from a user program.

KILL,filespec1

This command deletes a file from a diskette. The file is no longer accessible by normal methods and is no longer known to DOS.

The file filespec1 is deleted from the current diskette mounted on the specified drive. If a drive number was not specified, then all mounted diskettes are searched, starting with the diskette on drive 0, and the delete is done on the 1st file found having the specified name and name extension.

KILL action is as follows:

1. If the file was allocated file space on the diskette, the space is released, and becomes available for subsequent assignment to other files. The file's data, if any, on the diskette is not altered by the KILL. This data, though no longer accessible, is not written over until the associated file space is reassigned to another file and those sectors actually written to.
2. The file's FPDE and any owned FXDEs are freed by zeroing bit 4 of the 1st byte of each and by zeroing the associated HIT sector byte for each. Except for that bit 4, none of the associated FPDE and FXDEs are altered by normal DOS operation until that FDE is reassigned to another file by DOS.

If the user has inadvertently killed a file that shouldn't have been, since neither the associated FDE's or the diskette space used by the file is changed by DOS until DOS has a need to, it is barely possible to reconstruct the FPDE and FXDEs and reallocate the space. To do this, you must be extremely familiar with the workings of the directories; do not call Apparat as this is a major undertaking and not something that can be quickly taught. If you don't know how to do it, forget it!!!!!!!!

If you have more than a few files to delete at one time from a diskette, use the PURGE command.

KILL command examples:

1. KILL XXX/BAS:1
   The file XXX/BAS on the diskette mounted on drive 1 is killed.
2. KILL YYY
   Starting with drive 0, mounted diskettes are searched until file YYY is found on one of them. That file is then killed. If other mounted diskettes also contain a YYY file, the other YYY files are not killed.

LC[,yn]

LC or LC,Y sets the keyboard lower case a-z toggle switch to accept a - z without change.

LC,N sets the keyboard lower case a - z toggle switch to change lower case a - z to upper case A-Z.

For the Model I, the LC command has no effect unless the lower case driver is active (see LCDVR command).

LCDVR[,x[,s]]

In NEWDOS/80 version 1, the lower case driver that processed keyboard lower case alphabetic and which sent lower case displayed characters to the display was a separate program that executed from high memory. In version 2, the lower case driver is an integral part of the Model I NEWDOS/80.

If x = Y, the lower case driver routine is activated, and if x = N, the routine is deactivated. When the lower case driver routine is active:

1. Keyboard input a - z characters are processed according to the a - z toggle switch.
2. ASCII codes 96 - 127 (60H - 7FH) are displayed as their proper characters and are not changed to 64 - 95 (40H - 5FH) by the ROM display routine.

The second parameter is meaningful only when x = Y, performs the same as the first parameter of LC command, initially setting the a - z toggle switch to accept a - z (if s = Y) or convert a-z to A-Z (if s - N).

Once the lower case driver is activated, pressing shift 0 will switch the driver back and forth between accepting lower case letters and converting lower case letters to upper case. Further, DOS command LC may be used to explicitly set one or the other of those states.

To use the lower case driver, NEWDOS/80's keyboard and display intercept routines must be enabled. Other routines (excluding ROUTE) that disable these NEWDOS/80 functions will also disable the lower case driver (one example is using the circular buffer in the spooler).

If no parameters are specified, the command is assumed to be LCDVR,Y,N.

This lower case driver operates somewhat differently than the LCDVR program supplied with Version 1. In Version 1, if lower case a-z was being converted to upper case A-Z, then upper case A-Z was also being converted to lower case a-z. Version 2 does not convert upper case A - Z. to lower case a-z; instead a true capital letter lock is done.

LCDVR command examples:

1. LCDVR
   The lower case driver routine is activated and the lower case switch is set to convert lower case a - z to upper case A - Z.
2. LCDVR,Y,Y
   The lower case driver routine is activated, and the lower case switch is set to accept lower case a - z without modification.
3. LCDVR,N
   The lower case driver routine is deactivated.

LIB requires no parameters. It displays the library commands of NEWDOS/80. Commands FORMAT, COPY and APPEND execute in memory 5200H and up, and, along with CHAIN, cannot be executed in MINI-DOS. The other commands execute from the DOS overlay area, 4D00R-51FFH, and, except for CHAIN, can be executed under MINI-DOS.

LIST,filespec1[,start-line[,line-count]]

This command sends the contents of file filespec1 to the display. Though file filespec1 need not be a text file, if it is not, the resulting display will not be very meaningful. Examples of text files are BASIC programs saved with the A option, BASIC files written using PRINT, assembler, FORTRAN and COBOL source text files, SCRIPSIT files saved with the A option and Electric Pencil files. To list a non-text file, use. SUPERZAP.

No check is made on the character representations except to modulate characters whose hexadecimal values are between 80H and FFH into the range 00H to 7FH and to replace with a period all characters whose hexadecimal value is less than 20H or greater than the high ASCII character value specified by the SYSTEM option AX.

If start-line (decimal value 1 - 65535) is specified, listing will start with that line where a line is considered to end with the ENTER or EOL character 0DH.

If line-count is specified, then the number of lines displayed is limited to either line-count or the number of lines in the file from the start point, whichever is less. If line-count is specified, start-line must also be specified.

Pressing right arrow will cause a display pause when hex char 0DH is encountered or after 256 bytes have been displayed, whichever comes first. Pressing ENTER will continue the displaying. Pressing up-arrow will terminate LIST.

Aside from just listing a file, LIST is useful where text files maintain a date/time stamp near the beginning. If the user has multiple copies of a text file, it may be necessary to look at the file beginning to determine which copy is the most recent.

LIST command examples:

1. LIST,BASEPROG/BAS
   displays the entire contents of file BASEPROG/BAS.
2. LIST,XXX,1
   displays the first 6 lines of file XXX.
3. LIST,YYY: 1,200
   displays the contents of file YYY from the 200th line to the end of the file.

LOAD.filespec1

This command loads the Z-80 machine language file filespec1 into RAM, and stores its entry address into the two bytes at 4403H (17411 decimal). The file must be in proper loader format, such as created by DUMP or EDTASM. The load proceeds using control data from the file. If the file loads over any part of the resident DOS (4000H - 4CFFH) or its overlay area (4D00H - 51FFH), serious and maybe file damaging trouble will occur; with luck, the system will hang.

LOAD is used when a program or data is to be loaded into RAM for later use by other programs. An example is loading programs which will be invoked via BASIC'S USR function. Remember, the entry address is stored in the two bytes at 4403H (17411 decimal); this is not done in TRSDOS.

LOAD command examples:

1. LOAD,OVERLAY/OBJ:1
   The object code module OVERLAY/OBJ is loaded into main memory from the diskette mounted on drive 1. The load control information within file OVERLAY/OBJ determines what is to be loaded and where in main memory it is to be loaded.
2. Suppose that BASIC does not use all of high memory and that a BASIC program wishes to load the program USR3PGM/0BJ into high memory and later execute it as the BASIC USR3 function. Executing the BASIC statements:

CMD"LOAD,USR3PGM/0BJ"

DEFUSR3 = (PEEK(17411) + 256 * PEEK(17412) - 65536

will set this up.

MDBORT has no parameters. It should only be executed when NEWDOS/80 is in MINI-DOS state. MINI-DOS state is terminated, the pre-MINI-DOS state purged and the system goes to DOS READY.

The purpose of MDBORT is to provide for the situation where the operator does not want to continue the main program which was interrupted by the simultaneous depression of the D, F and C keys (which invoked MINI-DOS).

MDCOPY,filespec1[,TO],filespec2

The regular COPY command cannot be executed under MINI-DOS. MDCOPY gives the user a restricted and quite slow form of file copy which does execute under MINI-DOS.

MDCOPY copies the contents of file filespec1 to the new or existing file filespec2. File filespec1 is not altered, and the previous contents of file filespec2, if any, are lost. Filespec2 may not be foreshortened as is allowed for COPY.

MDCOPY command example:

1. MDCOPY XXX/DAT:0 YYY/DAT:1
   The contents of file XXX/DAT on the diskette currently mounted on drive 0 is copied as file YYY/DAT onto the diskette currently mounted on drive 1.

The message MSA is not redisplayed if the PAUSE command itself was displayed. If the PAUSE command was not displayed, as occurs if it is executed under DOS-CALL, the message MSA is displayed. In any event, the message PRESS "ENTER" WHEN READY TO CONTINUE is displayed on the next line. DOS then waits for the user to press the ENTER key. The PAUSE command is one of the four ways of causing a pause in chaining, and can also be used when a series of commands in main memory are being executed by a series of DOS-CALLs.

MDRET has no parameters. The system exits MINI-DOS state and continues the main program at the point where it was interrupted by the invocation of MINI-DOS (simultaneous depression of the D, F and G keys). If the cursor was displayed before 'DFG', it will be redisplayed. If the 'DFG' interruption occurred while the key input buffer contained a partial input record, that partial record is still there even though it is no longer displayed. The user should continue keying exactly where he/she left off.

If the invocation of MINI-DOS occurred during the timer interrupt rather than the key intercept, one or more of D, F or G may appear as spurious input keys after MDRET is executed. The user should backspace over them. The user and DOS have no control over these spurious input chars; therefore DFG should not be pressed when a program is in text overwrite mode, such as SCRIPSIT or Electric Pencil; instead go into command mode where the spurious characters can be backspaced over without damage to the text.

PAUSE,msg

The message MSA is not redisplayed if the PAUSE command itself was displayed. If the PAUSE command was not displayed, as occurs if it is executed under DOS-CALL, the message MSA is displayed. In any event, the message PRESS "ENTER" WHEN READY TO CONTINUE is displayed on the next line. DOS then waits for the user to press the ENTER key. The PAUSE command is one of the four ways of causing a pause in chaining, and can also be used when a series of commands in main memory are being executed by a series of DOS-CALLs.

PAUSE command example:

1. PAUSE,MOUNT DISKETTE LABELED "PRIMARY" ON DRIVE 1.
   This message will appear on the display and will be followed on the next display line by the message PRESS "ENTER" WHEN READY TO CONTINUE. DOS waits for the user to press ENTER which presumably he/she will do after the proper diskette has been mounted in drive 1. DOS doesn't check to see if the user has done what was requested; all DOS does is wait for the ENTER.

PDRIVE[, password1: ]dn1, [ dn2 [ =dn3 ]][, TI=type1 ] [, TD=type2 ]
[,TC=tc1] [ ,SPT=scl][,TSR=rcl][,GPL=gc2]{,DDSL=ln1][,DDGA=gcl][ ,A]

NEWDOS/80 has limited capabilities for operating with a mixture of 5 inch disk drives and to a lesser extent 8 inch disk drives. PDRIVE is the command method used to inform NEWDOS/80 of a particular physical drive's characteristics.

Each PDRIVE command lists the resulting specifications for 10 drives even though the actual number of drives eligible for I/O is limited by the SYSTEM option AL and in no case exceeds 4. Those drives within the range of SYSTEM option AL are flagged on the PDRIVE display by an asterisk suffixed to the drive number. The specifications for the 10 drives is maintained on the system diskette mounted on drive dn1. For efficiency reasons, DOS normally uses drive specifications from a table it has in main memory. This main memory PDRIVE table contains specifications for 1 to 4 drives, depending upon the SYSTEM option AL value, and is automatically reloaded from the drive 0 diskette at power on and reset if and only if the specifications for all 10 drives are error free (otherwise the reset hangs). This table is also immediately reloaded by a PDRIVE command specifying the A parameter (see below).

Drive dn1 is the drive containing the system diskette whose control information (in the 3rd sector) is being updated. Drive dn2 indicates which physical drive of the 10 represented in the control information sector on drive dn1 is having its control information updated.

For example, if the PDRIVE command is PDRIVE,1,4,TC=80 then the diskette on drive 1 is read to obtain the PDRIVE control information and is updated to contain the new drive 4 specification. Drive 1's PDRIVE control information contains the specifications for ten drives, dn2 values 0 through 9, and it is the fifth drive's information (for dn2 = 4) that is changed. The specifications for the other nine drives are not changed.

If passwords are enabled, then password1 must be specified and be the master password for the diskette on drive dn1. Otherwise password1 may be left out of the command.

Control data is changed only for the parameters specified; parameters not specified are not changed. If any errors are displayed, the dn1 diskette must NOT be used as the system diskette during a reset/power-on until the errors are corrected.

PDRIVE,dn1 will list the 10 PDRIVE specifications contained in the control data on the system diskette mounted on drive dn1.

dn2 must be specified if any other optional parameters except A are specified. If dn2 is specified, it must be the 1st parameter following dn1.

dn2=dn3 causes drive dn2 to assume the PDRIVE specifications of drive dn3. This is done before any other optional parameters are interpreted.

TI=type1 specifies the type of disk drive interface. type1 consists of one or more alphabetic letter flags chosen from the list below. For the Model I, one and only one of flags A, B, C or E must be chosen. For the Model III, one and only one of flags A or D must be chosen. The other flags are optional depending upon the interface. Certain flags are inter-drive mutually exclusive meaning that for a given drive dn1, if one dn2 drive specifies a flag that is inter drive mutually exclusive with another flag, then another dn2 drive may not specify the excluded flag. For now, flags B, C and E are interdrive mutually exclusive for the Model I.

Flag A means the standard disk interface is to be used for diskette I/O for this drive. For the Model I this interface supports drive types A and C. For the Model III this interface supports drive types A, C, E and G.

Flag B (Model I only) means that an OMNIKRON mapped type interface is installed and is to be used for I/O for this drive. This interface supports drive types A, B, C and D.

Flag C (Model I only) means that a PERCOM doubler type interface is installed and is to be used for I/O for this drive. This interface supports drive types A, C, E and G.

Flag D (Model III only) means that an Apparat disk controller type interface is installed and is to be used for I/O for this drive. This interface supports drive types A through H.

Flag E (Model I only) means that an LNW type interface is installed and is to be used for I/O for this drive. This interface supports drive types A through H.

Flag H means head settle delay is to be done whenever DOS changes from another drive to this drive. For Model I and Model III 5 inch drives, The -heads for all 5 inch drives are loaded when the motors go on, and this extra time delay is NOT needed. Flag H is needed for 8" drives.

Flag I means the lowest numbered sector on each track is sector 1. This is the normal state for Model III TRSDOS diskettes. If flag I is not specified, the lowest numbered sector on each track is assumed to be 0, which is the state for the Model I and for NEWDOS/80 on the Model III.

Flag J means the track numbers start from 1 . If flag J is not specified, track numbers are assumed to start from 0, which is the standard state for the Model I and the Model III.

Flag K means track 0 is formatted (or is to be formatted) in density opposite to that of the diskette's other tracks. This makes track 0 unavailable for normal I/O. Flag J is implicitly set by flag K. The purpose of formatting track 0 in opposite density is to allow a double density (Model I) or single density (Model III) SYSTEM diskette to be booted up. The Model I ROM must be able to read the boot sector in single density, and the Model III ROM must be able to read the boot sector in double density. Setting flag K causes FORMAT and COPY with format to format track 0 in the opposite density and to store the required boot sector onto that track for the ROMs to use. With flag K set, normal DOS I/O to track 0 actually goes to track 1, 1 to 2, etc. Flag K must be specified for a drive that is to read a double density diskette created by the PERCOM type doubler interface under NEWDOS/80 version 1 or any other DOS except NEWDOS/80 version 2 or higher. For NEWDOS/80 version 2 Model I, double density data diskettes do not have to reserve track 0 for opposite density if those diskettes will never be used on a drive 0 whose PDRIVE specifies double density. Flag K must NOT be specified for standard Model III diskettes, unless for some reason the user wants a single density system diskette on the Model III or is making a double density diskette to be read on the Model I that does not have NEWDOS/80 version 2. When flag K is specified, then TC must specify one less track than would be specified if flag were not specified. Further, due to the differing sequence in which consecutive sectors are stored on the diskettes, double sided, double density diskettes created under the patched NEWDOS/80 version 1 are not readable under NEWDOS/80 version 2. To transfer files on those diskettes to Version 2, they must first be moved (using Version 1) to either single sided (either density) or double sided, single density diskettes.

Flag L means two step pulses between tracks. This allows a 35 or 40 track diskette to be read on an 80 track drive. Writing can also be done in this manner, but the 35 or 40 track drives have trouble reading some of the sectors so writing is not recommended.

Flag M means the diskettes are standard TRSDOS Model III diskettes. Flag M implies flag I. The COPY DOS command is the only function within NEWDOS/80 that will honor or even notice a TRSDOS Model III diskette as distinct from a NEWDOS/80 diskette, and even this will not occur unless flag M is set.

Flags F through G and N through Z are reserved for future definition.

TD is the Type of Drive specification. The definitions are:

1. TD=A 5 inch, single density, single sided drive

2. TD=B 8 inch, single density, single-sided drive

3. TD=C 5 inch, single density, double sided drive

4. TD=D 8 inch, single density, double sided drive

5. TD=E 5 inch, double density, single sided drive

6. TD=F 8 inch, double density, single sided drive

7. TD=G 5 inch, double density, double sided drive

8. TD=H 8 inch, double density, double sided drive

If a CPU speed up module is installed in the computer that reverts to normal CPU during disk I/O, this reversion must not slow the CPU speed to less than the original rated CPU speed for that model. NEWDOS/80's disk I/O loops, especially for the Model 1 for drive types B, D, E and G, cannot tolerate any reduced CPU speed below the original speed. In limited testing and with SYSTEM option BJ properly set, NEWDOS/80 Version 2 has run disk I/O successfully without the need to turn off the CPU speed; however, Apparat does not guarantee such performance.

TD=F and TD=H require a CPU speed up module installed in the computer which at least doubles the CPU's speed during disk I/O.

For drive types C, D, G and H, the current NEWDOS/80 interfaces (TI flags A, B, C, D or E) consider a double sided diskette as a single volume (i.e., only one directory) with each track having its lower numbered sectors on the first side and the higher numbered sectors on the second side. Pin 32 is used to select the 2nd side (special cables required), and any drive on the cable that shunts pin 32 over as a drive 3 select must have that shunt wire cut to prevent that drive from being selected when another drive's 2nd side is being selected. Double sided, double density 40 and 80 track drives have been used on the Models I and III under NEWDOS/80 Version 2.

One of the strongest reasons Apparat never supported double density in Version 1 was that most drives did not work reliably well in double density. Whether this was the fault of the drives, the data separator or the controller was never really ascertained. Over the last nine months things have improved somewhat, but double density is still not as reliable as single density and probably never will be. Apparat was informed that the two byte pattern 6DB6 is a much better "worst case" double density pattern than the E5's used in single density, and indeed the 6DB6 pattern is such. In fact, it is such a good "worst case" condition that a good percentage of certified double sided, double density diskettes will fail format. To many users, this will prove intolerable and they will want to apply the ZAP that goes back to the E5 pattern, if it is not already applied. However, using the E5 pattern in double density means that the user will increase the probability that a diskette that formats successfully will at some future time fail.

TC=tc1 specifies the number of tracks on the disk, excluding track 0 if TI flag K is set. If flag K is not set, TC=35 for a 35 track drive, TC=40 for a 40 track, etc. If flag K is set, then TC=34 for a 35 track drive, TC=39 for a 40 track, etc.

SFT=scl specifies the number of sectors per track. For double sided, single volume diskettes (TD = C, D, G or II), scl must be twice what it would be if single sided diskettes. scl may be any value from 1 to the maximum number of 256 bytes sectors the track can physically hold. For each of the above specified drive types, the maximum number of sectors per track is: A=10, B=17, C=20, D=34, E=18, F=26, G=36 and H=52.

TSR=rcl specifies the track stepping pulse time code the controller uses for this drive, rcl is a value from 0 to 3 and becomes part of the SEEK, STEP and RESTORE commands sent to the controller. For the Model I and III standard controllers, TSR=0 gives 5 ms stepping, TSR=l gives 10ms stepping, TSR=2 gives 20ms stepping and TSR=3 gives 40ms stepping. TSR=3 was the original standard for the Model I, with some users using TSR=2 or TSR=1 for certain drives. The Model III appears to use TSR=0 as standard. If you are having drive trouble, the safest setting is TSR=3.

GPL=gc2 specifies the number of granules per lump where gc2 is a value between 2 and 8. In TRSDOS for the Model I and III and the older versions of NEWDOS, disk space allocation was done via granules (5 sectors per granule on the Model I and 3 per granule on the Model III) and tracks (2 granules per track on the Model 1 and 6 granules per track on the Model III). In NEWDOS/80 version 2, for both the Models I and III, there are still 5 sectors per granule, and 2 to 8 granules per lump (not track). Wherever a track number appeared in the directory (in the GAT sector and in the FDE two byte extent elements), it has been replaced with a lump number. Doing so allows a granule to start in one track and end in another and allows double density and 8 inch diskettes to maximize the number of sectors per track while keeping the same directory format. GPL=2 maintains compatibility with the old 35 track single density diskettes, as the directories will be exactly the same and transferable back and forth between the Model I TRSDOS and NEWDOS versions before NEWDOS/80 version 2. However, by going to GPL=8 the directory can now accommodate 192 x 8x5= 7680 sectors or 1,966,000 bytes which might suffice for a while.

DDSL=ln1 is the logical equivalent of and replacement for the DDST parameter used in NEWDOS/80 version 1. lnl specifies the number of the lump at whose first sector is to contain the directory's 1st sector. This value is stored in the boot sector 3rd byte during diskette format and is used when necessary to find the directory. It is also used during diskette format to determine where to put the directory. In the older systems, the 3rd byte of the boot sector contained the track number in whose 1st sector the directory started. Since tracks are not used in space allocation and control in NEWDOS/80 version 2, the 3rd byte of the boot now contains the number of the lump in whose 1st sector the directory starts. To determine the relative sector number of the directory's 1st sector (the GAT sector), access the boot sector's 3rd byte and multiply that value by 5 times GPL. DDSL=17 maintains compatibility with the standard 35 track, single sided, single density diskettes. DDSL should be set to the value used for the DDST parameter in NEWDOS/80 version 1.

DDGA=gcl specifies the default number of granules to be allocated to the directory when it is created during format, where gcl is a value between 2 and 6. DDGA=2 should be specified for standard 35 track, single density, single sided compatibility. gcl > 2 allows the user to have more than 62 files on a data diskette with the maximum being 222 files.

A specifies that if and only if no errors were found during the checking of the specifications for all the drives, then the specifications for SYSTEM option AL number of drives is loaded into the main memory PDRIVE table to immediately become the controlling data for those drives; this eliminates tin-need for a reset. If parameter A is specified, dn1 must = 0.

PDRIVE is executable under MINI-DOS.

PDRIVE command examples:

1. PDRIVE,dn1,dn2,TI=A,TD=A,TC=35,SPT=10,TSR=3,GPL=2,DDSL=l7,DDCA=2
   is the PDRIVE specification for a standard 5 inch, 3 5 track, single density, single sided diskette used for communication in the Model I world. This specification can also be used on the Model III to read the diskette providing the directory address marks are correct (see SYSTEM o
2. PDRIVE,dn1,dn2,TI=A,TD=*E,TC=40,SPT=18,TSR=3,GPL=2,DDSL=17,DDGA=2
   is the Model III specification (Model I, use TI=C) for a standard 5 inch, 40 track, double density, single sided diskette used for communication through out the NEWDOS/80 Model III world. Using this specification, this diskette can also be read on the Model I in a drive other than 0 if the double density interface is
3. PDRIVE,dn1,dn2,TI=AM,TD=E,TC=40,SPT=18,TSR=3,GPL=6,DDSL=17,DDGA=2
   is the Model III specification (Model I, use TI=CM or EM) for reading or writing to a TRSDOS Model III standard 5 inch, double density, single sided diskette. A 40 track, double density, single sided 5 inch diskette is the only type TRSDOS Model III diskette that NEWDOS/80 can handle. GPL=6 is mandatory. Since a TRSDOS Model III diskette cannot be formatted by NEWDOS/80, DDSL and DDGA are meaningless. In NEWDOS/80 (double density mod must be installed for Model 1), only the COPY DOS command can be used with TRSDOS Model III diskettes excepting that diskette sectors can be read/written via SUPERZAP by using the DD, DM, DTS, VDS, CDS, CDD, etc. functions that do not refer to files (i.e., don't
4. PDRIVE,dn1,dn2,TI=A,TD=C,TC=80,SPT=20 ,TSR=2,GPL=8,DDSL=20,DDGA=6
   is the specification for a 5 inch, 80 track, single density, double sided, single volume diskette with a 20ms stepping, 8 granules per lump, with the directory positioned at the diskette halfway point and maximum size directory.. For the Model III, the single density drive 0 restrictio
5. PDRIVE,dn1,dn2,TI=A,TD=G,TC=80,SPT=36,TSR=2,GPL=8,DDSL=35,DDGA=6
   is the Model III specification (Model I, use TI=C or F.) for a 5 inch, 80 track, double density, double sided, single volume diskette to use 20ms stepping, 8 granules per lump, maximum size directory positioned at the diskette halfway point. For the Model 1, the double density drive 0 restrictio
6. PDRIVE,dn1,dn2,TI=CK,TD=E,TC=39,SPT=l8,TSR=3,GPL=2)DDSL=17,DDGA=2
   is the Model I specification (Model III, use TI=AK) for 5 inch, 40 track, double density, single sided diskette that has track 0 formatted in single density, hence only 39 tracks available for regular use. This specification will handle double density diskettes formatted by TRSDOS and NEWDOS/80 version 1 running under the PERCOM doubler. This specification will also be used when generating a double density diskette to be the system diskette in drive 0 for the Model I. For LNW Model I interface,
7. PDRIVE,dn1,dn2,TI=CK,TD=G,TC=79,SPT=36,TSR=3,GPL=8,DDSL=35,DDGA= 6
   is the Model J specification (Model III, use T1=AK) for a 5 inch, 80 track, double density, double sided, single volume diskette that has track 0 formatted single density. For the LNW Model I. interface, u
   Warning!!! Double sided, double density diskettes used on the patched NEWDOS/80, version 1 are not useable on Version 2 (see TI flag K di
8. PDRIVE,dn1,dn2,TI=AL,TD=A,TC=3 5,SPT=10,TSR=3,GPL=2,DDSL=17,DDGA=2
   is the specification for a 5 inch, 35 track, single sided, single density diskette that is to be read on an 80 track drive. The 80 track drives step only half as far as the 35 and 40s for each data track; setting flag L causes 2 steps to be taken for each data trac
9. PDRIVE,dn1,dn2,TI=BH,TD=B,TC=77,SPT=17,TSR=3,GPL=3,DDSL=17,DDGA=6
   is the Model I specification for an 8 inch, 77 track, single sided, single density diskette. Note, NEWDOS/80 version 1 used SPT=15 and an implied GPL=3, and to read those diskettes, SPT=15 and GPL=3 must be used. It is recommended that a COPY be done to convert those diskettes to SPT=17, thus gaining 12% more diskette space. Flag H causes head load settle delay to be used, required for most 8 in
10. PDRIVE,dn1,dn2,TI=BH,TD=D,TC=77,SPT=34,TSR=3,GPL=8,DDSL=17,DDGA=6
    is the Model I specification for an 8 inch, 77 track, single density, double sided, single volume diskette with head load settle delay
11. PDRIVE,dn1,dn2=dn3
    is the specification to cause drive dn2 to receive as its specifications those of
12. PDRIVE,dn1,dn2=dn3,TC=40,TSR=2
    is the specification to cause drive dn2 to receive as its specifications those of drive dn3 and then to apply new values for T
13. PDRIVE,0,A
    causes the PDRIVE data for SYSTEM option AL number of drives to be loaded into the main memory PDRIVE table if and only if the full display of the specifications shows
14. PDRIVE,0,dn2=dn3,A
    changes drive 0's specifications for dn2 to be those of dn3, and then performs as in the abov

PRINT, filespec1 [,start-line [, line-count ]

PRINT executes identical to LIST, excepting the listing goes to the printer instead of the display. Refer to DOS command LIST for specifications and examples.

PROT,[password1:]dn1[, NAME=name1 ]
[,DATE=mm/dd/yy][,RUF]
[,PW=password2][,LOCK][,UNLOCK]

At least one optional parameter must be specified. The target diskette is mounted on drive dn1. If passwords are enabled, password1 must be specified and must equal the diskette's master password.

NAME=name1 The diskette is given the name name1.

DATE=mm/dd/yy The diskette is given the date mm/dd/yy.

RDF Reset Updated Flags. This option turns off the updated flags for all files on the diskette. If a user backs up only those files having the updated flag on (see UPD option of COPY), executing PROT with the RUF option after the copying is completed turns off the updated flags so the files will not be eligible for a subsequent backup until the file is subsequently updated. Simply writing or rewriting one sector of the file, whether or not anything was actually changed, causes DOS to turn on a file's updated flag.

PW=password2 Password2 must conform to the rules for passwords, with null set as all blanks. The diskette receives password2 as its password.

LOCK All files of the diskette, except system and invisible files, are given the diskette master password as both their access and update passwords. If password2 specified, it is used. This feature used to be the only way a user, in a password enabled system, could get to a file whose password(s) he/ she had forgotten, if the user did know the diskette master password. It has the unfortunate drawback in that it changes the passwords for all, except system and invisible, files on the diskette; thus causing the user to reassign passwords to all the others as well as to the file whose passwords he/she forgot. An easier way is available if the user knows the password of at least one NEWDOS/80 system diskette or better still, has a NEWDOS/80 system diskette with passwords disabled (system option AA = N). With passwords disabled, the user can use ATTRIB to directly reassign new passwords to the file whose passwords are forgotten without having to affect other user files on the diskette. Then passwords can be re-enabled.

UNLOCK The access and update passwords of all of the diskette's files, except system and invisible files, are set to all blanks, meaning no passwords for those files.

PROT command examples:

1. PROT,2,RUF
   The updated flag is cleared for each file on the diskette currently mounted on drive 2.
2. PROT,QLDPSWD:1,NAME=AAB3,DATE=07/15/81,PW=NEWPSWD
   In this example, passwords are enabled; therefore the diskette's master password OLDPSWD was required. The diskette control information for the diskette mounted on drive 1 is changed such that its name is AAB3, its date is July 15, 1981 and its new master password is NEWPSWD.

PURGE,[password1:]dn1[,/ext][,USR]

The diskette mounted on drive dn1 is used for this command. If passwords are enabled, password1 must be specified and must be equal to the diskette's master password.

For each file, except BOOT/SYS and DIR/SYS, on the diskette, DOS asks the operator if the file is to be killed. If the file is to be killed, respond Y; the file will be immediately killed, as if a KILL command has been issued. If the file is NOT to be killed, respond N. Respond Q if you wish to quit the PURGE function.

/ext If this option is specified, the purge queries are limited to only those files having name extension ext where ext is 0 to 3 characters.

USE If this option is specified, system and invisible files are not included in the PURGE function.

PURGE command examples:

1. PURGE,1
   For each file, except BOOT/SYS and DIR/SYS, on the diskette currently mounted on drive 1, DOS asks if the file is to be killed. If the response is Y, the file is killed.
2. PURGE,0,/DAT
   For each file on the diskette currently mounted on drive 0 that has name extension DAT, DOS asks if the file is to be killed and does so if the response is Y.
3. PURGE,0,USR
   For each non-system, non-invisible file on the diskette currently mounted on drive 0, DOS asks if the file is to be killed and does so if the response is Y

This command causes the re-execution of the previous DOS command, excluding the command R. Example:

DIR 1 followed by R

will execute the same as if the two DOS commands had been:

DIR 1
DIR 1

The R command can not be executed from BASIC via CMD"doscmd" as that function requires that the command, excluding ENTER, must be 2 or more characters long.

The R command has no parameters and must be keyed exactly as R followed by ENTER. If more than 2 characters are keyed into the buffer and then backspaced so that DOS only sees the R and the ENTER, the previous DOS command that was residing in the command buffer will still have been altered and the R command will either fail or in rare circumstances, execute something different than what the operator expected.

If the previous DOS command is no longer intact in the DOS command buffer, the results of the R command are unpredictable.

If SYSTEM option BE = N, the R command does not execute the previous DOS command but instead simply returns to DOS READY.

RENAME,filespec1[,TO],filespec2

The diskette mounted on drive dn1 is used for this command. If passwords are enabled, password1 must be specified and must be equal to the diskette's master password.

The file filespec1 is renamed to filespec2, where filespec2 consists of only a name and optionally a name extension. If filespec1 does not specify a drive number, then all mounted diskettes are searched, and the first file encountered matching filespec1's name and name extension is renamed. RENAME change only the file's name and name extension; nothing else is changed.

ROUTE

ROUTE,CLEAR

ROUTE,devl[,dev2][,dev3]...

The purpose of the ROUTE command is to allow some flexibility from where the keyboard and/or RS-232 input is received and to where display, printer and RS-232 output is sent. This is more restrictive form of routing than is available in other DOSs.

At the conclusion of a ROUTE command, any existing routes are displayed; if none, nothing is displayed. ROUTE with no parameters does nothing except display the existing routes.

ROUTE,CLEAR clears all routes.

devl specifies the device being routed. dev2, dev3, etc. specify the device(s) being routed to (the routed-to devices) when devl is an output device or routed from (the routed-from devices) when dev1 is an input device. For the Model I, the device codes are IT for the keyboard, DO for the display, PR for the printer and NL for null (meaning nothing is transferred). For the Model III, P.I for the RS-232 input and RO for the RS-232 output are added to the above 3 codes. An input device (KB or RI) may not be routed to an output device (DO, PR or RO), and an output device may not be routed to an input device.

Whenever devl is specified, ROUTE initially clears any previously existing routes for that device and then establishes the routes specified by dev2, dev3, etc., if any.

Any of the devices dev2, dev3, etc. may also be of the form MM=addr where addr specifies the main memory location of a user routine to which devl is to be routed. The first 12 bytes of the routine are reserved for use by DOS and must not be altered by the user. Upon routing, the user routine is entered via a CALL at the 13th byte, and it is the user's responsibility to save and restore all registers, except AF, used by the routine and routines it calls. If devl is an input device, the routine returns the new byte in register A with a zero indicating there is no new input byte from that routine. If devl is an output device, upon entry to the routine, register C contains the byte being outputted.

If devl is an output device, the output byte is sent to all routed-to devices in the order given in the ROUTE command.

If devl is an input device, each routed-from device is queried in the order given in the ROUTE command. If that device supplies a non-zero byte, the queries stop and the byte is used as the input byte for the devl. If no routed-from device has an input byte, a zero is considered devl's current byte.

The maximum number of routes-to and routes-from, excluding MM=addr types, in existence at one time is four for the Model I and six for the Model III.

WARNING!!! No editing of input or output characters is done during routing. This may cause problems (i.e., display control characters causing the printers to do unpredictable things).

ROUTE command examples:

1. ROUTE,PR,DO
   Printer output does not go to the printer but instead goes to the display.
2. ROUTE,DO,DO,PR
   Display output goes to both the display and the printer.
3. ROUTE,PR,DO,PR
   Printer output goes to both the display and the printer. If the routes of both example 2 and 3 are active, the routing is equivalent to the Model III TRSDOS function DUAL.
4. ROUTE,KB,RI (Model III only)
   Keyboard input characters come from the RS-232 input device and not from the keyboard.
5. ROUTE,DO,RO (Model III only)
   Display output is sent to the RS-23 2 output device and not to the display.
6. ROUTE,PR,MM=0FE80K
   Printer output is sent to the routine at main memory location 0FE80H (the routine's actual entry point is 0FE8CH).
7. ROUTE,KB,KB,MM=0F800H
   Keyboard input comes from either the keyboard or the routine at main memory location 0F800R. Input from the keyboard has precedence.
8. ROUTE,PR,NL
   Printer output is discarded.
9. ROUTE,PR All
   routing for the printer is dissolved. Printer output goes to the printer.
10. ROUTE,CLEAR All
    routes are dissolved, and all devices are returned to their normal paths.

SETCOM[ ,OFF] [ ,WORD=wl] [ ,BAUD=br]
[ ,STOP=sb] [ ,PARITY=pp]
[ ,WAIT] [ .NOWAIT]

The SETCOM command optionally changes the state of the RS-232 interface and always displays the state. For RS-232 discussion, see chapter 8 of the Model III Operation and BASIC Language Reference Manual. The SETCOM command affects only the standard RS-232 control blocks and routines.

If OFF is specified, the RS-232 interface is turned off. No other optional parameters may be specified.

If any of WORD, BAUD, STOP or PARITY is not specified, the state for that keyword is not changed.

WORD=wl specifies the number of bits per transmission byte. wl must be one of 5, 6, 7 or 8.

BAUD=br specifies the transmission rate (the baud rate) for both sending and receiving. The 16 allowable values for br are 50, 75, 110, 134, 150, 300, 600, 1200, 1800, 2000, 2400, 3600, 4800, 7200, 9600 and 19200.

STOP=sb specifies the number of stop bits to be used for each byte transmitted. sb is either 1 or 2.

PARITY=pp specifies the parity to be used in the transmission where 1 = odd parity, 2 = even parity and 3 = no parity.

WAIT or NOWAIT are mutually exclusive and specify whether or not the RS-232 input routine is to wait until an input byte is received and the output routine is to wait until the current byte has been sent. If neither WAIT nor NOWAIT is specified, the previous wait or no wait state remains.

SETCOM command examples:

1. SETCOM,WORD=8,BAUD=300,STOP=1,PARITY=1,WAIT
   Activates the RS=232 interface, if not already active, and sets the interface for 8 bit bytes, 300 baud rate, one stop bit, odd parity and forces the RS-232 routines, when called, to wait until an input byte is ready or until the RS-23.2 output device will accept an output byte.
2. SETCOM,NOWAIT,PARITY=3,WORD=7
   Activates the RS-232 interface, if not already active, and sets the interface for 7 bit bytes, no parity and causes the RS-232 routines not to wait until an input byte is ready or the RS-232 output device will accept an output byte. The TRS-80 interrupt routines will handle the actual byte input or output with the RS-232 device. The other parameters not mentioned in the command are not changed.
3. SETCOM,OFF
   The RS-232 interface is deactivated. The current interface specification is remembered.

STMT,msg

Since normal DOS commands are always displayed, this command normally has nothing to do since its function, to display the message MSA, has already been done. However, if this command was invoked via DOS-CALL (which does not display the DOS command), the message MSA is displayed.

STMT is one of 3 ways in chaining to display a message without a pause. This allows multiple line instructions to be displayed, with the last line being a PAUSE and the others being STMTs.

STMT command examples:

1. STMT PHASE ONE COMPLETED
   This is simply an announcement to the terminal operator that phase one (whatever that was) has been completed. DOS does not pause.
2. STMT DISMOUNT AND STORE AWAY DISKETTE XXX PAUSE AND MOUNT DISKETTE YYY ON DRIVE 2
   This example illustrates the combined use of the STMT and PAUSE commands to give instructions and wait until they are carried out.

SYSTEM,[password1:]dn1,[,AA=yn][,AB=yn][,AC=yn][,AD=yn][,AE=yn]
[,AF=yn][,AG=yn][,AH=yn][,AI=yn][,AJ=yn][,AK=yn][,AL=al]
[,AM=am][,AN=an][,AO=ao][,AP=ap][,AQ=yn][,AR=yn][,AS=yn]
[,AT=yn][,AU=yn][,AV=av][,AW=aw][,AX=ax][,AY=yn][,AZ=yn]
[,BA=yn][,BB=yn][,BC=yn][,BD=yn][,BE=yn][,BF=yn][,BG=yn][,BH=yn][,BI=bi][,BJ=bj][,BK=yn][,BM=bm][,BN=bn]

The NEWDOS/80 system diskette whose control information is being updated/ displayed by this command is mounted on drive dn1. If passwords are enabled, password1 must be specified and be equal to the diskette's master password. If no optional parameters are specified, then only a display of existing options is given. The optional parameters may be specified in any order, and only those parameters specified have their values changed in the diskette's control data (3rd sector on the diskette). Parameters not specified are not changed.

If many options are being changed, it may be necessary to perform multiple SYSTEM commands as the DOS buffer is limited to 79 characters per command.

It is anticipated that additional options will be specified as time proceeds.

Changes to a system diskette's system option's do not affect the computer operations until that system diskette is mounted on drive 0 and a reset done.

AA=yn - If AA=Y, passwords are enabled. If AA=N, passwords are disabled.

AB=yn - If AB=Y, the system is to operate in RUN-ONLY mode. SYSTEM options AD=N, AE=N and AF=N are forced at reset time, and the pressing of ENTER to override the auto command is disallowed. The user must have a proper auto command (see AUTO, section 2.4) that will either invoke a user program or execute a CHAIN file that will eventually invoke a user program. In RUN-ONLY mode, if the system finds itself at normal DOS READY or MINI-DOS READY, it will go into an endless loop after displaying 'RUN ONLY STOPPED!! PRESS 'R' FOR RESET*. Upon receiving R, the DOS command BOOT (see section 2.7) will be executed. BASIC honors RUN-ONLY by disabling BREAK, treating LOAD without R or V as an error, and by not allowing any direct statements. If AB=N, the system is in normal command mode.

AC=yn - (Model I only) If AC=Y and if SYSTEM option AJ=Y, the NEWDOS/80's debounce routine is used. If AC=N or SYSTEM option AJ=N, the NEWDOS/80's de-bounce routine is bypassed.

AD=yn - If AD=Y, 'JKL' is enabled, and if AD=N, 'JKL' is disabled.

AE=yn - If AE=Y, '123' is enabled as the method to invoke DEBUG (see section 4.1). If AE=N, '123' is disabled.

AF=yn - If AF=Y, 'DFG' is enabled as the method of invoking MINI-DOS (see section 4.2). If AF=N, 'DFG' is disabled.

AG=yn - If AG=Y, BREAK is considered a normal input key with code = 01. If AG=N, the BREAK key is not considered a normal input key and its occurrence is changed to the null key code 00. The state of the BREAK key is set according to option AG at reset and then again every time the system returns to normal DOS READY. DOS command BREAK may be used to enable or disable the BREAK key until the next normal DOS READY. Also, programs may enable the BREAK key by storing a 0C9H byte in Model I location 4312H (Model III location 4478H) or disable the BREAK key by storing a 0C3H byte in that location.

AH=yn - Not defined in NEWDOS/80, version 2. Formerly, this dealt with delaying the disabling of timer interrupts during disk I/O to gain better clock accuracy. This is no longer done.

AI=yn - (Model I only) If Al = Y, lower case modification has been installed in the computer and AI=N if it is not. User programs may test for bit 4 of 436CH for this state, 1 if AI=Y and 0 if AI=N. Currently, DEBUG and SUPERZAP use this flag to decide whether memory displays can display lower case.

AJ=yn - If AJ=Y, NEWDOS/80's keyboard intercept routine is active. This routine contains repeat key function, 'debounce' (Model I only) and one of the methods used to spot 'JKL', '123' and 'DFG' (the other being off the timer interrupts). If AJ=N, NEWDOS/80 does not intercept the keyboard two byte address vector at 4016H and

1. The repeat key function for the Model I is not active regardless of the SYSTEM* option AU. The Model III reverts to the ROM repeat key function.

2. 'debounce' (Model I only) is not active regardless of SYSTEM option AC setting.

3. .'JKL', '123' and 'DFG' can only be triggered via the interrupts, resulting in many more spurious key input characters.

If the up-arrow key is depressed all during the reset/power-on sequence, AJ = N is forced; this is necessary for those programs that eventually overlay the DOS in main memory.

AK=yn - Not defined in NEWDOS/80, version 2. Formerly, this option dealt with allowing 'JKL' to pass graphic characters to the printer. This has been incorporated into SYSTEM option AX.

AL=al - al (value 1-4) specifies the number of physical drives in the system. If your system only has one drive, setting al = 1 will limit the system to only checking for that one drive. Though al can be set to 255, it should never exceed 4.

AM=am - am (value 0 - 255 where 0 = 256) is the number of tries allowed for a disk I/O before it is declared in error. The original DOSs used a value of 10.

AH=an - an = the default drive number for the DIR command.

AO=ao - When creating a file and when the user lets the system choose the diskette to contain the file by not specifying a drive number in the filespec, the system will first search all the drives for an existing copy of the file. If it does not find an existing copy, the system will start searching at drive ao, and will search that and higher numbered drives until a free FDE is found. It will not search a drive whose number is less than ao.

AP=ap - ap is a memory address, which if other than 0 and is within the range of existing memory, is stored as DOS's HIMEM address value in the two bytes at Model I location 4049H (Model III location 4411H).

AQ=yn - If AQ=Y, the CLEAR key is enabled, and if AQ=N, the CLEAR is disabled if SYSTEM option AJ=Y.

AR=yn - If AR=Y, COPY, formats 5 and 6, are allowed without diskette password checking even though passwords are enabled. If AR=N, passwords are required if passwords enabled.

AS=yn - (Model I only) If AS=Y, BASIC will convert input text character strings from lower to upper case. This is useful when lower case hardware is not installed or when lower case drivers are not used as it is very possible to input lower case characters (using the shift key) and have BASIC display them as upper case even though they are really lower case. The user can stare forever at a compare that looks equal on the display, but BASIC computes as unequal. If as = N, BASIC will leave the text character strings alone. This option does not affect string characters input as data rather than as part of text.

AT=yn - AT=N puts chaining into record mode, meaning that only requests for full records come from the chain file; single char key input request are honored from the keyboard. AT=Y puts chaining in single character mode meaning that all requests for an input key come from the chain file.

AU=yn - AU=Y turns on the clock driven repeat key function. The first repeat will delay option AV number of 25 ms intervals. Subsequent repeats will enter as fast as the program asks for them but not more than 12 per second. AU=N turns off the repeat key function, eliminating repeat keys on the Model I and shifting to the ROM repeat key function on the Model III.

AV=av - AV is used when AU=Y. av is the number of 25 ms intervals to pass between the key depression and the acceptance of the 1st repeat of that character. Subsequent repeats are as fast as the program wants them but not more than 12 per second.

AW=aw - is the number of write-with-verify disk I/O tries allowed. This I/O retry count works in conjunction with option AM=am with each retry under AW taking place only after the sector verify read has failed am number of times. Formerly, if sector write encountered no error and the verify read did result in an error, it was left to the user to retry the write. Now, if aw is greater than 1, the write will automatically be retried in the cases where the write was apparently good but the verify read failed.

AX=ax - This is ASCII code of the highest printable character for the printer. It is used by system routines to determine when to substitute blanks or periods in place of ASCII codes higher than this value. This value must not exceed 255. This high ASCII code is stored in the one byte at Model I location 4370H (Model III location 4290H).

AY=yn - is used only during resets wherein DOS senses that it was not active immediately prior to the reset (i.e., reset after power-on or after execution of non-disk BASIC). AY=Y causes the operator to be asked for date and time. AY=N bypasses this query and causes date and time to be set to zeroes.

AZ=yn - is used only during resets wherein DOS senses that it was active immediately prior to the reset. AZ=Y causes the operator to asked for date and time. AZ=N causes date and time to be left as they were prior to the reset.

BA=yn - BA=Y causes a reset to activate 'ROUTE,DO,NL', thus causing all display output, including the DOS and BASIC banners, to be lost until the operator or a user program executes either 'ROUTE,CLEAR' or 'ROUTE,DO'. BA=N disables this reset action.

BB=yn - (Model III only) BB=N informs the system that the clock interrupts occur 60 times a second. BB=Y informs the system that the clock interrupts occur 50 times a second. This option docs not set the clock to perform as such, but only acknowledges that it does.

BC=yn - BC=Y means the operator can manually pause or cancel chaining. BC=N means the operator is not allowed to manually pause or cancel chaining. RUN ONLY forces BON.

BD=yn - BD=Y means the operator can override the AUTO command at reset by holding down the ENTER key. BD=N means he/she can't. RUN ONLY forces BD=N.

BE=yn - BE=Y enables the DOS command R to repeat the previous DOS command (see section 2.41). BE=N causes the R command to simply return to DOS READY.

BF=yn - (Model I only) BF=Y performs at reset/power-on time the equivalent of the DOS command LCDVR,Y (see section 2.29). BF=N performs the equivalent of LCDVR,N. However, if DOS senses that the lower case hardware is either not installed or is not operating, BF=N is forced.

BG=yn - BG=Y performs at reset/power-on time the equivalent of the DOS command LC,Y (see section 2.28). BG=N performs the equivalent of LC,N

BH=yn - At reset/power-on time BH=Y enables cursor blinking, and BH=N inhibits it.

BI=bi - At reset/power-on time, the numeric value bi is set as the cursor character's value, excepting that if bi = 0, then the standard cursor character value is used (95 for the Model I and 176 for the Model III).

BJ=bj - Option BJ provides a minimal control for NEWDOS/80 when a CPU speed up modification is installed that is to continue operation during disk operations. This option multiplies (roughly) by bj the number of Z-80 instructions executed during certain timing loops used internal to NEWDOS/80. bj must be an integer greater than 0 and equals the number of times the CPU has been speeded up. Set bj = 1 if the loops are not to be lengthened. If the loops are to be lengthened, bj must always be rounded up in the cases where the new CPU speed is not an even multiple of the original Model I or Model III speed. Option BJ does NOT perform the actual CPU speed switching.

BK=yn - BK=Y allows the DOS command WKDIRP and the W and C functions of DIRCHECK to be executed. BK=N causes these functions to be rejected with 'DISK ACCESS DENIED'.

BM=yn - BM=Y causes diskette formatting to verify read sectors in a separate VERIFYING phase after all tracks have been, formatted. This verify read is in addition to the verify read done on a track's sectors immediately after the individual track was formatted. BM=N bypasses this VERIFYING phase, deeming as sufficient the verify sector read done when the individual track was formatted.

BN=yn - Model I only. BN=N causes the write of single density diskette directory sectors to use the address mark readable by Model I TRSDOS. BN=Y causes the write of single density diskette sectors to use the address mark readable by Model III NEWDOS/80. BN=Y should only be used where it is required that single density diskettes be NEWDOS/80 version 2 exchangeable between the Model I and the Model III.

Though the information contained in the directories used by Model I TRSDOS, Model I NEWDOS/80 and Model III NEWDOS/80 is the same (except for some additions by NEWDOS/80), the address mark byte (part of the magnetic format and identification bytes that surround each 256 bytes of user data on the soft sectored diskettes) used to indicate the directory sectors are 'protected' is different on the Model III than it is on the Model I for single density diskettes.

The changing of SYSTEM option BN does not in itself change the address mark of any directory sectors. All this does is set the protected sector write routine in DOS to write the specified address mark whenever a protected sector is written or rewritten to disk. To set all sectors of a single density diskette directory to the proper address mark, use either DOS command WRDIRP or DIRCHECK with the W option. Warning!!! If a single density diskette has been used on the Model III or has been used on the Model I where BN=Y and the diskette must now be used with Model I TRSDOS, the user must set BN=N and rewrite the directory sector address marks using WRDIRP or DIRCHECK with option W. This must be done even though, with BN=N, SUPERZAP under NEWDOS/80 on the Model I shows the directory sectors protected; this is because Model I NEWDOS/80 accepts either address mark value as 'protected' though it only writes the one value specified by option BN.

System option codes BO and up are reserved for future definition.

SYSTEM command examples:

1. SYSTEM,0,AL=4,AA=Y,AU=Y,AV=20,AT=Y
   The SYSTEM control parameters AL, AA, AU, AV and AT are changed on the current system diskette mounted on drive 0. All the other SYSTEM parameters are left unchanged. The full SYSTEM specification is then displayed. These changes are not used to control NEWDOS/80 until the next reset/power-on.
2. SYSTEM,2,AP-=0FF00H,AN=1 ,AX=126
   The SYSTEM control parameters AP, AN and AX are changed in the control sector of the diskette currently mounted on drive 2. No other SYSTEM parameters are changed. The full system specification contained on that diskette is then displayed. For the SYSTEM parameters contained on that diskette to control NEWDOS/80, that diskette must be a NEWDOS/80 version 2 system diskette, must be dismounted from drive 2 and remounted on drive 0, and a reset/power-on must be done.

TIME[,hh:mm:ss]

If no parameters are specified, the current times is displayed in hh:mm:ss format.

If hh:mm:ss is specified, the clock is set to time hh:mm:ss where hh is a 2 digit hour value, 00 - 23, mm is a two digit minute and ss is a two digit seconds value. No check is made on the validity of the values. Facl of the three values is converted to a single byte value and stores into its byte of the clock. The clock three bytes start at model I location 4041H (model III location 4217H) and are in seconds, minutes, hours order.

At reset/power-on the clock is set according to SYSTEM option AY or -AZ. The clock is updated once a second. The user should not rely upon the clock for an accurate value as disk I/O frequently and interrupt routines infrequently run so long with interrupts disabled that one or more timer interrupts will be missed, causing the clock to run slow. The real time clock is not a hardware clock, but instead is maintained by software that is not aware of the lost timer interrupts.

TIME command examples:

1. TIME,15:23:00
   The clock is set to 3:23 PM.
2. TIME
   The current time is displayed.

VERIFY[,yn]

NEWDOS/80 performs verify read after all of its directory writes and after all sector writes when logical record or single byte I/O is used. It does not perform verify reads when full sector writes are done via the 4439H vector.

VERIFY or VERIFY,Y Diskette writes done via the 4439H vector are verify read. A verify read means the sector is read after it is written. If the sector was written illegible or with bad parity, an error will be triggered. A byte for byte data compare is not done. However, if the verify read detects an error and SYSTEM option AW is not equal to 1, the write and verify read will be done again since the system still has access to the data that should have been placed into the diskette sector.

Diskette full sector writes done via the 4439H vector are not verify read.

COPY, EDTASM and BASIC SAVE's write the file completely without validity read, but then read back the entire file as a verify read. All BASIC disk data writes to print/input files, marked item files, fixed item files or field item files (where record length is not 256) perform verify read due to the fact that byte rather than sector I/O is used. Field item files with record length 256 use sector I/O and are not verify read unless VERIFY is on.

WRDIRP,dn1

WRDIRP causes the directory sectors for the diskette in drive dn1 to be read and rewritten in the currently defined protected state for the current computer (see SYSTEM options BN and BK).

This command is used where single density diskettes are to be exchanged under NEWDOS/80 version 2 between the model I and III.

This command enables the user to set the directory to the proper read protect state while under MINI-DOS, since it is most likely he/she will find out about the problem when in the middle of doing something else (and thus can't get to DIRCHECK). CAUTION!!! This command uses the directory starting granule number from the 3rd byte of the boot sector to find the directory. It then checks to see if the FPDE's for BOOT/SYS and DIR/SYS are present. If these checks pass, it then changes what it thinks are the directory sectors all to protected status. Do NOT use this command unless you are sure the only problem is the different protection status between the model I and model III; if you have doubts, use the W function of DIRCHECK.

If SYSTEM option BK = N, the DOS command WRDIRP is disabled.

WRDIRP command example:

1. WRDIRP,1
   For the diskette mounted on drive 1, the directory address marks are set for the current computer and, if Model I, for the setting specified by SYSTEM option BN.

These DOS routines have entry and exit conditions, and rather than repeat them in each routine's specification, some of the conditions are defined here with the using routine's specification simply referring to the condition's code.

1. Only register AF is altered by the routine. Any other registers used by the routine are saved on entry and restored on exit.
2. On exit, Z state is set if no error is encountered during the routine's execution. NZ state is set if a DOS error is encountered, and register A contains a DOS error code. The setting of Z and NZ takes precedence over the setting of other flags such as C and NC.
3. On entry, DE points to an open FCB.

There are incompatibilities with TRSDOS in the use of some of these routines. They are discussed briefly in the routines where they occur, so study them carefully. The reader should also be aware of the differences in the way the FCB fields NEXT and EOF are maintained (see FCB specification, section 5.9).

The discussion of each routine gives its entry address (the address to be used in the CALL or JP Z-80 instruction), then its title (if one is appropriate), and then its specification.

Unless otherwise specified, the DOS routine uses the invoker's stack. Unless specified as a dead end routine, the DOS routine exits to the caller.

Many of these routines use a FCB (see section 5.9). NEWDOS/80 on both the Models I and III and Model I TRSDOS all use a 32 byte FCB while Model III TRSDOS uses a 50 byte FCB. NEWDOS/80 will run with user programs having the 50 bytes FCB but will only use the first 32 bytes of those FCBs. Programs using a 32 byte FCB with Model III TRSDOS will have problems.

The routines listed below are not necessarily in ascending numeric order.

If either MINI-DOS or DOS-CALL, the stack pointer is set to where it was before the last DOS command; otherwise it is set to DOS's stack area and the BREAK key is enabled/disabled according to system option AG.

If DOS-CALL and if either not chaining or chaining is not to be continued at the current DOS level, all registers except AF are restored to as they existed on DOS-CALL entry, Z state is set, and a return is made to the DOS- CALL invoker. If this was the outermost DOS-CALL level, DOS is taken out of DOS-CALL state.

If RUN-ONLY and if chaining is not active, the message 'RUN ONLY STOPPED!! KEY ' R' FOR RESET.' is displayed, DOS loops waiting on the reply, and then executes DOS command BOOT (see section 2.7).

If DOS-CALL and if chaining is to continue at the current DOS-CALL level, DOS waits for the next command from the chain file.

If MINI-DOS, then MINI-NEWDOS/80 READY is displayed,. and DOS waits for the next command.

If chaining is active, DOS waits for the next command from the chain file.

NEWDOS/80 READY is displayed and DOS waits for the next input command.

Dead end routine. Programs concluding with an error that is either already displayed or not to be displayed jump to 4030H. DOS action is the same as for 402DH except as follows:

If CHAINING, chaining is aborted.

If DOS-CALL, the current DOS-CALL level is exited in the same manner as for 402DH, except that C state is set.

Dead-end routine. DOS is entered, and the stack pointer is set to DOS's own area. HL points to a command, terminated by a 0DH byte, that DOS is to use as its next command. DOS moves this command to its own 80 byte command buffer and then executes it.

Dead end routine if bit 7 of register A equals 0. Programs terminating with a DOS error jump to 4409H with the DOS error code in register A and bit 7 of register A equal 0. Depending upon DOS's state, the following actions occur:

If CHAINING, chaining is aborted.

If DOS-CALL, the current DOS-CALL level is exited in the same manner as for 402DH exit, except NZ and NC state is set and the DOS error code is in register A. The error MSA is not displayed.

Otherwise the DOS error message is displayed, and an exit is taken to 402DH.

A program way CALL 4409H to display an error MSA by placing the error code in A and setting bit 7 of register A equal to 1. The appropriate DOS error message will be displayed. On return, only the F register has been altered.

The Model I TRSDOS will print diagnostics if bit 6 of register A equals 0. The Model III TRSDOS displays only the error number if that bit equals 0 and the error message if that bit equals 1. NEWDOS/80 ignores the value of that bit.

Debugging hint: By setting the 4 bytes at 4409H equal to CD 0D 44 C9, the error display routine can be made to invoke DEBUG instead of displaying the error message.

User programs have two methods of entering the DEBUG facility: (1) by use of Z-80 instruction RST 30H and (2) by the Z-80 instruction CALL 440DH. When done with the DEBUG facility, DEBUG command G will return to the instruction following the RST 30H or the CALL, provided the PC register was not changed.

Registers AF, BC, DE and HL are altered by this routine. On entry, DE points to the user interrupt routine which must conform to the following format:

1st 2 bytes: Used by DOS as a forward chain pointer. On entry, the two bytes can be any value.

3rd byte: The number of 25ms intervals to pass between invocations of the user's routine. Example, if the routine is to be invoked every second, the 3rd byte must be set = 40 (28H). DOS does not alter this byte.

4th byte: Count down value to the next invocation. On entry, this byte should be properly initialized to a value greater than 0 but less than or equal to the value in the 3rd byte. Every 25ms interrupt, DOS decrements this value. If the result is non-zero, this routine is bypassed for this 25ms interrupt. If the result - 0, the value from the 3rd byte is moved into the fourth byte, registers HL, DE, BC and AF are saved, and the user routine is called at its 5th byte. Any other registers used by the routine must be saved/restored by it. Interrupts are disabled, and the user routine must not re-enable them.

While a user interrupt routine is in the interrupt chain, it must not be altered in any way except by a routine that runs with interrupts disabled; the first two bytes must never be altered.

Model I TRSDOS uses the 4 vectors, 4410K, 4413H, 4416H and 4419H, for its user- "interrupt routine handling. NEWDOS/80 uses only 4410H and 4413H for non- compatible handling of these routines. Any program using a 25ms interrupt user routine in TRSDOS must be modified to work under NEWDOS/80. This is a major incompatibility between the two Model I systems.

Model III TRSDOS has not yet made any provision for user timer routines, using 4410H - 441BH for other purposes, including HIMEM.

Model III NEWDOS/80 continues with the user timer interrupt routine mechanism used on the Model I, except that 447BH is the routine enqueue vector instead of 4410H, and in order to continue with 25 ms counting where the Model III clock actually counts in either 30ths or 25ths of a second, a second pass through the user routine check and invocation sequence is done when necessary to bring 25ms counting up with the real clock. If a user routine is being invoked every 25 ms, the routine must be prepared to accept two invocations within the same timer interrupt.

Registers AF, BC, DE and HL are altered. The user interrupt routine (as described in section 3.7) pointed to by register DE is taken out of the 25ms interrupt chain, if it is in the chain. The routine no longer participates in the interrupts and may now be altered at will by the user.

See section 3.8 for TRSDOS incompatibility.

If the disk drives are rotating, reselect the current drive, thereby keeping the drives rotating for approximately 2.4 seconds more. Register AF is altered.

This routine does not exist in TRSDOS; see section 3.8 for incompatibility.

This routine is DOS-CALL. DOS does not shift to its own stack area, but instead remains with the user's stack. All registers except AF are saved in the stack and will be restored on return. The command to be executed is pointed to by HL, must be less than 80 characters, must terminate with byte 0DH, and can be anything legal for the current state DOS is in. DOS sets DOS-CALL state, if not already set, saves the current stack pointer, and executes the command. The command can be the invocation of a user program.

DOS-CALL is now legal under CHAINING where it was not in NEWDOS/80 Version 1.

DOS-CALL is the way BASIC executes the DOS command contained within the BASIC statement CMD"xx" where xx is the DOS command.

The DOS-CALL caller is responsible for assuring that memory conflicts do not arise and that sufficient stack space is available.

Nested calls to DOS-CALL may be executed. Upon exiting from a DOS-CALL level, the return is made to the next outer level. When the outermost level is exited, DOS leaves DOS-CALL state.

If the DOS command invokes a program, that program may use its own stack area, and it must exit using one of the three exits: 402DH, 4030H or 4409H. On exiting, the program may store a 2 byte parameter in 4403H, 4404H (17411, 17412 decimal) for use by the caller.

The 4419H vector is used differently in TRSDOS; see section 3.8 for incompatibility.

See section 4.4 for further discussion of DOS-CALL.

From the text pointed to by HL, extract a filespec, place it in the area pointed to by DE and terminate it with the byte 03H. Registers AF, BC and HL are altered.

If the first text character is A - Z or 0 - 9, or if the first text character is * and the next character is A - Z or 0 - 9, text is moved from the HL area to the DE area until a character that is not /, ., :, A - Z, or 0 - 9 is encountered or until 32 bytes have been transferred. If less than 32 bytes, a 03H byte is placed after the last byte in the DE area to indicate end of filespec, and a return is made with Z state set. If the filespec is more than 31 characters it is considered improper as discussed in the following paragraph.

If the first character was improper, or if the first character was * but the 2nd was improper, a return is made with NZ state set.

On exit, if the terminator/improper byte equals 03 or 0DH, then HL points to that byte; otherwise HL points to the next byte.

The user will notice that NEWDOS/80 doesn't check for an exact filespec; it leaves this to be done by the OPEN routines, 4420H and 4424H.

Conditions 3.1.A and B hold. The entry requirements are the same as for 4424H, which is executed immediately as a subroutine to this routine. If 4424H is successful in opening an existing file, no further action is required here, and an exit is taken with Z and NC states set. If the file was not found, this routine proceeds to create the file.

If the filespec in the FCB pointed to by register DE specifies an explicit drive number and the diskette mounted on that drive has a free FDE, the file is created on that diskette whether or not the diskette actually has any free space. If the filespec did not specify a drive number, the system starts searching mounted diskettes, starting with the drive number specified by SYSTEM option AO and preceding through higher numbered drives until a diskette with a free FDE is found. If a free FDE is not available, the file cannot be created, and the error exit is taken. -

Creating a file consists of converting a free FDE to a FPDE. This entails inserting the name and name extension (if any), encoding the password (if any) as both the update and access passwords, storing the LRECL (0 means 256) from register B, setting the EOF equal to 0, setting access level as FULL, and marking the file non-system, non-invisible. No diskette file space is assigned to the file at this time; in fact, DOS doesn't even look to see if the diskette has any free space. Note, though the LRECL is stored in the FPDE during file creation, it is never used. Each subsequent open of the file uses the LRECL provided in register B.

After the file is created, the DOS routine at 4424H is called to perform the OPEN. On exit after a successful file create and open, Z and C states are set.

Conditions 3.1.A and B hold. On entry, register DE points to a FCB containing the filespec for the file to be opened, HL points to a 256 byte buffer to be used during disk sector reads and writes for this FCB, and B contains the LRECL (0 = 256). If an explicit drive number was specified in the filespec, the search for the file is limited to that drive; otherwise the search starts with drive 0 and proceeds to higher drives until a file with the specified name and name extension is found. If no file is found, the error exit is taken.

If passwords are enabled and the file has non-null passwords, then an error exit is taken if the filespec does not contain either the update or the access password. If passwords are disabled or the file has no passwords or the update password is specified, the FCB's access level is set to FULL; otherwise the access level from the FPDE is placed into the FCB to limit the type of access for this file.

The FCB is converted from containing the filespec to containing information about the file, which will be used while the FCB is open to reduce the amount of directory I/O which would otherwise be required. The conversion entails copying the EOF and the 1st 4 extents from the FPDE, storing the LRECL from register B, setting bit 7 of the FCB's 2nd byte equal to 1 if LRECL is not equal to 0 (to indicate logical record processing), setting NEXT equal to 0, storing the drive number and the FPDE's DEC code, storing the 256 byte buffer pointer from register HL, setting the access level, setting bit 5 of the FCB's 2nd byte equal to 1 to indicate that the buffer does not contain the current, sector and setting bit 7 of the FCB's 1st byte equal to 1 to indicate that the FCB is open.

Conditions 3.1.A, B and C hold. This routine dissolves the connection between the FCB and the file. If bit 4 of the FCB's 2nd byte equals 1, the FCB's buffer is written to disk like a 4439H call. If the FCB's EOF is different from that in the FPDE, the FPDE is updated for the new EOF. If the file has excess granules beyond EOF and if automatic space deallocation is allowed, the excess granules are released. The FCB is then converted back to contain a filespec consisting of the file name, name extension (if non-blank) and the drive number. This filespec can be used later to re-open the file, provided a password is not required.

Conditions 3.1.A, B and C hold. The file associated with the FCB is killed in the same manner as for DOS library command KILL (see section 2.27). The FCB is set to all zeroes.

Conditions 3.1.A and B hold except the registers AF, BC and HL are altered and on exit HL (and 4403H - 4404H (17411 - 17412 decimal)) contain the program's entry address. On entry, register DE points to a FCB containing the program file's filespec. The load is done the same as for DOS library command LOAD (see section 2.32).

Dead end routine. On entry, DE points to a FCB containing the program file's filespec. Registers AF and BC are altered; all other registers are passed on unchanged to the program when its execution begins. The file open, load and commence execution are done the same as when DOS executes a command that is not a library command, excepting that there is no default name extension. If an error occurs during the open or load, DOS exits to 4409H. If DEBUG is active (see section 2.17), DEBUG is entered just before the program commences execution.

If bit 7 of the FCB's 2nd byte equals 0, the sector represented by the high two bytes of the NEXT field is read into the FCB's buffer and, if no error or if error code 6 (sector read protected), the NEXT field is advanced 256 bytes. If an error other than code 6 occurs, the NEXT field is not advanced, meaning the user can retry to read the same sector.

If bit 7 of the FCB's 2nd byte equals 1, then a logical record of length equal to the FCB's LRECL (where 0 means 256) is moved from the FCB's buffer to the buffer pointed to by register HL on entry. As each byte is moved, the NEXT field is incremented. When the FCB's buffer is empty, the next file sector is automatically read into it and byte movement continues. If an error occurs, including error code 6, the logical record move terminates, leaving NEXT advanced for the number of bytes moved.

If bit 1 of the FCB's 1st byte equals 1, the NEXT and EOF fields are considered RBA's within the diskette rather than within a file, thus giving the user the capability to read a diskette, rather than a file. The use of bit 0 of the FCB's first byte is defined in section 3.20 below. DOS routines 0013H, 001BH, 4439H, 443CH and other routines that indirectly read or write sectors also operate as such if any of these two bits are on. The use of these 2 bits is incompatible with TRSDOS.

One incompatibility between NEWDOS and TRSDOS occurs when the program reads the EOF from the FCB to determine the number of bytes in the file. However, in many cases the user does not have to know what the EOF is. Instead, for both TRSDOS and NEWDOS, the user can read the file sector by sector, waiting for either of the two EOF errors. If the error code is 1CH (END OF FILE ENCOUNTERED), then the file ends on a sector boundary and the last sector read successfully was the file's last. If the error code was 1DH (PAST END OF FILE), then the last sector successfully read was also the file's last, but was only a partial sector with the value in FCB+8 equaling the number of bytes in that sector belonging to the file. Remember, this is true for both TRSDOS and NEWDOS; thus the same code can work for both.

Conditions 3.1.A, B and C hold.

If bit 7 of the FCB's 2nd byte equals 0, the disk sector as defined by the NEXT field is written with the contents of the FCB's buffer. Unless VERIFY is on (see section 2.48), verify read is not done. If no error, and if the lower order byte of NEXT equals 0, the NEXT field is advanced 256 bytes. Whether or not NEXT was advanced, if NEXT now exceeds EOF or if bit 6 of the FCB's 2nd byte equals 0, EOF is set equal to NEXT. If an error occurred, NEXT is not altered, thus allowing the user to retry to write the same sector.

If bit 7 of the FCB's 2nd byte equals 1, a logical record of length equal to the FCB's LRECL (0 means 256) is moved from the caller's buffer, pointed to by register HL on entry, to the FCB's buffer. With each byte's move, NEXT is incremented, and if NEXT now exceeds EOF or if bit 6 of the FCB's 2nd byte equals 0, EOF is set equal to NEXT. When the FCB's buffer fills, the buffer is written to the appropriate disk sector with verify read and then the logical record move continues, filling in the FCB's buffer for the next file sector. Whenever an error occurs, the logical record move terminates, leaving NEXT advanced for the number of bytes moved.

Bit 1 of the FCB's 1st byte functions as described in section 3.19. If bit 0 of that byte equals 1, then sectors are written protected (error code 6 on sector read).

If a verify read is done after the write of a protected sector, error code 6 is not returned to the caller as an error.

A significant incompatibility with TRSDOS lies in the fact that when a sector is written to disk in EWNDOS/80 and the low order byte of NEXT is non-zero, NEXT is not advanced by 256 bytes. In this case, NEWDOS/80 assumes that the caller is writing the last sector of the file (though it need not be) that is only partially full, and that NEXT already is the proper RBA value for EOF (if EOF is to be updated by the write).

One incompatibility between NEWDOS and TRSDOS is in setting the final EOF for a file that is written sector by sector but usually does not end on a sector boundary. However, if the program knows when it is about to write the last sector, whether partial or full, and can store the desired low EOF byte value in FCB+5 just before writing that last sector, both TRSDOS and NEWDOS will exit from that write with the same EOF. Thus, in this instance, the same program code will work for both TRSDOS and NEWDOS, and no compatibility exists.

Conditions 3.1.A, B, and C hold. If the FCB has a sector awaiting write (bit 4 of FCB 2nd byte = 1), it is written as a 4439H call. The FCB NEXT field is set = 0. Bit 5 of FCB 2nd byte is set = 0 to indicate the buffer does not contain the current sector.

Conditions 3.1.A, B, and C hold. The NEXT field is set to the RBA of the logical record whose relative record numbre (=0 the first record) is in reigster BC upon entry. If the new NEXT is in the same sector as the old NEXT, the status of the current sector is not changed (i.e., the sector is not written to disk if bit 4 of the FCB 2nd byte equals 1). If the new NEXT is not in the same sector as the old NEXT, then (1) if bit 4 of the FCB 2nd byte equals 1, the old sector is written back to disk, and (2) bit 5 of the FCB 2nd byte is set to 1 to indicate that new sector has not yet been read into the buffer.

Conditions and performance are the same as 4442H except that the NEXT field is reduced by the LRECL.

Conditions and performance are the same as 4442H except that the NEXT field is set equal to the EOF field.

Conditions 3.1.A, B and C hold. If the file sector represented by the two high order bytes of the FCB's NEXT field is not already allocated to the file , the granule containing it is allocated along with the granules for any lower sectors for the file that are not yet allocated. This allows the programmer to allocate file space before it is actually needed, and is especially valuable when it is necessary to know that a sector can be written before any data is placed in the buffer. If a file's size can be predetermined before being written (such as is done in COPY), pre-allocating the necessary granules saves considerable time over allocating the granules as the file write proceeds.

This address is defined differently in TRSDOS.

Conditions and performance are the same as for the 4442H call except the new NEXT position value is taken from the registers H, L and C where H contains the high order and C the low order values.

This address is defined differently in TRSDOS.

Conditions 3.1.A, B and C hold. If the EOF value in the FCB differs from that in the file' s FPDE, the FCB's EOF value is written in to the FPDE on disk.

This address is defined differently in TRSDOS.

Conditions 3.1.A and B hold. On entry, register A contains a drive number. That drive becomes the current drive, is selected and, if necessary, powered up.

Conditions and performances is the same as for 445BH excepting that, in addition, the drive is tested to determine if a diskette is mounted and is rotating. If this rotation test fails, error code 08, DEVICE NOT AVAILABLE, is returned.

Register HL points to a user routine in main memory to be chained in the chain of user logical routines. The first 12 bytes of the routine are defined as follows:

4 bytes reserved for use by DOS only.

8 byte logical routine name field containing the 1 - 8 character name of the routine, padded on the right with blanks.

If a routine with the same name already exists in the queue, FILE ALREADY EXISTS error code is returned with NZ set. Otherwise the routine is enqueued, and exit taken with Z state set. HL, DE, BC and AF are altered by this function. This function is new with MEWDOS/80.

Subsequently, whenever a DOS command of the form *name1 or *name1, parameters is executed, DOS searches its queue for a routine named name1, sets HL pointing to the parameters, if any, and jumps to the routine's 13th byte. When the routine concludes, it should exit via 402DH, 4409H, or 4030H. The routine may use all registers, and can use the two bytes at 4403H - 4404H to receive or pass back a parameter. If the logical routine name1 does not exist in the queue, FILE NOT IN DIRECTORY error code is returned with NZ set.

HL points to a logical routine as defined in section 3.31. If the routine is not in DOS's logical routine queue, this function exits with FILE NOT IN DIRECTORY error code in register A and with NZ set. Otherwise, the routine is dequeued, meaning that subsequent *name1 commands naming it will abort, displaying FILE NOT IN DIRECTORY. Registers HL, DE, BC and AF are altered by this function. This function is new with NEWDOS/80.

Condition 3.1.A holds. The message bytes pointed to by HL up to and including a 0DH byte (EOL) or up to but not including a 03H byte (EOM) are sent to the display.

The same as 4467H except the message is sent to the printer.

The current clock value at Model I locations 4041E - 4043H (Model III locations 4217H -4219H) is converted to HH:MM:SS character format and stored in the 8 bytes pointed to by HL. Registers AF, BC, DE and HL are altered. On exit, HL points to the next byte after the HH:MM:SS. field.

This routine is the same as 446DH, except the date value at Model I locations 4044H - 4046H (Model III locations 421AH - 421CH) is converted to MM/DD/YY format.

If the filespec pointed to by register DE has no name extension, insert the 3 characters pointed to by HL as its name extension. The resulting filespec cannot exceed 31 characters. Registers AF and HL are altered.

This is DOS's single byte read routine even though it starts in ROM. Conditions 3.1.A, B and C hold. If the disk sector containing the NEXT byte of the file is not in the FCB's buffer, it is read into there. The byte is then placed into register A for use by the caller. The FCB's NEXT field is incremented.

This is DOS's single byte write routine, even though it starts in ROM. Conditions 3.1.A, B and C hold. If the disk sector corresponding to the FCB's NEXT position is not in the FCB's buffer, it is read into the buffer, unless NEXT is on a sector boundary and is equal to EOF. The byte in register A on entry is placed into the buffer, and NEXT is incremented. If the buffer is now full, the sector is written to disk as if a 443CH call.

Continue to ...

Chapter 4: DOS Features

Skip to ...

Chapter 5: DOS Modules, Data structures, and Miscellaneous Information

Chapter 6: Additional Programs Supplied on NEWDOS/80 Diskette

Chapter 7: Disk Basic, Non-I/O Enhancements

Chapter 8: Basic Disk I/O Enhancements
and Differences

Chapter 9: Error Codes and Messages

Chapter 10: Glossary

Chapter 11: Error Reporting, Incompatibility Handling,
and Patching.

Chapter 12: Conversion Information
and Miscellaneous Comments.

Appendix A: Appendix A

Appendix B: Appendix B

Go back to ...

Chapter 1: Introduction

Chapter 2: DOS Library Commands

Chapter 3: DOS Routines