NEWDOS/80 v2.0 Reference - Chapters 4-6

Chapters

Library Commands

Supplied Programs

As an aid primarily for the machine language programmer but also for use by higher level language programmers, NEWDOS/80 has the DEBUG facility for interrupting current execution, inspecting memory, altering memory, inspecting disk, altering disk, single step execution, etc.

DEBUG can be entered in three ways:

1. Simultaneously depressing the three keyboard keys 1, 2 and 3. In order for this 123 action to work the follow conditions must be met.

1. SYSTEM option AB = N.

2. SYSTEM option AE = Y.

3. Either. (1) interrupts are enabled or (2) the main program is awaiting keyboard input via the standard keyboard input routine and SYSTEM option AJ = N.

4. DOS must not be currently using its overlay area (main memory locations 4D00H - 51FFH.

5. DOS must not have its overlay inhibit enabled.

2. Executing either a RST 30H or a JP 440DH or a CALL 440DH Z-80 instruction.

3. Automatically at, but before, a machine code program commences execution if DEBUG has been turned on via DOS command DEBUG (see section 2.17).

Upon entry, the DEBUG facility will (1) save all registers in the interrupted program's stack, (2) use the next stack locations for its own operations, (3) disable any stops that may have been set on its last exit, (4) display memory using mode and locations as remembered from its last exit, and (5) display the cursor in the lower right hand corner of the display to indicate that the DEBUG facility is awaiting an input command.

All commands, even the single character commands, to the DEBUG facility must terminate with ENTER. If an error is made in keying in a command but before ENTER is depressed, simply backspace over the incorrect characters and type in the correct ones. If desired, the command may be purged before ENTER by keying shift-left arrow.

Both the X and S displays display memory 16 bytes per display line, both in hexadecimal and in character format. If SYSTEM option AI = Y, character for-mats will include lower case letters.

When DEBUG encounters an error condition, it displays 'ERROR' and waits for the user to acknowledge the error which is done by pressing ENTER to clear the error state.

The DEBUG facility commands are as follows. Wherever numeric values are used, they are always hexadecimal values without the suffixed H unless otherwise specified.

X - The DEBUG facility shifts to X display mode, if not already there. The X display contains 15 lines. The 1st through 4th lines contain the 1st 64 byte memory area display. The 5th line displays the interrupted/ replaced contents of Z-80 registers AF, BC, DE and HL. The 6th through 9th lines contain the 2nd 64 byte memory area display. The 10th line contains the interrupted/replaced contents of Z-80 registers AF', BC', DE' and HL". The 11th through 14th lines contain the 3rd 64 byte memory area display. The 15th line contains the interrupted/replaced contents of Z-80 registers PC, SP, IX and IY. The displays for registers AF and AF' also include a bit mask for the associated F register, with an alphabetic character if the bit equals 1 (state set) and a - if the bit equals 0 (state not set). The meanings of the bits (7 - 0) are:

Using the X display allows the user to track the registers and three separate memory areas at one time.

S - The DEBUG facility shifts to S display mode, if not already there, using X display's 1st memory area's base address rounded down to a 256 byte page boundary as the S display's base address. The S display displays 256 bytes of memory, using 16 display lines.

[n]Daddrl - If in S display mode, the 256 byte block containing addrl is displayed; if n is specified, the base address of the specified area is changed, but the display won't change since DEBUG is in the S display mode. If in the X display mode, addrl becomes the base address for the specified area: 1 if n not specified, 2 if n equals 2, and 3 if n equals 3. Examples:

1. D7080 displays the contents of locations 7000H - 70FFH if DEBUG is in S display mode. If in X display mode, display area 1 will display the contents of locations 7080H - 70BFH.

2. 3DFFC0 If DEBUG is in X display mode, display area 3 will display the contents of locations FFC0H - FFFFH. If in S mode, the new area 3 address is remembered, but the display is not changed.

[n[; - If in S display mode and n not specified, the S display is advanced to the next 256 byte block. If in X display mode, the specified 64 byte display area is advanced 64 bytes: area 1 if n not specified, area 2 if n equals 2, and area 3 if n equals 3.

[n[- - If in S display mode and n not specified, the S display is retarded to the next lower 256 byte block. If in X display mode, the specified 64 byte display area is retarded 64 bytes: area 1 if not specified, area 2 if n equals 2 and area 3 if n equals 3.

Maddrl - The DEBUG facility shifts to S display mode, if not already there, displays the 256 byte block containing addrl, enters modify mode and displays a blinking cursor over the hex digit next to be changed. Pressing a key 0 - 9 or A - F causes that hex digit to be replaced in memory and the cursor advanced one position. Pressing right arrow or space advances the cursor one position without memory change. Pressing left arrow retards the cursor one position without memory change. Pressing shift left arrow retards the cursor 4 hex digits without memory change, and pressing shift right arrow advances the cursor 4 hex digits without memory change. Pressing up arrow moves the cursor up one display line without memory change, and pressing down arrow moves the cursor down one line without memory change. The cursor cannot be advanced or retarded outside the current 256 byte page. Pressing ENTER terminates modify mode. Any other key terminates modify mode and raises ERROR state. Example:

M6314 DEBUG is shifted to S mode, if not already there. The contents of 6300H - 63FFH are displayed, and a blinking cursor is displayed over the first hexadecimal digit of byte 6314H. The operator may now key in replacement hexadecimal digits and/or move the cursor around within the displayed 256 byte page.

F[addrl][,hbl][,hb2][,hb3][,hb4] Starting at main memory location addrl, find an occurrence of the specified series of hexadecimal bytes. hbl, hb2, hb3 and hb4 are each 2 hex digits representing a hexadecimal byte. If any of hbl, hb2, hb3 or hb4 are specified, addrl must also be specified. If none of hbl, hb2, hb3 or hb4 is specified, then the series of hexadecimal bytes last used by an F command is used. If addrl is not specified, then the memory location +1 of the last F command match is used, thus allowing the user to find successive occurrences of the initially specified byte string. Main memory is searched for an occurrence of the search string of bytes. If found, the address of the first of the matching bytes less 20H is made the X display's 1st area's base address. This causes the matching byte string to appear at the start of line 3 of the X display. If not found, X display's 1st area's base address is set = 0FFE0H. Example:

F5200,CD,24,44 will start at main memory location 5200H and search for the first occurrence of the three bytes mentioned. Subsequently, the command F will search for the next occurrence of the same three bytes.

If a match takes places in the current stack area, it is possible that the matching bytes will be gone from the stack before they can be displayed, thus causing the user to think DEBUG has stopped erroneously. Further, DEBUG stores the comparison copy of the bytes in the 51xxH region of memory; so if that area is searched, a match will be found upon the compare bytes themselves.

I - Execute the interrupted program's current instruction and then re-enter the DEBUG facility. This allows the user to single step execute the interrupted program. The user may then observe the changes (or havoc) wrought by each instruction. Single stepping has some pitfalls however:

1. A full timer interrupt sequence may also execute during the single step.

2. Single stepping is not allowed if the instruction location is less than 5200H or jumps to or returns to a location less than 5200H.

3. The DEBUG facility uses the Z-80 instruction RST 30H to trap for the return to DEBUG after the single instruction has been executed. Therefore, the single stepped instruction should not branch upon itself and should not refer to the next byte following itself as the source or destination of data.

C - Performs identical to I except that if the single stepped instruction is a CALL, the entire called routine is executed during the so called single step.

Rdreg,value! - Replaces the interrupted contents of double register dreg with the value value1. Examples:

RDE,C000 - replaces the previous contents of register DE with the hexadecimal value C000.

RHL',7100 - replaces the previous contents of register HL" with the hexadecimal value 7100.

Ldnl,drsl - Relative sector drsl of the diskette mounted on drive dnl is read into DOS's system sector buffer (Model I locations 4200H - 42FFH; Model III locations 4300H-43FFH). DEBUG then shifts into S mode and displays the sector's contents in that buffer. drsl is a decimal (yes, decimal) value. The user is responsible for providing correct values for dnl and drsl as DEBUG makes no checks. Once the sector's contents are in the buffer, the user may treat those bytes as normal main memory, may search them using the F command and may alter them by using the M command. However, altering the sector in the buffer does not alter it on the diskette; the WR command must be executed to store the sector back onto the diskette. Since almost all NEWDOS/80 system programs use the system sector buffer for their diskette reads and writes, the user should not use the L or WR commands if the interrupt took place in DOS (in this case the interrupt address is usually below 5200H but be careful of COPY, FORMAT, etc.) and he/she intends to continue the interrupted program's execution. Warning !!! If passwords are enabled, commands L and WR will be rejected and ERROR state entered. Example:

LI,150 - loads the 151st sector of the diskette currently mounted on drive 1 into the system sector buffer.

#Rdal,drsl - The contents of the system sector buffer (4200H-42FFH on the Model I; 4300H-43FFH on the Model III) are written to relative sector drsl of the diskette mounted on drive dnl. The parameter definitions and restrictions in the use of command L also apply to command WR. If the specified diskette sector is read protected, it is written read protected. Warning!!! If you specify the wrong values for dnl and drsl, you will write the buffer's data to the wrong sector and create for yourself a lot of trouble. Be sure you know what you are doing!!! Example:

WRl,150 - writes the current contents of the system sector buffer to the 151st sector of the diskette currently mounted on drive 1.

Q - Exit DEBUG to DOS READY. The previous program is forgotten. If the system was in DOS-CALL or MINI-DOS, that state is purged.

G[addrl][,addr2][,addr3] - Restore the registers and resume program execution. If addrl is specified, execution resumes at that location; otherwise it resumes at the memory address specified in the PC register. If addr2 is specified, a breakpoint is set for that location by replacing the byte at that location with the single byte Z-80 instruction RST 30H which when executed will cause the DEBUG facility to be reentered. The replaced byte is not lost (it is restored upon DEBUG re-entry), but it is unavailable during the period from DEBUG exit until DEBUG entry. Addr3 is a 2nd breakpoint address. When addr2 is specified, it is not required that addrl be specified. Addr2 and addr3 must not be less than 5200H. Examples:

G7000,8400,8425 will set a breakpoint at main memory locations 8400H and 8425H, and will restore the registers and commence program execution at main memory location 7000H.

G will restore the registers and commence program execution at the main memory location saved in the PC register. If the interrupted program was awaiting input (such as DOS READY or BASIC READY) at the time of interrupt, it is still awaiting input. Even though no cursor is re-displayed (as DEBUG does not remember the cursor state), the user may proceed with key input.

There are many times when, during the execution of a main program, the operator would like to interrupt the main program, execute one or more of the DOS library commands and then resume main program execution without any change having occurred to the main program's state during the interruption. NEWDOS/80 provides such a facility, called MINI-DOS.

In order to use MINI-DOS the following conditions must be met:

1. SYSTEM option AB = N.
2. SYSTEM option A? = Y.
3. Either. (1) interrupts are enabled or (2) the main program is awaiting keyboard input via the standard keyboard input routine and SYSTEM option AJ = Y.

With these conditions satisfied, the simultaneous depression of the keys D, F and G will cause the main program to be interrupted, its register state saved, and MINI-DOS state to be entered. MINI-NEWDOS/80 READY will be displayed. CAUTION, pressing DFG is not recommended while disk I/O is in progress as a fatal error to the diskette is possible; if exit from MINI-DOS is via MDBORT, then there's no problem.

From MINI-DOS state, the operator may execute any of the DOS library commands except APPEND, CHAIN, COPY and FORMAT. Non-library commands or programs may not be executed under MINI-DOS.

When ready to return to the main program, enter the DOS library command MDRET. If the cursor was displayed before DFG, it will be redisplayed. The main program's register state is restored, and the main program resumes its execution. If the main program was awaiting keyboard record input and a partial record was already inputted, that partial record is still in the buffer even though it is not displayed. If the main program was awaiting keyboard input, whether or not any characters had been entered, upon exit from MINI-DOS, the main program is still waiting. Don't be timid; start keying. If the main program was not awaiting keyboard input, it will go on about its business.

If the main program is not to be resumed, entering the DOS library command MDBORT will terminate both MINI-DOS and the main program, with the system going to normal DOS READY.

Though COPY may not be used under MINI-DOS, simple file copies can be done using DOS library command MDCOPY.

NEWDOS/80 is unable to eliminate all cases where the triple key depression results in one or more of the keys being transmitted as input to the main program. This is especially so when system option AJ = N. These spurious keys usually show up on exit from MINI-DOS. The user should back space over them, and should not use triple key depression when the main program is in text overwrite mode.

As an example of MINI-DOS use, start at DOS READY and execute the following:

BASIC

10 PRINT "HELLO": GOTO 10

RUN

The BASIC program is now in an endless loop printing the word HELLO on the display. Simultaneously press the D, F and G keys. The BASIC program's execution is interrupted, and the message MINI-NEWDOS/80 READY appears on the display. Now execute the following DOS commands:

DIR 0
 FREE
 CLOCK
 CLOCK,N
 LIB
 SYSTEM,0
 PDRIVE,0
 MDRET

							
The MDRET command caused the exit from MINI-DOS, and the BASIC program continued execution where it was interrupted- Now, while we have a test program executing, let's try out the entry to DEBUG. Simultaneously depress the 1, 2 and 3 keys. Once again, the BASIC program's execution is interrupted. The DEBUG routine is now active, and the display is loaded with either the X or the S DEBUG display format. Now type in G followed by ENTER. DEBUG is exited, and the BASIC program continues execution. Now, press DFG again, to get back into MINI-DOS. Once there, execute DOS command MDBORT. This causes DOS to forget about the interrupted program, to exit. MINI-DOS and go to normal DOS READY.
						

The DOS commands CHAIN and DO are simply different spellings of the same command; therefore, in this section, only the command word CHAIN will be used where in reality either one can be used.

For most TRS-80 users there are functions which use the same series of DOS commands and/or program responses, and for each of these functions it would save a lot of key stroking, operator time and errors if this keyboard character sequence could be saved in a disk file to be called upon when the operator wishes to execute a specific function.

For example, suppose that each time a reset/power-on is done, the operator keys in the following commands and program responses:

HIMEM,0E800H
Execute DOS command HIMEM

PROGRAMl
Execute program named PROGRAMl

Y
Response to PROGRAMl's 1st query.

50
Response to PROGRAM1's 2nd query.

PR0GSAM2
Upon PR0GRAM1'S completion, execute program

1
Response to PR0GRAM2's 1st query

W0RKF1
Response to PR0GRAM2's 2nd query

W0RKF2
Response to PR0GRAM2's 3rd query

BASIC,RUN"BASPGMl/BAS"
Upon PR0GRAM2's completion, enter BASIC and run BASIC program BASPGMl.

Y
Response to BASPGMl's 1st query.

Subsequent input to BASPGMl is assumed to vary from run to run, is therefore not part of the standard sequence and of no concern here. What is of concern is that this same sequence of keyboard input must be keyed in each time.

However, if this keyboard character sequence was placed in a disk file named, for example, XXX/JCL, then this keyboard input sequence can be triggered to occur by executing the DOS command:

CHAIN,XXX/JCL

The execution of this CHAIN command (see section 2.9) causes keyboard input to come from the file XXX/JCL, starting at the file beginning and transmitting characters as keyboard input when requested by DOS or the executing program. The characters are transmitted upon request until the end of the file is reached, at which time keyboard input is switched back to the normal keyboard. Thus, having keyed in the CHAIN command, the operator may sit back and wait until after BASPGMl has received its first response instead of having to key in the various commands and responses as needed.

Further, since this keyboard sequence is to be invoked at reset/power-on, the operator may avoid even the keying in of the CHAIN command by setting that command up beforehand as the AUTO command (see section 2.4). This is done by executing the DOS command:

AUTO,CHAIN,XXX/JCL

Now, when reset/power-on is done, the CHAIN command is automatically executed, and the operator has nothing to do until after program BASPGMl has received its first response.

Both this process of causing keyboard input to be taken from a disk file and the associated operational mode that NEWDOS/80 is in during that time is called chaining. The files that contain the keyboard character sequences are called chain files.

NEWDOS/80 is not concerned with the creation of chain files; NEWDOS/80 only uses them in response to a CHAIN command (see section 2.9). It is up to the user to decide what keyboard character sequence is to be contained in a chain file, and it is left to the user to build the chain files he/she needs. Probably the simplest way is to use either SCRIPSIT or PENCIL and store the resulting file in ASCII mode. For users that do not have either SCRIPSIT or PENCIL, a BASIC program named CHAINBLD/BAS has been included on the NEWDOS/80 diskette to create and edit simple chain files. To build chain files having other than printable keyboard characters, some other chain file build program must be used.

Chain file creators must remember that, except for any /./ type chaining control records (discussed below), the chain file must contain exactly the keyboard character sequence that DOS or the current executing program expects. Chaining does not guess for you.

During the processing of a chain file, NEWDOS/80 operates in one of two modes, depending upon the setting of SYSTEM option AT.

If SYSTEM option AT = Y, then all requests for keyboard input via the standard keyboard routine are honored from the chain file. This applies to both a request for a record (such as INPUT or LINEINPUT in BASIC) and for a single character (such as INKEYS in BASIC).

If SYSTEM option AT = N, then only requests for full records (such as INPUT or LINEINPUT in BASIC) via the standard keyboard routine at ROM location 0040E are honored from the chain file. Requests for a single byte (such as INKEY$ in BASIC) are honored from the keyboard.

On the NEWDOS/80 Version 2 diskette the user has been provided with (1) the BASIC program CHAINBLD/BAS with which the user can build simple chain files and (2) a sample chain file named CHAINTST/JCL. The instructions for using CHAINBLD/BAS are given in section 6.6. Here, all we want to do is use CHAINBLD/BAS to look at the chain file CHAINTST/JCL. With computer at DOS READY, enter the follow responses:

BASIC RUN "CHAINBLD/BAS:0"
start CHAINBLD/BAS executing

2
chooses file load option

CHAINTST/JCL:0
filespec of file to be loaded into memory

L ;
list first page of chain file

;
list next page of file

D
return to edit menu

Q
return to main menu

5
exit from the program

At each step, study carefully what is displayed. This chain file contains a good example of commands, program responses, and chaining control records. Don't be alarmed at CHAINBLD's 10 second initialization time. Once you have carefully studied the chain file, exit back to DOS and execute the chain file using the DOS command:

CHAIN,CHAINTST:0

Since most chain character sequences are short, usually less than 100 characters, it is a shame to allocate a full granule of 1280 bytes for each such sequence. Therefore, NEWDOS/80 allows a chain file to be divided into sections with the keyboard character sequence making up each section preceded by a section identification record (see /./0 discussion below) excepting that the first section of a chain file need not have a section ID record. If the chain file section that is to be accessed by a CHAIN command is preceded by a section ID record, the CHAIN command must specify the section ID as well as the file.

During chaining, when either end of file or end of section is encountered, NEWDOS/80 terminates chaining without notification and sets keyboard input back to the normal keyboard routine. This also happens if either DOS command CHNON,N or the chaining /./5N function (see /./ below) is executed. If the current program was awaiting input, the operator will have no indication of this change except that all activity will stop. Usually, the operator knows what will be the first display after chaining terminates; so he/she is ready for it.

If a DOS recognized error occurs during chaining, chaining will be terminated with the message CHAINING ABORT displayed to inform the operator.

If the DOS command CHAIN is executed while chaining, chaining simply forgets the previous file and starts chaining within the new file, which may well be the same file and section as the previous one. CHAIN commands are not nested, and there is no RETURN function in chaining.

DOS-CALL is legal during chaining.

During chaining, there are five ways to alter the sequence of keyboard characters.

1. The current executing program may decide to execute a CHAIN or CHNON command via DOS-CALL (CMD"doscmd" in BASIC).
2. A CHAIN command itself may be part of the chain file. However, for the command to be executed, either DOS must be awaiting its next command or the current program executing must be clever enough to detect the CHAIN command record in its normal record processing and execute the CHAIN command via DOS-CALL (CMD"doscmd'* in BASIC).
3. An easier method is by having the chain file contain a /./4 type chaining control record (discussed below) at the point where the change of sequence is to occur. Using the /./ allows the chaining sequence to be changed regardless of whether DOS or a user program is in control and the sequence change takes place without notification on the display. The limitation of this type of sequence changes is that chaining cannot shift to a different file.
4. The DOS command CHNON (see section 2.10) may be part of a chain file. Remember, DOS must be awaiting its next command. If CHNON,N is specified, chaining is deactivated (though the chain file is not closed and file position is remembered for a subsequent CHNON,Y or CHNON,D command), and keyboard input next comes from the keyboard. If CHNON,Y is specified and DOS-CALL is active, chaining continues but the current DOS-CALL level is exited.
5. A /./5 type chaining control record (defined below) may be used in the chain file instead of DOS command CHNON. The /./5 record function is executed even if DOS is not awaiting its next command.

If the CHAIN command is executed via DOS-CALL (CMD"doscmd" in BASIC), the programmer must remember that DOS remains in DOS-CALL executing DOS commands from the CHAIN file until either end of file, end of section, command CHNON,N or command CHNON,Y (see section 2.10) is encountered. Thus, if a program wishes to activate chaining but wants to process subsequent chain input itself, then the first characters of that chain file or chain file section must be either CHNON,Y or CHNON',N.

Chaining has six control records that may be placed within a chain file. Each of these records must start with either a one character or a 4 character identification sequence and must end with the EOL (ENTER) character. In NEWDOS/80 Version 1, only the one character record identification was used; in Version 2, it is recommended that the four character record identification be used, as the four characters are all printable and thus visible during chain file create or edit. The record ID characters are not displayed during chaining. These control records cause chaining to perform the action described for each. For each special record defined below, the four character record ID is given first followed by the alternative one character ID value.

1. /./0 or one byte = 128 (80 hex). This identifies a section ID record, which must be the first record of a chain section, unless the first section within a file is to be unnamed. The rest of the record is the section's ID which is used to match against a CHAIN command's section ID, if it specifies one, or against the section ID specified in a A/4 chain control record. Subsequent file characters until EOF or until but not including the next section ID record are all considered part of this new section. Example:
   /./0XXXXXX identifies subsequent characters as belonging to chain section XXXXXX.
2. /./I or one byte = 129 (81 hex). This causes the rest of the record to be displayed, and then the system waits for the user to press ENTER before continuing. This is a built in pause function. Example:
   /./1MOUNT WORK DISKETTE The message MOUNT WORK DISKETTE is displayed followed by PRESS "ENTER" WHEN READY TO CONTINUE. DOS then waits for the ENTER.
3. /./2 or one byte = 130 (82 hex). The rest of the record is bypassed without further action. This allows the chain file creator/ maintainer to place comment records in the file for documentation without them being displayed.
4. /./3 or one byte = 131 (83 hex). The rest of the record is displayed, but no pause is done. This allows the creator/maintainer to display to the operator what is happening. Example:
   A/3PHASE TWO COMPLETED The message PHASE TWO COMPLETED is displayed. DOS does not wait but instead continues processing chain file input.
5. A/4 or one byte = 132 (84 hex). The rest of the record is a chain file section ID of 31 characters or less. The current chain file is searched for a chain section whose section ID matches that specified in the /./4 record. When found, chaining continues with the first character of that section. If the section is not found, END OF FILE ENCOUNTERED error is displayed and chaining is aborted. Example:
   A/4XXXXXX Sequential chain character processing shifts within the current chain file to the chain section named XXXXXX (see /./0 example above).
6. A/5 or the one byte = 133 (85 hex). The rest of the record is either the character Y, N or D. Using this one character parameter, a CHNON function is performed. The advantage of using the /./5 function rather than an actual CHNON command is that DOS does not have to be waiting for its next command. The disadvantage is that the chaining state change is more subtle. The /./5 function is not for the novice. Examples:

1. A/5N chaining is deactivated though the file is not closed.

2. A/5Y chaining remains active but the current DOS-CALL level, if any, is exited.

The novice chain file creator will find it easiest to use none of the chaining control records described above. As experience is gained, try using the /./3. record to display a comment and the /./I record to display a message and wait for ENTER. Next, try using /./0 records to divide a chain file into sections and then the /./4 record to cause chaining to branch around within a chain file.

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

During chaining and if SYSTEM option BC = Y, the operator may terminate chaining by holding down the up arrow key, or the operator may force a chaining pause by holding the right arrow key, and may resume chaining by pressing ENTER.

NEWDOS/80 allows any machine language program to call the DOS routine at 4419H (see section 3.11) to execute a DOS command or user program. This capability is called DOS-CALL. BASIC uses DOS-CALL to execute the CMD"doscmd" function.

The calling program builds a DOS command in a buffer and terminates it with a 0DH byte. With HL pointing to the command, the DOS routine at 4419H (see section 3.11) is called to cause DOS to execute the command after moving it to its own buffer and converting lower case to upper.

If the DOS-CALL is executing a user program, DOS does not check for conflict between the calling program and the called program. It is the responsibility of both programs to avoid conflicts. An example of a user program executing under DOS-CALL is the execution of SUPERZAP under BASIC through the CMD"SUPERZAP" function.

Furthermore, the registers cannot be used to pass parameters back and forth between the calling and the called programs. On entry to the called program, however, register HL does point to the command parameters. Also, the two bytes at 4403H - 4404H may be used to pass a 2 byte parameter back and forth.

A user program activated under DOS-CALL may itself use DOS-CALL (be careful not to overflow the stack). DOS-CALLs can be nested, with each call activating a new DOS-CALL level.

Upon return from a DOS-CALL, the calling program must check for three states. If Carry is set, an error has occurred that has already been displayed. If the program is to continue execution, then it must decide what to do. If the program is to terminate, it should exit via a jump to 4030H in case this program was itself invoked by DOS-CALL, which will cause an exit to the next higher calling program with C state set.

However, if the returned state is NZ and NC, a DOS error has occurred that has not yet been displayed and the error code is in the right 6 bits of register A (bits 6 and 7 equal 0). If the calling program is to continue operation, it can have the error message displayed by calling AA09H with bit / of register A = 1; otherwise it should exit via a jump to 4409H with bit 7 of register A = 0. This latter action will cause the error message to be displayed and the system goes to DOS READY unless the calling program was itself invoked by DOS-CALL, in which case the error msg will not be displayed and an exit will be taken to the next higher calling program with register A unchanged and NC and NZ states set.

If the returned state is NC and Z, then the called function completed normally. Since all registers except AF are saved at DOS-CALL entry and restored at DOS-CALL exit, the only way a parameter may be passed back is by using the two bytes at 4403H and 4404H (17411 and 17412 decimal). Actually, the higher unused bytes of the DOS command buffer, 4318H - 4367H, can be used for communication each way in DOS-CALL, but the programmer must understand that DOS moves all commands into that buffer before executing them.

NEWDOS/80 has a small routine for dumping the contents of the display screen to the printer. This feature allows the operator to print information that would otherwise be lost as soon as the display is used for something else.

In order to use JKL, the following conditions must be met.

System option AD = Y.

1. Either (1) interrupts are enabled or (2) the main program is awaiting keyboard input via the standard keyboard input routine and system option AJ - Y.
2. DOS must not be currently using its overlay area (main memory locations 4D00H - 51FFH).
3. DOS must not have its overlay inhibit enabled.

With these conditions met, the simultaneous depression of the keys J, K and L will cause the main program to be interrupted, its state saved, and the contents of the display dumped to the printer without any editing except that implied by SYSTEM option AX. If the printer is not ready or drops ready, the system will loop waiting for it and no message will be displayed to the operator.

JKL will substitute a period for each display character that is non-printable as defined by SYSTEM option AX.

Pressing the BREAK key will terminate the JKL function, except if the CPU is hung waiting on the printer.

When the dump is completed, the interrupted program is resumed. The problem of spurious input characters discussed in section 4.2 exists here as well.

In earlier versions of NEWDOS, the JKL routine was always resident in main memory. In Version 2, the JKL routine was very reluctantly moved into a system overlay program, thus making it unusable in certain circumstances where it was usable before. For example, JKL can not be invoked from DEBUG.

NEWDOS/80, like TRSDOS, allows for a very limited form of asynchronous execution. This is accomplished by inserting a user interrupt routine into DOS' s 25ms interrupt chain. The DOS routine (see section 3.8) at Model I location 4410H (Model III location 447BH) must be used to insert the routine into the chain, and the DOS routine 4413H (see section 3.9) must be used to take the routine out of the chain. Refer to these two sections for the required format of the user interrupt routine and how it is invoked.

Again, the user is reminded that the use of user interrupt routines under NEWDOS/80 is incompatible with that under TRSDOS.

The DOS system consists of 14 program modules which execute from three areas. The resident module SYS0/SYS resides in all the non-data areas from 4000H to 4CFFH. The modules SYS1/SYS through SYS5/SYS, SYS7/SYS through SYS9/SYS and SYS14/SYS through SYS17/SYS all share the DOS overlay area 4D00H - 51FFH (only one module at a time can be in that area). SYS6/SYS executes from both the overlay area and the 5200H - 6FFFH area.

NEWDOS/80's Disk BASIC enhancements to the TRS-80's ROM BASIC consists of a main resident module and 8 overlay modules. The modules SYS10/SYS through SYS13/SYS and SYS21/SYS execute from DOS's overlay area, 4D00H - 51FFH. The modules SYS18/SYS through SYS20/SYS execute from BASIC's overlay area, 5200H -56FFH. All of BASIC's modules, except BASIC/CMD, are loaded as needed and must be on the system diskette when needed.

Reduced sized systems can be created, if passwords are disabled, by COPYING the full NEWDOS/80 diskette onto a new diskette and then KILLING the unwanted files. A minimum system to handle open's and close's will consist of 10 granules (BOOT, DIR, SYS0-SYS4). If the DEBUG facility is to be used (including BASIC'S CMD"D"), add SYS5. Section 5.2 indicates which additional modules must be added for the various DOS library commands. If BASIC is to be used, section 5.3 indicates which BASIC modules must be added, and section 5.2 indicates which DOS modules must be added if DOS library commands are to be executed via BASIC's CMD"xx" statement.

If the system module loader finds the module's directory entry inactive or encounters an error during loading, then one of the following occurs:

If SYS4 is an active module in the system, then SYSTEM PROGRAM NOT FOUND error will be displayed via a jump to 4409H.

If the jump to SYS4 via 4409H finds SYS4 not in the system, then the Z-80 HALT instruction is executed which on the Model I causes reset and on the Model III stops the computer (the operator must manually press reset).

Modules included in this category are SYS1/SYS thru SYS21/SYS. If any of BASIC overlay modules fail load, the user must carefully execute BASIC * to get back the basic program text.

CAUTION!!! Once a system file has been killed from a system diskette, it cannot be restored by simply copying it from another system diskette. The DOS system loader requires that system file FPDEs be in specific FDE slots in the directory and that all of a system file's space be accounted for in the first extent element. Further, SYS0/SYS must occupy the same granules as it did before kill, and it is recommended for efficient system operation that all other system files also occupy the same granules. Once the FPDE has be properly reconstructed, DOS command COPY can then be used to copy the file's contents.

For the Model I, NEWDOS/80 and TRSDOS diskettes are interchangeable provided the NEWDOS/80 diskette's directory consists of only 2 granules (see DDGA parameter of FORMAT, section 2.22, and COPY, section 2.14), and is set up for 10 sectors/track, 2 granules/lump and 5 sectors/granule operations (5 sectors per granule is standard for NEWDOS/80). The files on the diskettes may not be operationally interchangeable between the two systems; system modules, BASIC, ELECTRIC PENCIL, SCRIPTSIT, etc., definitely are not though the files they manipulate are.

For the Model III, the directories of NEWDOS/80 and TRSDOS diskettes are NOT compatible; a TRSDOS Model III diskette may not be used directly with NEWDOS/80 and NEWDOS/80 diskettes may not be used directly with TRSDOS Model III. If the NEWDOS/80 single density diskette has a directory of Model I standard position and size, the Model III TRSDOS has a conversion program to copy the data to a Model III diskette. The COPY function of NEWDOS/80, Version 2, also has a way of copying one, some or all files of a Model III TRSDOS Version 1.3 or higher diskette to or from a NEWDOS/80 diskette (see sections 12.1 and 2.14).

NEWDOS/80 makes all FDE's of a diskette, except those for BOOT/SYS and DIR/SYS, available for use; thus, a 2 granule directory on a newly formatted data diskette has 62 FDEs available. NEWDOS/80 allows the directory to be allocated with up to 6 granules during diskette formatting (see DDGA parameter of PDRIVE, FORMAT and COPY), thereby providing for a maximum of 222 available FDEs.

A diskette's directory always starts on a lump boundary and contains the GAT sector followed by the HIT sector followed by 8, 13, 18, 23 or 28 FDE sectors, depending upon the number of 5 sector granules allocated to the directory (see the DDGA parameter of PDRIVE, FORMAT and COPY). The user is encouraged to study the directory structure by use of program SUPERZAP(see section 6.1). The starting lump number of the directory is always contained as a hexadecimal value in the 3rd byte of each diskette's 1st sector; this value is used by DOS to find the directory.

5.6.1. - The GAT (Granule Allocation Table) Sector.

The GAT sector is the first sector in the directory and contains the following information:

Granule free/allocated table. Each of relative bytes 00H - 5FH corresponds to a lump and contains the free/allocate status bits for all of that lump's granules. The number of granules per lump is specified by the GPL parameter of PDRIVE and is a value between 2 and 8. The lump's 1st granule's bit is bit 0 (counting from the right), the 2nd granule's bit is bit 1, and so on up to the 8th granule. If the bit equals 0, the granule is free. If the bit equals 1, the granule is allocated or non-existent.

Granule existence table. Relative bytes 60H - BFH correspond to relative bytes 00 - 5FH. If a bit within a byte equals 0, then the corresponding granule for that lump exists and is useable. If the bit equals 1, the corresponding granule does not exist, must not be used and the corresponding bit in 00 - 5FH must equal 1. Actually, though NEWDOS/80 creates these existence bytes during format, it does so only for compatibility with the old style TRSDOS diskettes (wherein these bytes were known as lockout bytes). Actually, NEWDOS/80 never sets a granule non-existent. When necessary, the granule existence table is discarded altogether to make additional GAT sector bytes available to the granule free/allocated table.

In order to maximize the amount of diskette space controlled by the GAT sector, NEWDOS/80 Version 2 allows the free/allocated section of the GAT to extend through, and thereby replace, the existence (or lockout) portion of the GAT. In this case, the free/allocated status bytes are GAT relative bytes 00H through BFH instead of 00H through 5FH as discussed above. This extension is automatically done during format if the number of lumps for the diskette exceeds 60H (96 decimal).

The diskette s encoded password is in relative bytes CEH - CFH.

The diskette name is in relative bytes D0H - D7H.

The diskette date is in relative bytes D8H - DFH.

If a system diskette, the AUTO command to be used at reset is contained in relative bytes E0H - FFH. If the first byte of this area is 0DH (EOL), then no AUTO command exists for this system diskette.

5.6.2. - The HIT (Hash code Index Table) Sector.

The HIT sector is the 2nd sector in the directory. It serves as an index into the FPDEs for the diskette's files and also serves to indicate which FDEs are free and which are in use. If a HIT sector byte equals 0, the corresponding FDE either doesn't exist or is free. If a HIT sector byte is non-zero, the corresponding FDE is in use, and if in use as a FPDE, the HIT sector byte's value is a hash code formed from the contents of the FPDE's 6th through 16th bytes (the name and name extension). Thus, when it is necessary to look up a file in the directory, the hash code is computed and the HIT sector searched for a match. If a match is found, the corresponding FDE sector is read and the corresponding FPDE tested for matching name and name extension. If this match fails, the HIT sector search is continued.

The relative position of the HIT byte within the HIT sector is exactly equal to the corresponding FDE's DEC code; for it is by using the DEC code as an index into the HIT sector that the system knows which HIT byte to set non-zero when a FDE is allocated and to set to zero when a FDE is freed.

The HIT sector's 32nd byte is used differently in NEWDOS/80 than all the other HIT sector bytes. This byte contains the count of extra FDE sectors allocated to the directory; the legal values are 0, 5, 10, 15 and 20. This value is set up when the diskette is formatted.

On old Model I diskettes the value of the HIT sector byte for DIR/SYS (2nd byte of the HIT sector ) was 2CH which is not the correct value. This incorrect value causes FILE NOT IN DIRECTORY error to appear when the directory file itself is being accessed. For such diskettes, use SUPERZAPto put the correct value of C4H into the HIT sector 2nd byte.

5.6.3. - The FDE (File Directory Entry) Sectors.

The rest of the directory's sectors are FDE sectors, with each 256 byte sector containing eight 32 byte FDEs. A FDE is free if bit 4 of its 1st byte equals 0 and in use if the bit equals 1. An in-use FDE is a FPDE if bit 7 of its 1st byte equals 0 and a FXDE if the bit equals 1. When an FDE is freed, only the 4th bit of the 1st byte is zeroed and the corresponding HIT sector byte is zeroed. Nothing else is changed. However, the user may zero the entire 32 bytes of each unused FDE by using the C function of DIRCHECK, thus obtaining a Leaner looking directory.

1st byte.

Bit 7=0. Indicates FPDE, vice FXDE.

Bit 6=1. If a system file.

Bit 5=0. Undefined.

Bit 4=1. Indicates FDE allocated to a file.

Bit 3=1. If the file has the invisible attribute.

Bits 2-0. Access level code (see PROT parameter of ATTRIB, section 2.3).

2nd byte.

Bit 7=0. The file may be allocated more space when necessary. Bit 7 = 1 prohibits this. DIR, ATTRIB, CREATE and the DOS file space allocation routine use this bit.

Bit 6 = 0. The DOS file close function may deallocate any excess granules above the EOF (i.e., apparently not being used by the file). Bit 6=1 prohibits this. DIR, ATTRIB, CREATE and DOS file close use this bit.

Bit 5=1. At least one sector of the file has been written to, either new data or updated data, since the last time this bit was set to 0. DIR, ATTRIB, CREATE, PROT, COPY and the DOS sector write routine use this bit.

Bits 4 to 0. Undefined and reserved for future definition.

3rd byte - 0. Currently undefined and reserved for future definition.

4th byte - The lower order byte of the file's EOF. This value is the EOF position within the EOF sector. See FCB 20th byte below.

5th byte - The logical record length (LRECL) (0 = 256) in bytes. When a file is created via a 4420H vector call, the value from register B is stored here. When an existing file is opened, even as a new output file, this value is not updated. This value is never used in NEWDOS/80. The value stored in FCB+9 at open time is that from register B, not from the FPDE.

6-13th byte - The file name, padded on right with blanks if necessary.

14-16th byte - The file name extension, padded on right with blanks as necessary.

17-18th byte - The encode of the update password.

19-20th byte - The encode of the access password.

21st byte - The middle order byte of the EOF.

22nd byte - The high order byte of the EOF. The 4th, 21st and 22nd bytes are a 3 byte EOF value. This EOF value, instead of being in RBA format as are the EOF and NEXT fields of the FCB, is maintained in the old TRSDOS format which has the following rules:

If the lower order byte of the EOF equals 0, the EOF is in RBA format.

If the lower order EOF byte is not 0, then the EOF value in the FPDE is equal to the actual RBA value plus 256 (the high two byte value of the EOF is incremented by 1).

NEWDOS/80 maintains the directory FPDE EOF field in this manner in order to maintain compatibility with the old Model 1 TRSDOS 2.3 diskettes (see section 12.1). New EOF values for a file are placed into the FPDE only during file-create, write-EOF and DOS close. Thus, if the system fails requiring reset, the user can expect that any file open for output at the time of failure will contain the new data but usually not the new EOF.

See section 12.1 for EOF and NEXT incompatibility with other DOSs.

23-30th bytes. - Four 2 byte pairs (extent elements), each specifying a contiguous area of the diskette assigned to this file. The format of an extent element is:

1st byte:

255 (0FFH) means the end of the extent elements for this file.

254 (0FEH) means the next byte contains the DEC for the first or next FXDE assigned to this file.

0 - 253 (0 - 0FDH) equals the number of the diskette's lump in which the area starts. Other considerations including the number of lumps the GAT sector can handle limit this value to the range 0 - 191. This value is also the relative location within the GAT sector of the byte associated with this lump.

2nd byte (when the 1st byte is less than 254)

left 3 bits equals the number of granules (0-7) from the start of the lump to the start of the area.

right 5 bits equals the number less one of contiguous granules assigned to this area.

31-32nd byte. - An extent element whose 1st byte is either 255 or 254.

When a file has more than 4 space areas assigned, the additional extent elements are contained in FXDE's assigned to the file. The format of a FXDE is:

1st byte. - Bits 7 and 4 are both 1 to indicate a FXDE; all other bits of the byte equal 0.

2nd byte. - The DEC for previous FXDE or FPDE of this file. This is a backward chain. The previous entry's 31st byte will be 254, and the 32nd byte will contain the DEC of this FXDE.

Bytes 3-22. - Unused and should equal 0.

Bytes 23-32. - Are as defined for the FPDE.

In order that file information be read from or written to a diskette, a link must be created between that file and the user program. The link is created by the DOS open function (see sections 3.13 and 3.14) and dissolved by the DOS close function (see section 3.15). During the time the link is in existence, the control information for that link is maintained in a 32 byte area of main memory known as a File Control Block. At open time, the user specifies where in user memory this FCB is to be. While this link is in existence, the FCB's area of main memory must not be used for any other purpose. DOS does not remember where the FCBs are. The user informs DOS of which FCB to use for each function that is to use a FCB. Thus, the link is effectively dissolved by simply never using the FCB again in a function call or by using the FCB in the open of a new link. Remember though, if writing to a file where the EOF is being changed, either a DOS close or DOS write-EOF (see section 3.28) function must be done to assure the EOF is properly placed in the FPDE.

At open time (a call to DOS 4420H or 4424H), the caller provides in register DE the address of a 32 byte main memory area for use by the system as a FCB while the file is open. The user must have placed the filespec (terminated by a 0DH or 03H byte) for the desired file into the FCB's 1st bytes, and the DOS close function will attempt to put it back there when done. NEWDOS/80 will accept the Model III TRSDOS 50 bytes area but only uses the first 32 bytes. While the FCB is open, the format for the 32 byte FCB is:

1st byte.

Bit 7 = 0. The file may be allocated more space when necessary. Bit 7 = 1 prohibits this. DIR, ATTRIB, CREATE and the DOS file space allocation routine use this bit.

Bit 7 = 1. The link is in existence (i.e., an open has been done).

Bit 7 = 0. The link is not in existence (i.e., either an open has not been done or a close has been subsequently done).

Bits 6-2 = 0. Undefined.

Bit 1=1. The value in the FCB's NEXT and EOF fields are RBAs within the diskette, rather than the file. This allows the user to I/O directly to diskette sectors, bypassing the file concept altogether. This bit should never be 1 during byte I/O via the 0013H or 001BH calls.

Bit 0=1. Sectors written to the file are written read protected in the same manner as DOS writes directory sectors. This bit should never be 1 during byte I/O via the 0013H or 001BH calls.

2nd byte.

Bit 7=1. Either single byte operations or logical record operations (record length in FCB's 10th byte) are being done via this FCB. NEXT value is maintained at the next byte to be read or written. This bit is set to 1 at open time if register B is not 0. It is also set to 1 whenever byte I/O is done via the 0013H or 001BH ROM calls.

Bit 7=0. Read and write operations are by full 256 byte sectors with the FCB's NEXT value incremented 256 bytes upon the completion of each successful I/O.

Bit 6=0. The FCB's EOF value is to be set equal to the FCB's resulting NEXT value on every successful write operation.

Bit 6=1. The FCB's EOF value is to be set equal to the FCB's resulting NEXT value only for those successful write operations resulting in the NEXT value exceeding the current EOF value.

Bit 5=0. The FCB's buffer contains the current file sector's data. If bit 5=1, the buffer does not contain the current file sector's data; if needed, that sector's data must be read into the buffer.

Bit 4=0. The FCB's buffer does not contain updated data not yet sent to the file. If bit 4=1, the buffer does contain updated data not yet sent to the file. During DOS close, if this bit is 1, the sector data in the buffer is automatically written to disk. This updated data is also written on every 443FH and 4451H call and on every 4442H, 4445H, 4448H and 444EH call that positions the file within a different sector.

Bit 3=1. This FCB is in the NEWDOS/80 Version 2 format for the 18th - 32nd bytes. This bit is set to 1 by DOS open. If bit 3=0, the FCB is in the old format and is illegal in NEWDOS/80 Version 2.

Bits 2-0. Access level code (see PROT parameter of ATTRIB, section 2.3).

3nd byte.

Bits 7-5. These bits are defined the same as those in the FPDE 2nd byte (see section 5.7). If bit 5 equals 0, the DOS sector write routine sets the bit to 1 in both the FCB and the FPDE just before it actually writes the current sector to disk.

Bits 4 - 0. Undefined and reserved for future definition.

4-5th byte. - The main memory address of the FCB's buffer. The user determines where the buffer is to be and puts this address into register HL before the call to the DOS open routine. Sectors are read from disk into this buffer and written to disk from this buffer.

6th byte. - The low order byte of the FCB's NEXT field. This is the relative position within sector value. See discussion for FCB 12th byte below.

7th byte. - The relative number of the drive containing the diskette containing the file.

8th byte. - The DEC code of file's FPDE. After the FCB is opened, this DEC code is the link between the open FCB and the file's directory information as the FCB itself no longer contains the filespec.

9th byte. - The low order byte of EOF. This is the relative position within the EOF sector. See discussion of FCB 14th byte below.

10th byte. - The logical record length (LRECL) (0 = 256) for records of this file. This value is supplied in register B by the caller at open time. If not 0 at open time, bit 7 of the FCB's 2nd byte is set to 1, and subsequent DOS sector read or write calls must contain, in register HL, the address of the logical record to be moved to the FCB's buffer (write) or filled from the FCB's buffer (read).

11th byte. - Middle order byte of the NEXT field.

12th byte. - High order byte of the NEXT field. The 12th, 11th and 5th bytes form a 3 byte RBA within the file of the next byte to be processed, either input or output.

For single byte and logical record I/O, DOS maintains the FCB NEXT field in exact RBA format.

For full sector I/O, DOS also maintains the NEXT field as an exact RBA, but there are subtle actions by DOS that can give trouble if the user is not aware of them. DOS does not change the lower order byte of the NEXT field during full sector I/O. Normally, this byte is zero, and that's fine. However, the user can set this byte non-zero or if the previous I/O done was in single byte or logical record mode the lower order byte will probably be non-zero. The user must be aware of the following rules:

During full sector reads, all three bytes of NEXT participate the EOF check just as for single byte and logical record reads.

During full sector write, when the low order byte of the NEXT field is non-zero, the NEXT field is not advanced 256 bytes upon the successful completion of the write and EOF, if it is updated, assumes that non-advanced NEXT value. The rationale here is that if the NEXT field's lower order byte is zero, the value of NEXT after the successful write is to be at the first byte of the next sector, but if the NEXT field's lower order byte is non-zero, the value of NEXT after the successful write is to remain within the sector just written.

See section 12.1 for discussion of NEXT and EOF field incompatibility with other DOSs.

13th byte. - Middle byte of the EOF field.

14th byte. - The 14th, 13th and 8th bytes form 3 byte RBA within the file of the end-of-file (the 1st byte beyond the file's last data byte). This value is initialized from the FPDE at open time, and is updated at sector, logical record or byte write time under control of the FCB 2nd byte, bit 6. See section 12.1 for discussion of NEXT and EOF field incompatibility with other DOSs.

15-22nd byte. - Identical to 23-30th bytes of FPDE.

23-24th byte. - For the current FXDE whose 4 extent elements are in the FCB 25th - 32nd bytes, the number in this field represents the relative granule number of that FXDE's 1st extent's 1st granule. If that value equals 0FFFFH, then no FXDE is represented in the 25th-32th bytes.

25-32nd byte. - Identical to 23-30th bytes of the current FXDE, if any.

Discussion of FCB bytes 17-32:

The definition for FCB bytes 17 to 32 has changed from what it was in NEWDOS/80 Version 1 and Model I TRSDOS. It was assumed that very few user programs ever referred to these bytes as they serve only to reduce the number of directory accesses done by the resident DOS. However, some users (such as the old SUPERZAPcoded in BASIC) have made use of the old definitions to get around having to open a file when diskette, rather than file, I/O was wanted. NEWDOS/80 Versions 1 and 2 have provided a diskette, as opposed to file, I/O method (see FCB 1st byte, bit 1 definition); that method should be used and those old pseudo FCB methods MUST be discarded to run with NEWDOS/80 Version 2. Failure to do so could be catastrophic; NEWDOS/80 Version 2 has activated bit 3 of FCB 2nd byte in an attempt to head off these bad pseudo FCBs.

This change to the FCB 17-32nd bytes allows the FCB to contain all of a file's extent information for any file having 8 or less extents (DIR with the A option will display how many extents a file has). If the file occupies contiguous diskette space, 8 extents is enough for approximately 300,000 bytes (or 270,000 bytes if the directory is spanned by the file's space).

If the file has more than 8 extents, meaning that more than one directory FXDE is assigned to the file, then the FCB contains space information for the file's 1st 4 extents and the 1 to 4 extents of the FXDE last having a sector read or written. It is quite possible for large randomly accessed files to require a lot more directory accesses than was done under NEWDOS/80, Version 1.

Program SUPERZAP/CMD provides the user with the means to read and write standard 256 byte diskette sectors or any part of main memory, except writing to ROM. Learning to use SUPERZAP is strongly recommended for all NEWDOS/80 owners. If corrections (known as zaps or patches) are to be made to your NEWDOS/80, Apparat will distribute them in written form for application using SUPERZAP. You must know how to us DFS and MODxx. In learning to use SUPERZAP, do your learning on a diskette having data that you can afford to lose!!!!!

Certain diskettes are written in non-standard sector formats and are thus inaccessible to SUPERZAP. There exist other programs that read anything that is on a diskette, but do not have some of the other SUPERZAP features. The user, at some time, will probably want to buy one of these other programs from the vendors that sell them.

SUPERZAP operates in both upper and lower case.

Where numeric values are inputted and unless otherwise specified, SUPERZAP assumes DECIMAL unless the value is suffixed with the character H to indicate hexadecimal.

6.1.1. Function Modes

The menu displays the functions available. The user keys in the selected function's characters and then presses ENTER. The SUPERZAP functions are as follows:

DD - Display a Disk sector. SUPERZAP will ask for the drive number and the number of the relative sector within the diskette, read the sector and display it.

DM - Display a 256 byte page of main memory. SUPERZAP will ask for a memory address, truncate it to a 256 byte boundary and display the page.

DFS - Display a File's Sector. SUPERZAP will ask for the file's filespec. Next, SUPERZAP will ask for the relative sector number within the file and will display that sector.

DTS - Display track's sector. SUPERZAP will ask for the drive number, track number and the number of the relative sector on the track. It will then read the sector and display it.

DMDB - Display Memory Dump Block. SUPERZAP will ask for the filespec of the memory dump file (created by DUMP, see section 2.20). It will display the dump's base address. Next it will ask for a main memory address within the range of the dump, truncate it to a 256 byte boundary and display the memory page.

VDS - Verify Disk Sectors. SUPERZAP will ask if the operator wants a pause when a read protected sector is encountered. Next, SUPERZAP will ask for the drive number and the number of the relative sector on the diskette of the 1st sector to be verified. Lastly, it will ask for the number of sectors to be verified. It will then proceed with the verify which consists simply of reading each sector within the range specified. When a protected sector is encountered and if a pause was requested, SUPERZAP will display the sector's location and wait for the operator to press ENTER before continuing. VDS is a fast way of finding bad sectors on a diskette that the user suspects have gone bad. While verifying is being done, VDS may be cancelled by pressing up-arrow.

ZDS - Zero Disk Sectors. SUPERZAP will ask for the drive number and the number of the relative sector on the diskette of the first sector to be zeroed. Next, it asks for the number of sectors to be zeroed. The zeroing is then done. The read protection status of each sector is not changed.

CDS - Copy Disk Sectors. SUPERZAP will ask for the drive number and the number of the relative sector on the diskette of the source (where the data is coming from) range's 1st sector. Next, it will ask for the same data for the destination (where the data is going to) range's 1st sector. Lastly, it will ask the number of sectors to be copied. The copy is then done. Destination sectors are each assigned the read protection status of the corresponding source sector.

CDD - Copy Disk Data. This function differs from CDS in that any string of diskette bytes may be copied. SUPERZAP will ask for the drive number and the number of the relative sector on the diskette of the sector containing the source range's 1st byte and then ask for that byte's offset within the sector. It will ask for the same information for the destination range's 1st byte. Lastly, it will ask for the number of bytes (65535 is the maximum allowed) to be copied. The copy is then done. The read protection status of the destination sectors is not changed.

DPWE - Display PassWord Encode. SUPERZAP will ask for the password, encode it and display the resulting encode in hexadecimal as it would appear in a directory FPDE.

DNTH - Display Name/Type hashcode: SUPERZAP will ask first for the filename and next for the type (name extension). It will then hash them and display the resulting hashcode in hexadecimal as it would appear in the directory HIT sector.

EXIT - End SUPERZAP and exit to 440DH (DOS READY).

Since ZDS, CDS and CDD change diskette data, the user is first asked if he/she is sure this function is wanted, just in case the wrong function was keyed.

For CDS and CDD, the copy normally proceeds in ascending byte order for both the source and destination. However, if the highest source byte is within the destination range, the copy is in descending byte order to avoid destructive overlap.

All disk I/O's are done through the normal DOS sector I/O routines. Thus, if an error occurs, system option AM and AW I/O try counts are in effect.

For VDS, ZDS, CDS and CDD, if a disk I/O error results, the operator will be offered the choice of retrying, skipping the sector or terminating the function. In many cases, repeated retrying will eventually work. If the error sector was a source sector, skip will cause the associated destination bytes to receive whatever happens to be in the source's buffer; this should be no problem as the user is faced with a reclaim job anyway.

When SUPERZAP is waiting for a numeric value, keying an X as the value will cause SUPERZAP to terminate the function and return to the menu. If SUPERZAP is waiting for a filespec, a null parameter will terminate the function.

When any of DD, DM, DFS, DTS or DMDB is suffixed with ',P', the sectors or memory pages will be printed as well as displayed. For DD,P, DFS,P or DTS,P, the user will be asked for the number of sectors to be printed. For DM,P or DMDB,P the user will be asked for the number of bytes. If the printer is not ready or drops ready, SUPERZAP will loop waiting on it without operator notification. Pressing the P key will cause printing to pause; press ENTER to continue. Pressing the H key will terminate printing.

6.1.2. Display Mode

For DD, DM, DFS, DTS and DMDB, while a sector or memory page is displayed, SUPERZAP is in the display mode and waits for a display mode command. Except for the F and L commands, the keyed command bytes are not displayed and do not require termination with ENTER; the command is executed as soon as all characters of a display mode command have been keyed. The display mode commands are:

X The current function is terminated and SUPERZAP returns to the menu.

g Redisplay the same sector or memory page.

+ or ; Display the next higher sector or memory page.

- Display the next lower sector or memory page.

J Restart the same function.

R Restart the same function, retaining the 1st parameter unchanged.

SCOPY DD and DTS only. The current sector is to be copied to a specified sector. SUPERZAP will ask for the destination sector's drive number and relative sector number. The destination sector may be the same as the source sector. SUPERZAP will read the destination sector and report its status. Then the source sector's contents are written to the destination sector. SCOPY is useful when a sector is found to have bad parity but, with the exception of a few bytes, is intact; by SCOPYing upon itself, new parity will be generated, and the sector can then be repaired. It is also useful for altering a sector's read protect status.

When SUPERZAP is in the display mode, it has a diskette, file, main memory or memory dump file search capability. The match is on 1 to 4 hexadecimal bytes (without the suffixed H) which are represented by aa,bb,cc,dd. When the search finds a match, the sector or memory block containing the first byte of the match is displayed with a thin vertical blinking cursor to mark its position. That cursor will disappear as soon as a key is depressed; however, the associated 'find' position is remembered in case the search is to be continued. When SUPERZAP is in display mode, the following commands to perform searching may be keyed in, terminated by ENTER.

F,aa,bb,cc,ddThe 1 to 4 hexadecimal match bytes are stored, and the search starts at the first byte of the diskette (if DD or DTS mode) or file (if DFS or DMDB mode) or main memory (if DM mode).

F,The same as above except the previously established match bytes are used.

Fxx,aa,bb,cc,ddThe 1 to 4 hexadecimal match bytes are stored, and the search starts within the current sector or block at the xxth relative byte where xx is a 2 digit hexadecimal number without the suffixed H.

Fxx or Fxx,The same as above except the previously established match bytes are used.

FThe search continues at the first byte following the position of the first byte of the last match, and the search uses the previously established match bytes.

L,aa,bb,cc,ddThis command is to be used instead of F,aa,bb,cc,dd when, in DFS mode, the file being searched is standard load module (i.e., SUPERZAP/CMD, LMOFFSET/CMD, etc.) and the user wants SUPERZAP to purge out all except actual object code bytes from the search. This allows a load module file search for two or more bytes without the imbedded loader control information interfering with the match. The resulting display will still contain the loader control information; the user must be prepared to occasionally see this control information imbedded within the matching bytes. Usually, but not always, this control information is 4 bytes long with the first byte being a hexadecimal 01. Except for purging this control information from the match, L,aa,bb,cc,dd works the same as F,aa,bb,cc,dd. The F command may be used to continue an L type search.

L,The same as above except the previously established match bytes are used. MODxx DD, DM, DFS and DTS only. SUPERZAPenters modify mode and positions the cursor to the first hex digit of relative byte xx (value 00H - FFH) of the current page or sector.

EXITEnd SUPERZAP and exit to 402DH (DOS READY).

If an error occurs during the keying in of a display mode command, the partial command is ignored and the sector or block is redisplayed again.

6.1.3. Modify Mode

SUPERZAP enters modify mode upon execution of the display mode command MODxx.

This mode allows the changing of individual bytes within the current disk sector or memory page. Responses while in modify mode are defined as follows:

Hexadecimal digit character- 9 or A - F.The hex digit at the current cursor position is replaced by the new hex digit, and the cursor is advanced one position. If the cursor wraps around, an error will occur if the next character inputted is a hex digit character. Replacements in a main memory page are for real while replacements in a sector are buffered until the sector is written or a 'Q' command cancels the pending update.

Space or right arrow.The cursor is advanced one position.

Left arrow.The cursor is retarded one position.

Shift right arrow.The cursor is advanced 4 positions.

Shift left arrow.The cursor is retarded 4 positions.

Down arrow.The cursor is advanced one display line.

Up arrow.The cursor is retarded one display line.

ZTxxThis sequence is displayed vertically in display7 and must terminate with ENTER. All hex digits from and including the cursor position to and including the 2nd hex digit of relative byte xx are zeroed. The cursor is left positioned to the 1st hex digit following relative byte xx, and if wrap around occurs, the next input char may not be a hex digit.

RTxx,jkThis command is similar to ZTxx except that each byte's 1st digit is replaced with the hex digit j, and each byte's 2nd digit is replaced with the hex digit k.

QFor sector operations only. Modify mode is terminated, any changes in the buffer are discarded, and SUPERZAP returns to display mode.

ENTERFor memory page operations, modify mode is terminated, and SUPERZAP returns to display mode. For sector operations, the operator is asked if he/she really wants to update the sector now. If not, SUPERZAP continues in modify mode. If so, the sector (with any changes) is written back to disk, modify mode is terminated, and SUPERZAP returns to display mode.

When modify mode encounters an error, it will display 'INVALID MODIFICATION MODE CHAR. REPLY '*' TO CONTINUE', Upon receiving * , SUPERZAP returns to modify mode.

Program DISASSEM/CMD disassembles Z-80 object code from a standard TRS-80 load module or from main memory. The disassembled code is sent to the display or to the printer. Generated source text may be sent to disk and a location cross reference may be produced.

Responses to the query 'OBJECT FROM MAIN MEMORY OR DISK?' (M OR D):

1. null or D   - Object is a disk load module.

2. M - The object code is in main memory.

1. Respond to the query 'OBJECT VIRTUAL BASE ADDRESS? (HEX)' with the 1 to 4 digit hexadecimal location value (without suffixed H) where the object code is considered to execute from, whether or not it is actually there now. In the listing, this value will be the first instruction's printed location value.

2. Respond to the query 'OBJECT REAL BASE ADDRESS (HEX)?' with null (meaning the real and virtual locations are the same) or with the 1-4 digit hexadecimal main memory location (without suffixed H) where the disassembler will actually find the object code.

Responses to the query 'ANY OPTIONS?':

1. null - null No more options to be specified.

2. PTR- PTR The output is sent to the printer instead of the display.

3. BFSP - BFSP Bypass Full Screen Pauses. In normal operation the disassembler pauses whenever the display screen is full or whenever a break occurs in the sequential locations of the disassembled file. The disassembler waits for (1) ENTER to continue, (2) X to terminate the disassembly or (3) V (object from main memory only) to restart the disassembly at a new location. The BFSP option bypasses this pausing, causing display to occur as fast as the disassembly can proceed. This option is automatically invoked if option PTR is specified.

The remainder of the options are legal only when the object code is from disk:

4. NCR - The location reference table is not to be built and no display or listing done of it.

5. NIP - Do not print or display the disassembled instructions.

6. STD - Source To Disk The disassembled code is to be sent to disk in the format of an EDTASMsource text file. See discussion below.

7. FGN=xxx - First Generated Name xxx is the 3 alphabetic character name of the first name to be assigned during the STP action described below. The default name is AAA.

8. RTD - The location reference table is to be stored onto disk. After the reference table is built, the program will ask for the 'REFERENCE TABLE FILESPEC?'. Respond with the filespec of the file to contain the reference table. Reference table files can be used (by a user-created program) to merge the reference tables of two or more programs. See below for file format.

9. REA - Enable listing of all types of references; this is the default.

10. RE& - Enable list of the specified reference type where '&' is one of L, P, R, S, T, U, V, W or X. Reference types are defined at the beginning of each location table listing.

11. RIA - Disable list of all types of references.

12. RI& - Disable listing of the specified reference type where is one of L, P, R, S, T, U, V, W or X.

The disassembler operates through four phases:

1. If object code from disk and option NCR not specified, DISASSEM displays 'BUILDING CROSS REFERENCE TABLE' and passes through the object code building the location reference table. For a large disassembly this will take some time. If insufficient main memory for the table, the disassembly will terminate.

2. If RTD option specified, this phase writes the location reference table to disk.

3. List disassembled instructions to display or printer. If STD specified, the resulting text is also written to disk. On the disassembled instruction print lines,1 indicates the number of references to bytes of the instruction; the value is hexadecimal with blank meaning and F meaning 15 or more references. Col w20umn 2 indicates which bytes of the instruction have been referenced. If blank and col w75umn 1 non-blank, then only the instruction's 1styte is referenced; otherwise the hex digit represents a 4 bit binary mask of which bytes, from the left, are referenced.

4. If object is from disk and NCR is not specified, the location reference- table is displayed or printed. The definitions of the reference type codes are given first. Then, in ascending numeric order, every referenced location is listed with the location of every referencing instruction. Suffixed to each referencing location value is the reference type code for the Z-80 instruction making the reference.

If the disassembler finds something wrong with the object module, either 'DISK OBJECT FILE FORMAT NOT AS EXPECTED' or 'PAST END OF FILE' will be displayed and the disassembly will terminate.

While the disassembled instructions are being displayed or printed, holding down P will cause a pause; press ENTER to continue. Holding down X will terminate the disassembly. At most other times when DISASSEM is awaiting a user response, the disassembly may be terminated by holding down up-arrow and pressing ENTER.

For main memory disassemblies, the operator may shift the disassembly point at will. When the disassembly is paused, keying V will display the query 'VIRTUAL RESTART LOCATION? (HEX)'. The operator responds a 1 to 4 hexadecimal digit value, which is the main memory location where the disassembly is to restart.

If the PTR option is specified and after all options have been specified, the following occurs:

Respond to the query Q LINES PER PAGE, EXCLUDING TOP AND BOTTOM MARGINS? (1-255)' with the number of printable lines per page.

Respond to the query '# LINES EACH FOR TOP AND BOTTOM MARGIN? (0-10)' with the number of lines the disassembler is to skip at both the top and bottom of each page. If 0, the disassembler does no paging action. What the disassembler does for top and bottom margins is completely independent and in addition to anything a printer driver may be doing.

Respond ENTER to the query 'REPLY "ENTER" WHEN PRINTER AT TOP OF PAGE' when the printer is on and at top of page.

Respond to the query 'HIGH ASCII CODE FOR PRINTER? (5A - 7F)' with the 2 hexadecimal digit value (between 5AH and 7FH) for the highest printer code for your printer.

The STD option causes the disassembled code to be converted into EDTASMtype source text code. The resulting STD output (if not too large) can be loaded and assembled by EDTASM. The outputing of source text via the STD option works as follows:

After the cross reference table build phase and the RTD phase, respond to the query 'ASSEMBLER SOURCE TEXT OUTPUT FILESPEC?' with the filespec of the file to contain this generated source code. The file will be opened, and the generated text sent to it during the main disassembly phase.

All numeric values within the disassembled code are replaced with a 3 character alphabetic name unique to that value. The names are assigned arbitrarily in ascending alphabetic order with the first name assigned either AAA or the name specified by the FGN option.

If a numeric value does correspond to a disassembled location, the name assigned to that value is placed in the location name field of that location's instruction when it is sent to disk and displayed or printed.

If a numeric value does not correspond to a disassembled location, an EQU statement is generated at the end of the source text to equate the name with the value.

ORG statements are generated as necessary, and the END statement is generated as the last text statement.

The format of the reference table file created by the RTD option is:

1. 1 byte = C0H. Backward EOF. Ignore it.

2. 1 or more entries of the form:

Program LMOFFSET/CMD reads a tape or disk load module, displays its load information, optionally changes the program's load area, optionally attaches an appendage enabling the program at execution time to move itself from its load area to its execution area, optionally prepares the module to run under non-disk BASIC via SYSTEM, and stores the module onto disk or tape with a new name.

LMOFFSET functions as follows:

1. - Reads either a tape-type assembly load module from tape or a disk-type assembly load module from disk.

If from disk, LMOFFSET asks for the source filespec.

When reading from tape, a single * will be displayed when LMOFFSET is ready for the tape. Do rewind (if necessary) fast forward positioning (if necessary) and press PLAY. *** appears when tape read synchronization has completed. The character C will be displayed when a bad checksum is encountered. The character P will be displayed if leading extraneous data bytes encountered. The character I will be displayed if imbedded extraneous bytes are encountered.

2. - Displays (1) the area into which the module will load, (2) possible conflicts with system storage and (3) the module entry point. If an appendage is scheduled to be applied, the entry point will be into the appendage.

3. - Asks for a new load point. Reply either with a new load point or simply reply ENTER if satisfied with the current load point. If the user is simply transferring the load module without change, respond ENTER to the first request for a new load point and LMOFFSET will go directly to step 7 below.

4. - If a new load point specified, LMOFFSET asks if the appendage is to be suppressed.

If the appendage is to be suppressed, the resulting module can only be used via the DOS library command LOAD as there is no appendage to move the program to its execution area and the entry point is forced equal to 0. The resulting output load module can be used via LOAD where two or more load modules are loaded into main memory and then stored as one load module via DOS library command DUMP.

If the appendage is not to be suppressed, then LMOFFSET will append to the user program either a DOS enabled appendage or a DOS disabled appendage, depending on whether DOS is to be disabled or not.

5. - If a new load point was specified, LMOFFSET goes back to 3 above to display the resulting load information and ask for a new load point. If another load point is given, it cancels the one specified earlier, including its scheduled appendage, if any.

6. - Finally, when the response to 3 above is a null, then if a new load point was specified and the appendage is not suppressed, LMOFFSET asks if DOS is to be disabled. If so, the DOS disabled appendage is selected; if not, the DOS enabled appendage is selected.

7. - LMOFFSET next asks if the destination is disk or tape.

If the destination is disk, LMOFFSET asks for the filespec of the load module file to be created.

If the destination is to tape, LMOFFSET asks for the tape module name and then which tape speed (L or H). Next it asks for ENTER when the tape is positioned and in record mode.

8. - The resulting load module is then written to disk or tape. If a new load point was specified, (1) the load address for each object code record is altered, (2) if the appendage was not suppressed, an extra object code record (the appendage) is inserted before the entry point record and the entry point is set to the appendage's 1st byte, and (3) the entry point is set to 0000 if a new load address was specified and the appendage was suppressed.

9. - When the destination file write is completed or if an error or other type of termination occurs during step 7 or 8 above, LMOFFSET asks if the same module is to be written to another file (which may be the same file). If so, steps 7 and 8 above are repeated.

10. - When all done or if an error or other type of termination occurs while not in steps 7 or 8, LMOFFSET asks if another source load module is to be processed. If so, execution returns to step 1 above; if not, LMOFFSET exits back to DOS.

The up-arrow key may be used at any time to terminate the current LMOFFSET function. If LMOFFSET is waiting for a response, hold down the up-arrow key and press ENTER.

A module can end up with multiple appendages if the output from one LMOFFSET run is made the input to another, but doing this is strongly discouraged; in the case where one appendage is a DOS disable appendage, it must never be done. LMOFFSET knows nothing of a previously existing appendage appended by a revious execution of LMOFFSET.

LMOFFSET does not perform any object code relocation!!!! It only assigns code to new load locations so that DOS can load the module from disk without damage to DOS.

If the source program loads into the display area 3C00H - 3FFFH) without overflowing it, those object code records will not have their load addresses modified.

The appendage added to a module by LMOFFSET starts with 64 bytes of zeroes. This area is available to users to patch in special code. The load address of this patch area is the same as the module's resulting entry address, providing there is only one appendage. Z-80 code patched into this area will be the first executed when that program commences execution. This will be done before the program is moved to its execution locations and before DOS is disabled, if DOS is to be disabled.

When a program is to run in any part of the DOS area, a DOS disabling appendage must be specified. The DOS disabling appendage causes the user program to execute as if it was loaded from tape under the non-disk BASIC SYSTEM function.

When the resulting user program module is executed, the action is as follows:

For a DOS enabled appendage:

1. - Executes any user supplied code in the 64 byte patch area.

2. - Moves the main program to its execution locations.

3. - Commences execution of the main program.

For a DOS disable appendage:

1. - Executes any user supplied code in the 64 byte patch area.

2. - Moves the display screen contents to high memory.

3. - Displays the following:

4. - When the operator has done the above, the appendage continues execution.

5. - Restores the screen contents from high memory.

6. - Moves the main program to its execution locations.

7. - Commences execution of the main program.

The DIRCHECK/CMD module tests and lists the target diskette's directory. If errors are found in checking the directory, they are listed before the directory listing. DIRCHECK also allows the option of cleaning up (not repairing) the directory, and, as an aid to moving single density diskettes back and forth between the Models I and III under NEWDOS/80, allows the option of writing the directory protected.

To the query 'OUTPUT TO PRINTER', reply Y if output to go to printer and N if to go to the display.

To the query 'WHICH DRIVE CONTAINS TARGET DISKETTE', reply the target drive number, in decimal.

DIRCHECK reads the BOOT sector (the diskette's 1st sector), and tests that the first 2 bytes are 00H and FEH respectively. If they are, DIRCHECK uses the 3rd byte as the number of the lump at whose first sector the directory starts. If the first 2 bytes are not correct, DIRCHECK displays '***** DISKETTE 1ST SECTOR NOT "BOOT". ASSUMING DIRECTORY STARTS ON LUMP 17 DECIMAL.'.

DIRCHECK proceeds to read the directory. In previous NEWDOS versions, DIRCHECK refused to process a directory that was not write protected. Because of the problem of moving single density diskettes between the Model I and Model III under NEWDOS/80, an unprotected directory will now be accepted, with two error messages displayed, one at this time and one after the files have been listed. The error message is '***** AT LEAST ONE DIRECTORY SECTOR UNPROTECTED'. If this message appears along with many other errors, the user can assume that DIRCHECK has not found the directory and should NOT execute the W function described later.

DIRCHECK uses the drive's PDRIVE (see section 2.37) data to determine the number of lumps and granules accounted for by the directory. If the PDRIVE data is not correct for the diskette, it is very probable DIRCHECK will list errors that are, not actually present.

Complaints, if any, about the directory are next listed. If a number is given, it is in hexadecimal for use in directory repair via SUPERZAP. Do not try to repair a bad directory unless you know what you are doing!!!!!!! The next best thing is to try to extract valued files via COPY and then re-format the diskette having the bad directory.

If the complaint is about a directory entry for a file, either the primary or an extended entry, the hexadecimal code is the DEC for the file's FPDE. When the complaint deals with a file extended directory entry but does not specify the file name/type, the hexadecimal code is the DEC for the FXDE itself. When the complaint deals with a HIT sector byte, the hexadecimal code is the relative location of that byte in the HIT sector. When the complaint deals with a GAT sector byte, the hexadecimal code is the relative location of that byte in the GAT sector. When the complaint deals with a granule, the hexadecimal value is expressed in bb,r format where bb is both the lump number and the relative byte location of the lump's byte within the GAT sector and x is both the relative granule within the lump and the bit number, counting from zero from the right, within that GAT byte.

The diskette's name and date are next listed.

The files are next listed, with numeric values in decimal and the following definitions:

S - System file.

I - File has invisible attribute.

P=nnn - File has access level nnn, and both update and access passwords are non-blank.

EOF=sss/bbb - End Of File value. ass = the relative sector within the file. bbb = the relative byte within the sector.

nnn EXTS - nnn is the number of extent elements, maximum of four per FDE, used to account for this file's disk space.

nnn SECTORS - The number of sectors allocated to this file.

Lastly, the number of free granules and locked out granules for the diskette are displayed. If the diskette contains more than 60H (96 decimal) lumps or if GAT relative byte 60H equals 0FFH, DIRCHECK assumes that there is no lock-out (existence) table. Note, NEWDOS/80 does not mark granules as locked out; the lockout table is maintained only for compatibility with Model I TRSDOS.

If at least one directory sector is unprotected, another error message indicating such is displayed.

'FUNCTION COMPLETED' message is displayed followed by the query:

REPLY

N - TO EXIT PROGRAM

Y - IF ANOTHER DISKETTE FOR SAME SPECS

I - FOR PROGRAM RE-INITIALIZATION

W - TO WRITE DIRECTORY SECTORS PROTECTED

C - TO CLEAN UP (NOT REPAIR) THE DIRECTORY

Reply with one of the following:

N - Program exits to DOS at 402DH.

Y - Another diskette to be checked but with same response to the printer query.

I - Another diskette to be checked but with different response to the printer query.

W - The directory sectors are read and re-written in protected state. Refer to specifications for DOS command WRDIRP (section 2.49) and option SYSTEM option BN (section 2.46). This function is only meaningful for single density diskettes that are going from Model I to Model III or vice versa or used interchangeably.

C - All unused FDEs within the directory are zeroed. This is a cosmetic function only that clears out residual information from no longer used FDEs. Normally, when DOS releases FDEs via KILL or automatic space deallocation, it only zeroes bit 4 of the first byte of the FDE, leaving the rest of the information for the remote possibility that the sophisticated user will attempt to reclaim the file or the sectors it used to own.

During display or printing, pressing:

BREAK - processing will pause at end of current line or line group.

ENTER - continues processing.

UP-ARROW - terminates displaying or printing.

35 months ago Apparat converted the TRS-80's tape oriented editor/assembler to:

1. Read text from disk as well as cassette.

2. Write text and/or object to disk as well as cassette. Disk files are validity read after all sectors written.

3. Allow down-arrow scrolling to display up to 15 text lines.

4. Prevent the confusing printer output associated with DEEM. Only the 1st byte of associated object code is listed.

5. List symbols in alphabetical order with reference list.

6. Accept and convert lower case alpha to upper.

It was anticipated that Radio Shack would soon come out with a disk oriented editor/assembler that would eliminate any need for the Apparat enhancements. To a degree that has come to pass, but not sufficiently to bury the Apparat enhanced version. Since the Apparat enhanced version is based on the copyrighted tape editor/assembler, Apparat has always required and still requires, as a pre-condition of use of its enhanced version, that the user purchase a copy of the TRS-80 tape editor/assembler and thereby pay the royalty due. In an effort to enforce this, Apparat has always refused, and will continue to refuse, to supply any documentation for the editor/assembler beyond that dealing explicitly with Apparat's enhancements.

This EDTASM is essentially the same as that offered with NEWDOS/21 and NEWDOS/80 Version 1 except:

1. EDTASM will now display, as part of the 'A' CMD, after the TOTAL ERRORS display, the number of bytes left in the text area so the user can judge his approach to symbol table overflow or text buffer overflow.

2. (Model III only) Object code cannot be outputted to tape. The user must output the object code to disk and then use LMOFFSET to copy it to tape.

Supplemental instructions for the editor-assembler.

1. To load a text module into the text buffer, enter one of the following commands:

1. L D=filespec1 if text from disk

2. L T=nnnnnn if text from cassette

where filespec1 is the filespec for the assembler text module to be loaded into the text buffer from disk and nnnnnn is the name of the assembler text module to be loaded into the text buffer from tape.

Examples:

1. L D=OLDTEXT/SRC:1 loads the assembler text file OLDTEXT/SRC into the text buffer from the diskette currently mounted on drive 1.

2. L T=OLDTXT loads the assembler text file OLDTXT into the text buffer from tape.

If the text buffer already contains text, the query 'TEXT IN BUFFER. ARE YOU CONCATENATING???' appears. If you are not concatenating, reply N; the buffer is marked empty before loading the specified text module. If you are concatenating, reply Y to cause the new text to be appended onto the end of the old. No concern is shown for overlapping sequence numbers; therefore you should execute a N EDTASM command upon completion of the load to assure a valid set of ascending sequence numbers.

2. To store a text module:

1. W D=filespec2 if text going to disk

2. W T=nnnnnn if text going to cassette

where filespec 2 is the filespec of the disk file to receive the assembler text from the buffer and nnnnnn is the one to six character name given to the text file written to tape. Examples:

1. W D=NEWTEXT/SRC:1 The assembler text (not the object code) currently in the text buffer is written to file NEWTEXT/SRC on the current diskette mounted on drive 1.

2. W T=NEWTXT The assembler text currently in the text buffer is written to tape and named NEWTXT.

3. For A commands with NO option not specified, respond to the query 'OBJECT FILE TO DISK OR TAPE? REPLY D OR T?':

1. T (Model I only) Object code going to cassette. The program name will come from the A command.

2. D Object code going to disk. Respond to the query 'OBJECT FILESPEC?' with the nnnnnnnn/ttt.pppppppp:d filespec of the object module. The file will be opened immediately, but not written until end of assembly listing. The name in the A command is ignored.

4. When an output text or object disk file is opened, one of the following is displayed:

1. 'FILE ALREADY EXISTS. USE IT????'. Reply Y if this is your intention. Otherwise reply BREAK to terminate the W or A command.

2. '************** FILE NON-EXISTENT. REPLY 'C' TO CREATE IT'. Reply C if this is your intention. Otherwise reply BREAK to terminate the W or A command.

5. Due to an error in the original DOS, EDTASM runs with interrupts disabled (except when re-enabled by disk I/O) in order that use of BREAK will function properly.

6. This EDTASM can execute in a regular TRSDOS Model I environment.

7. This EDTASM uses the standard keyboard, display and printer routines and control blocks. Users altering the system beware!!!!

The BASIC program CHAINBLD/BAS is a simple program to allow users to create and modify chain files (chaining is discussed in section 4.3).

CHAINBLD operates in record mode, requiring that an EOL character (ENTER character) appear in the file at least every 240 bytes, and it treats each occurrence of the EOL character as both the end of a BASIC input line and the end of a record within a chain file. A11 inserts, deletions, replacements, moves and copies are done in terms of records.

Furthermore, CHAINBLD makes no provision (except for the old Version 1 hex codes 80 - 83) for the file to contain special non-printable characters. The rule is that if the string resulting from the BASIC statement LINEINPUT C$ does not contain a given character, then that character cannot become part of the chain file. The exception is the EOL character, which is automatically supplied by CHAINBLD. If the user needs special characters in his/her chain file, some other program must be used to build the chain file. As a last resort, there is always SUPERZAP.

Tp some space, be sure to specify .a string area size.

After initialization, the main menu is displayed (not to be confused with the edit menu). The choices are:

1. DELETE ALL TEXT LINES All the text lines in the string area are deleted and the edit menu is displayed. When CHAINBLD starts execution, there are no text lines in the string area.

2. LOAD EXISTING TEXT FROM DISK Use this option to edit an existing chain file. If the string area already contains text lines, CHAINBLD will ask if those lines are to be deleted. If not, CHAINBLD returns to the main menu as it assumes the user wants to do more with the previous text. Otherwise the old text lines are deleted.

CHAINBLD will then ask for the existing chain file's filespec. If the filespec does not contain a name extension, the name extension JCL is assumed. The file is then loaded into the string area. The file cannot exceed the string area capacity and cannot have more than 1000 lines. The file must be segmented into records as discussed above. After the load, CHAINBLD displays the edit menu.

3. SAVE TEXT TO DISK The user has completed the creation and/or editing of the chain file text and now wants to write it to disk. If there are no text lines, the CHAINBLD will ask if a null file is to be written; if not, CHAINBLD goes back to the main menu.

Next, CHAINBLD asks if the file is to be written so that it can be processed by NEWDOS/80 Version 1. If so, any /./0 through /./3 chain control records are changed as they are outputted by substituting the corresponding single byte control code (80H - 83H) in place of the /./x character sequence. The text in the string area is not changed.

CHAINBLD then asks for the output file filespec. If the filespec does not contain a name extension, the name extension JCL is used. The file is then written to disk. When done, CHAINBLD goes back to the main menu.

4. EDIT TEXT This option does nothing except display the edit menu.

5. EXIT PROGRAM If the string area contains text that has not yet been written to disk, CHAINBLD asks if the user really wants to exit the program; if not, CHAINBLD goes back to the main menu. Otherwise CHAINBLD deletes all text lines and releases all string space except 50 bytes. The program then ends in the normal manner.

When the edit menu is displayed the user has a number of choices:

1. List text lines. The text lines are implicitly numbered in sequential order regardless of the changes that take place is the text. Line numbers do not belong to individual text lines. Instead a line number indicates the line's position at the current time within the file. This means that insert, delete, copy and move all change the line numbers of some or all of the text lines. The L and ; edit commands allow the user to display the text lines. L; displays the first line. L/ displays the last. L52 displays the 52nd line. In each case, if any text lines follow the target line in the text, they are also displayed. The ; edit command allows forward text paging.

2. The I edit command allows for a one or more text lines to be inserted in the text after the specified line. 10 does inserting at the start of the text. I/ does inserting at the end of the text. 123 does inserting after line 23. Lines are inserted into the text until, but not including, a line containing the /.// character sequence is encountered. That character sequence terminates the line insert mode.

3. The R edit command allows a new line to replace an old line. R43 causes text line 43 to be replaced with the new line that CHAINBLD will ask for.

4. The D edit command allows one or more text lines to be deleted. D34 deletes text line 34. D 20 41 deletes text lines 20 through 41.

5. The X edit command allows the specified text line to be added onto. Note that CHAINBLD does not actually allow a line to be edited. The edit mode really refers to editing the entire text.

6. The C edit command allows the specified lines to be duplicated to another part of the text. C 20 30 5 causes a copy of text lines 20 through 30 to be inserted after text line 5. Please note that the old lines 20 through 40 will now have line numbers 31 through 42.

7. The M edit command allows the specified lines to be moved to another position in the text. M 20 30 5 causes the text lines 20 through 30 to be deleted from the text and reinserted after text line 5.

8. The U edit command redisplays the edit menu.

9. The Q edit command redisplays the main menu.

The best way to learn CHAINBLD is to use it. The NEWDOS/80 distribution diskette comes with a sample chain file named CHAINTST/JCL. Load it in and look at it. Once in the string area, you may modify the text as desired, but do not store it back out as CHAINTST/JCL; use some other name.

1. The object module ASPOOL contained on the NEWDOS/80 diskette is H. S. Gentry's automatic Spooler Program, modified by Apparat to operate with NEWDOS/80 and to self-relocate. This program will automatically direct your printer output to the disk, and then automatically print it on the printer. This spooler program will print in the background while your foreground main program is executing provided the main program every second or so either sends a byte to be spooled or checks the keyboard for a new input character.

This spooler program is included on the NEWDOS/80 diskette as a free program to NEWDOS/80 owners. It is NOT a fully supported part of NEWDOS/80.

The basic operation of NEWDOS/80 DOS assumes that output that DOS sends to the printer will not involve disk I/O enroute to the printer. Therefore, the spooler discards all printer output it senses coming from DOS (such as PRINT, JKL, DIR with P option) with the warning message CAN'T SPOOL FROM DOS being displayed once for each spooled file.

This spooler program does NOT allow a spool file to be printed multiple times; once printed, the file EOF is set to 0 and the file closed to reclaim the file space. This spooler program does NOT remember spool contents from one spool activation to the next (this includes a reset). The user is warned that while the spooler is active, do NOT use reset or DOS library command BOOT to get to DOS ready. Instead, if another way is not available, use DFG to get to MINIDOS and then DOS library command MDBORT to get to DOS READY or use '123' to get to the DEBUG facility and then use DEBUG command Q to get to DOS READY.

2. INITIAL SETUP. Create a working spool module.

Before the spool system can be used, working program module copy(s) of ASPOOL must be set up. You should set up a working program module for each different configuration you intend to use. When making a working program module, the input module 'filespec1' must ALWAYS be ASPOOL/MAS or a copy of it, and the output module 'filespec2' must NEVER be ASPOOL/MAS. To create a working spool program module (as opposed to the master), enter the DOS command filespec1,I (example: ASPOOL/MAS:0,I ). The program will then ask for parameter specifications:

The program asks if the software printer driver whose address in is 4026H - 4027H at the time of spooler activation is to be used to drive the printer. Reply Y for yes or N for no (the spooler will drive the printer). If N, then:

The program asks if the printer is parallel or serial. Answer P for parallel or S for serial. If serial, then:

The program asks if the printer is an H14 type. Respond Y for yes and N for no.

The program asks if the printer output is to be formed into pages with a form feed between pages. Reply Y for yes and N for no. If Y, then:

The user will be asked for the number of print lines per page. Enter a number between 10 and 99.

The program asks if the printer uses a soft or hard form feed. A soft form feed is done by counting the number of lines printed and then printing carriage returns (OUR) (with or without line feeds (OAR)) until the end of the page is reached. A hard form feed is a single control character that causes a form feed function. If your printer will recognize a hard form feed answer H, otherwise answer S. If soft form, then:

The program asks for the total number of lines per page. Answer with a number between 10 and 99.

The program asks if a form feed is to be done at the end of each print file. Reply Y for yes and N for no.

The next question concerns automatic linefeed on each carriage return. Some printers linefeed on carriage returns and the computer should not output linefeeds. If your printer is of this type (Radio Shack standard) answer the question with N. If you want the software to generate linefeeds then answer with Y.

The program asks for the number of the disk drive that will be used to spool the print data. Answer with a number from 0 to 3.

The program asks for the number of seconds to transpire after the last keyboard key inputted until the spool program can start printing again. Respond with a 2 digit value 00 - 59. The purpose of a non-zero delay is to allow the keyboard to have primacy over the printer. When a keyboard key is depressed and if the spool program is printing a file, printer action will pause while keys are being inputted and until the required number of seconds have passed since the last key.

The program asks if the printer is to be driven by the timer interrupts (every 25ms on the Model I; every 33 or 25ms on the Model III) as well as via keyboard input and spooler output. Reply Y for yes if the interrupts are to be used; reply N for no. Allowing the interrupts to be used enables the spooler program to print while a foreground program is executing that does not frequently check the keyboard or send output to the spooler. The disadvantage of using the interrupts is that for a buffered printer, interrupts are disabled during the entire outputting of a line to the printer. However, the time delay will probably be no worse than that associated with disk I/O. If the interrupts are used, printing will nevertheless stop if the foreground program never sends anything to the spooler or tests the keyboard for input. This is because the disk I/O to read the next sector is done only during keyboard checking or main program output to the spooler. See circular buffer discussion for an additional disadvantage when the interrupts are used.

The program asks if the circular buffer is to be used to buffer keyboard input characters. Reply Y if yes; N if no. The circular buffer helps prevent lost keyboard input. If the 25ms interrupt is enabled to drive the printer (see above option), the circular buffer uses the ROM keyboard character input routine and therefore disables any drivers (such as NEWDOS/80's keyboard intercept routine, lower case driver, etc.) activated before the spooler is activated. If the 25ms interrupt is not used to send spooled output to the printer, then that does not frequently check the keyboard or send output to the spooler. The disadvantage of using the interrupts is that, for a buffered printer, interrupts are disabled during the entire outputting of a line to the printer. However, the time delay will probably be no worse than that associated with disk I/O. If the interrupts are used, printing will nevertheless stop if the foreground program never sends anything to the spooler or tests the keyboard for input. This is because the disk I/O to read the next sector is done only during keyboard checking or main program output to the spooler. See circular buffer discussion for an additional disadvantage when the interrupts are used.

The program asks if the circular buffer is to be used to buffer keyboard input characters. Reply Y if yes; N if no. The circular buffer helps prevent lost keyboard input. If the 25ms interrupt is enabled to drive the printer (see above option), the circular buffer uses the ROM keyboard character input routine and therefore disables any drivers (such as NEWDOS/80's keyboard intercept routine, lower case driver, etc.) activated before the spooler is activated. If the 25ms interrupt is not used to send spooled output to the printer, then the regular keyboard routine(s) (as existed in the 4016H - 4017H vector at spool activation) is used. This latter also holds if the circular buffer is not used, regardless of whether or not the 25ms interrupt is used.

Now that the spooler has all the initialization parameters, the in-main-memory program is altered. The program then asks for the filespec of the working program module to be stored on disk. Respond with the filespec you will use in the filespec2,A DOS command discussed below; do NOT respond ASPOOL/MAS!!!!!! The working program module will be written to disk, and the spool program exits to DOS via 402DH. HINT: Use SPOOLER/CMD for filespec

3. ACTIVATE SPOOLING. When spooling is to be used, enter the DOS command "filespec2,A" (example: SPOOLER,A ) where filespec2 is the filespec of one of the working spool program modules you have created. filespec2 must NEVER be ASPOOL/MAS. If the spooler is already active, 'FILE ALREADY EXISTS' error message is displayed.

The module will load into the 5200H - 5FFFH region, relocate itself to HIMEM-areasize1+1, and sets HIMEM = HIMEM-areasize1 where HIMEM is the DOS high memory address contained in Model I locations 4049H - 404AH (Model III locations 4411H - 4412H) and areasize1 is the amount of memory required by the spooler. Then the keyboard vector at 4016H - 4017H and the printer vector at 4026H -4027H are intercepted to vector to the spooler. If interrupts are to be used, a routine is entered into NEWDOS/80's 25ms interrupt chain of user interrupt routines. 'SPOOLER ACTIVE' is displayed, and the 402DH exit is taken to DOS.

The spooler is now active. All data intended for the printer will be directed to one of five disk files (POOL1, POOL2, POOL3, POOL4, POOL5). Why five files you may ask? Well, when you have "printed" as much data as you wish and would like that data to be actually printed on the real printer, you send an end-of-file to ASPOOL. This is done either via DOS command *ASP,W (CMD"*ASP,W" from BASIC) or by outputting to the spooler a 03 byte in the normal print stream

(LPRINT CHR$(3) from BASIC ). The file that was spooling will be closed and scheduled for printing. You may now spool to another file by just "printing" more data. The data will be placed on the disk while the first data file is being printed. This procedure may be repeated five times. If you try to spool a sixth file before the first has been printed on the real printer, the system will display 'SPOOL FULL. WAITING ON PRINTER' and will hang until a file is printed. All data is printed on the real printer in the background while the current or another main main task is executing or simply while the system is waiting for the user to tell it what to do next. Whenever *ASP,W is executed or a 03 byte is seen in the output to the spooler, the spooler program considers this an end of file (performing top-of-form if specified) even though you may be sectioning your spooled output for one report to keep the printer going and avoid running out of space.

Warning!!! The Model III ROM routine, normally used by the spooler, will discard the current character being sent to the printer if it senses the printer is not ready (including busy) and the BREAK key is pressed. Since the executing foreground program may be using the BREAK key while the spooler is printing in the background, there will be times when printer characters will be lost, unknown to the spooler. This can serious limit the usefulness of any spooler on the Model III that uses the ROM printer driver routine.

You may bring the spool system down gracefully at any time by the DOS command *ASP,S (CMD"*ASP,S" from BASIC) or by sending a 04 byte in the normal output to the spooler (LPRINT CHR$(4) from BASIC). This procedure will purge the current spool file, will prevent any new files from being created, and will display 'SPOOL STOPPING'. Main program execution then continues, any characters sent to the spooler will be ignored and the spooler continues to print any files that have been scheduled. When all files have been printed, the *ASP,P function is performed. NOTE, if the spooler appears to hang, it is probably waiting for the main program to check the keyboard. If the main program can't do this, try DFG, but wait till the drives stop.

You may bring the spool system down abruptly at any time by entering DOS command *ASP,P (CMD"*ASP,P" from BASIC). All remaining spooled data is lost. If an interrupt routine was active, it is purged. The keyboard and printer vectors are restored to what values they were when the spooler activated. If DOS's HIMEM value is the same as that set by the spooler when activated, HIMEM is set back to what it was before the spooler was activated, thus reclaiming the spooler's main memory. However, it the HIMEM is not the same, HIMEM is not changed, and the spooler memory remains lost to subsequent main programs. 'SPOOLER PURGED' is displayed, and the DOS 402UH exit taken to DOS.

You may flush the print queue at any time by entering DOS command *ASP,C (CMD"*ASP,C" from BASIC). The spooler will respond with "CLEAR BACKLOG OR PRINT (B/P)?". Respond with a B and Enter if you wish to clear the backlog, or a P and Enter to stop printing the current print file. Clearing the backlog does not purge the current print file, and clearing the current print file does not purge the backlog.

The status of the spool system may be determined at any time by entering the DOS command *ASP (CMD"*ASP" from BASIC). The system will print a list of all files waiting to be printed (BACKLOG) and any file that is open for printing or spooling. If the system has been stopped but not yet purged, "SPOOL STOPPING" will be displayed. If the spooler has been purged or not activated, 'FILE NOT IN DIRECTORY' is displayed.

Continue to ...

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

Skip to ...

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

Chapter 4: DOS Features

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

Chapter 6: Additional Programs Supplied on NEWDOS/80 Diskette