Table of Contents
3. DOS ROUTINES.
These DOS routines have entry and exit conditions, and rather than repeat them in each routine’s specification, some of the conditions are defined here with the using routine’s specification simply referring to the condition’s code.
- Only register AF is altered by the routine. Any other registers used by the routine are saved on entry and restored on exit.
- On exit, Z state is set if no error is encountered during the routine’s execution. NZ state is set if a DOS error is encountered, and register A contains a DOS error code. The setting of Z and NZ takes precedence over the setting of other flags such as C and NC.
- On entry, DE points to an open FCB.
There are incompatibilities with TRSDOS in the use of some of these routines. They are discussed briefly in the routines where they occur, so study them carefully. The reader should also be aware of the differences in the way the FCB fields NEXT and EOF are maintained (see FCB specification, section 5.9).
The discussion of each routine gives its entry address (the address to be used in the CALL or JP Z-80 instruction), then its title (if one is appropriate), and then its specification.
Unless otherwise specified, the DOS routine uses the invoker’s stack. Unless specified as a dead end routine, the DOS routine exits to the caller.
Many of these routines use a FCB (see section 5.9). NEWDOS/80 on both the Models I and III and Model I TRSDOS all use a 32 byte FCB while Model III TRSDOS uses a 50 byte FCB. NEWDOS/80 will run with user programs having the 50 bytes FCB but will only use the first 32 bytes of those FCBs. Programs using a 32 byte FCB with Model III TRSDOS will have problems.
The routines listed below are not necessarily in ascending numeric order.
If either MINI-DOS or DOS-CALL, the stack pointer is set to where it was before the last DOS command; otherwise it is set to DOS’s stack area and the BREAK key is enabled/disabled according to system option AG.
If DOS-CALL and if either not chaining or chaining is not to be continued at the current DOS level, all registers except AF are restored to as they existed on DOS-CALL entry, Z state is set, and a return is made to the DOS- CALL invoker. If this was the outermost DOS-CALL level, DOS is taken out of DOS-CALL state.
If RUN-ONLY and if chaining is not active, the message ‘RUN ONLY STOPPED!! KEY ‘ R’ FOR RESET.’ is displayed, DOS loops waiting on the reply, and then executes DOS command BOOT (see section 2.7).
If DOS-CALL and if chaining is to continue at the current DOS-CALL level, DOS waits for the next command from the chain file.
If MINI-DOS, then MINI-NEWDOS/80 READY is displayed,. and DOS waits for the next command.
If chaining is active, DOS waits for the next command from the chain file.
NEWDOS/80 READY is displayed and DOS waits for the next input command.
If CHAINING, chaining is aborted.
If DOS-CALL, the current DOS-CALL level is exited in the same manner as for 402DH, except that C state is set.
If CHAINING, chaining is aborted.
If DOS-CALL, the current DOS-CALL level is exited in the same manner as for 402DH exit, except NZ and NC state is set and the DOS error code is in register A. The error MSA is not displayed.
Otherwise the DOS error message is displayed, and an exit is taken to 402DH.
A program way CALL 4409H to display an error MSA by placing the error code in A and setting bit 7 of register A equal to 1. The appropriate DOS error message will be displayed. On return, only the F register has been altered.
The Model I TRSDOS will print diagnostics if bit 6 of register A equals 0. The Model III TRSDOS displays only the error number if that bit equals 0 and the error message if that bit equals 1. NEWDOS/80 ignores the value of that bit.
Debugging hint: By setting the 4 bytes at 4409H equal to CD 0D 44 C9, the error display routine can be made to invoke DEBUG instead of displaying the error message.
1st 2 bytes: Used by DOS as a forward chain pointer. On entry, the two bytes can be any value.
3rd byte: The number of 25ms intervals to pass between invocations of the user’s routine. Example, if the routine is to be invoked every second, the 3rd byte must be set = 40 (28H). DOS does not alter this byte.
4th byte: Count down value to the next invocation. On entry, this byte should be properly initialized to a value greater than 0 but less than or equal to the value in the 3rd byte. Every 25ms interrupt, DOS decrements this value. If the result is non-zero, this routine is bypassed for this 25ms interrupt. If the result – 0, the value from the 3rd byte is moved into the fourth byte, registers HL, DE, BC and AF are saved, and the user routine is called at its 5th byte. Any other registers used by the routine must be saved/restored by it. Interrupts are disabled, and the user routine must not re-enable them.
While a user interrupt routine is in the interrupt chain, it must not be altered in any way except by a routine that runs with interrupts disabled; the first two bytes must never be altered.
Model I TRSDOS uses the 4 vectors, 4410K, 4413H, 4416H and 4419H, for its user- “interrupt routine handling. NEWDOS/80 uses only 4410H and 4413H for non- compatible handling of these routines. Any program using a 25ms interrupt user routine in TRSDOS must be modified to work under NEWDOS/80. This is a major incompatibility between the two Model I systems.
Model III TRSDOS has not yet made any provision for user timer routines, using 4410H – 441BH for other purposes, including HIMEM.
Model III NEWDOS/80 continues with the user timer interrupt routine mechanism used on the Model I, except that 447BH is the routine enqueue vector instead of 4410H, and in order to continue with 25 ms counting where the Model III clock actually counts in either 30ths or 25ths of a second, a second pass through the user routine check and invocation sequence is done when necessary to bring 25ms counting up with the real clock. If a user routine is being invoked every 25 ms, the routine must be prepared to accept two invocations within the same timer interrupt.
See section 3.8 for TRSDOS incompatibility.
This routine does not exist in TRSDOS; see section 3.8 for incompatibility.
DOS-CALL is now legal under CHAINING where it was not in NEWDOS/80 Version 1.
DOS-CALL is the way BASIC executes the DOS command contained within the BASIC statement CMD”xx” where xx is the DOS command.
The DOS-CALL caller is responsible for assuring that memory conflicts do not arise and that sufficient stack space is available.
Nested calls to DOS-CALL may be executed. Upon exiting from a DOS-CALL level, the return is made to the next outer level. When the outermost level is exited, DOS leaves DOS-CALL state.
If the DOS command invokes a program, that program may use its own stack area, and it must exit using one of the three exits: 402DH, 4030H or 4409H. On exiting, the program may store a 2 byte parameter in 4403H, 4404H (17411, 17412 decimal) for use by the caller.
The 4419H vector is used differently in TRSDOS; see section 3.8 for incompatibility.
See section 4.4 for further discussion of DOS-CALL.
If the first text character is A – Z or 0 – 9, or if the first text character is * and the next character is A – Z or 0 – 9, text is moved from the HL area to the DE area until a character that is not /, ., :, A – Z, or 0 – 9 is encountered or until 32 bytes have been transferred. If less than 32 bytes, a 03H byte is placed after the last byte in the DE area to indicate end of filespec, and a return is made with Z state set. If the filespec is more than 31 characters it is considered improper as discussed in the following paragraph.
If the first character was improper, or if the first character was * but the 2nd was improper, a return is made with NZ state set.
On exit, if the terminator/improper byte equals 03 or 0DH, then HL points to that byte; otherwise HL points to the next byte.
The user will notice that NEWDOS/80 doesn’t check for an exact filespec; it leaves this to be done by the OPEN routines, 4420H and 4424H.
If the filespec in the FCB pointed to by register DE specifies an explicit drive number and the diskette mounted on that drive has a free FDE, the file is created on that diskette whether or not the diskette actually has any free space. If the filespec did not specify a drive number, the system starts searching mounted diskettes, starting with the drive number specified by SYSTEM option AO and preceding through higher numbered drives until a diskette with a free FDE is found. If a free FDE is not available, the file cannot be created, and the error exit is taken. –
Creating a file consists of converting a free FDE to a FPDE. This entails inserting the name and name extension (if any), encoding the password (if any) as both the update and access passwords, storing the LRECL (0 means 256) from register B, setting the EOF equal to 0, setting access level as FULL, and marking the file non-system, non-invisible. No diskette file space is assigned to the file at this time; in fact, DOS doesn’t even look to see if the diskette has any free space. Note, though the LRECL is stored in the FPDE during file creation, it is never used. Each subsequent open of the file uses the LRECL provided in register B.
After the file is created, the DOS routine at 4424H is called to perform the OPEN. On exit after a successful file create and open, Z and C states are set.
If passwords are enabled and the file has non-null passwords, then an error exit is taken if the filespec does not contain either the update or the access password. If passwords are disabled or the file has no passwords or the update password is specified, the FCB’s access level is set to FULL; otherwise the access level from the FPDE is placed into the FCB to limit the type of access for this file.
The FCB is converted from containing the filespec to containing information about the file, which will be used while the FCB is open to reduce the amount of directory I/O which would otherwise be required. The conversion entails copying the EOF and the 1st 4 extents from the FPDE, storing the LRECL from register B, setting bit 7 of the FCB’s 2nd byte equal to 1 if LRECL is not equal to 0 (to indicate logical record processing), setting NEXT equal to 0, storing the drive number and the FPDE’s DEC code, storing the 256 byte buffer pointer from register HL, setting the access level, setting bit 5 of the FCB’s 2nd byte equal to 1 to indicate that the buffer does not contain the current, sector and setting bit 7 of the FCB’s 1st byte equal to 1 to indicate that the FCB is open.
If bit 7 of the FCB’s 2nd byte equals 0, the sector represented by the high two bytes of the NEXT field is read into the FCB’s buffer and, if no error or if error code 6 (sector read protected), the NEXT field is advanced 256 bytes. If an error other than code 6 occurs, the NEXT field is not advanced, meaning the user can retry to read the same sector.
If bit 7 of the FCB’s 2nd byte equals 1, then a logical record of length equal to the FCB’s LRECL (where 0 means 256) is moved from the FCB’s buffer to the buffer pointed to by register HL on entry. As each byte is moved, the NEXT field is incremented. When the FCB’s buffer is empty, the next file sector is automatically read into it and byte movement continues. If an error occurs, including error code 6, the logical record move terminates, leaving NEXT advanced for the number of bytes moved.
If bit 1 of the FCB’s 1st byte equals 1, the NEXT and EOF fields are considered RBA’s within the diskette rather than within a file, thus giving the user the capability to read a diskette, rather than a file. The use of bit 0 of the FCB’s first byte is defined in section 3.20 below. DOS routines 0013H, 001BH, 4439H, 443CH and other routines that indirectly read or write sectors also operate as such if any of these two bits are on. The use of these 2 bits is incompatible with TRSDOS.
One incompatibility between NEWDOS and TRSDOS occurs when the program reads the EOF from the FCB to determine the number of bytes in the file. However, in many cases the user does not have to know what the EOF is. Instead, for both TRSDOS and NEWDOS, the user can read the file sector by sector, waiting for either of the two EOF errors. If the error code is 1CH (END OF FILE ENCOUNTERED), then the file ends on a sector boundary and the last sector read successfully was the file’s last. If the error code was 1DH (PAST END OF FILE), then the last sector successfully read was also the file’s last, but was only a partial sector with the value in FCB+8 equaling the number of bytes in that sector belonging to the file. Remember, this is true for both TRSDOS and NEWDOS; thus the same code can work for both.
If bit 7 of the FCB’s 2nd byte equals 0, the disk sector as defined by the NEXT field is written with the contents of the FCB’s buffer. Unless VERIFY is on (see section 2.48), verify read is not done. If no error, and if the lower order byte of NEXT equals 0, the NEXT field is advanced 256 bytes. Whether or not NEXT was advanced, if NEXT now exceeds EOF or if bit 6 of the FCB’s 2nd byte equals 0, EOF is set equal to NEXT. If an error occurred, NEXT is not altered, thus allowing the user to retry to write the same sector.
If bit 7 of the FCB’s 2nd byte equals 1, a logical record of length equal to the FCB’s LRECL (0 means 256) is moved from the caller’s buffer, pointed to by register HL on entry, to the FCB’s buffer. With each byte’s move, NEXT is incremented, and if NEXT now exceeds EOF or if bit 6 of the FCB’s 2nd byte equals 0, EOF is set equal to NEXT. When the FCB’s buffer fills, the buffer is written to the appropriate disk sector with verify read and then the logical record move continues, filling in the FCB’s buffer for the next file sector. Whenever an error occurs, the logical record move terminates, leaving NEXT advanced for the number of bytes moved.
Bit 1 of the FCB’s 1st byte functions as described in section 3.19. If bit 0 of that byte equals 1, then sectors are written protected (error code 6 on sector read).
If a verify read is done after the write of a protected sector, error code 6 is not returned to the caller as an error.
A significant incompatibility with TRSDOS lies in the fact that when a sector is written to disk in EWNDOS/80 and the low order byte of NEXT is non-zero, NEXT is not advanced by 256 bytes. In this case, NEWDOS/80 assumes that the caller is writing the last sector of the file (though it need not be) that is only partially full, and that NEXT already is the proper RBA value for EOF (if EOF is to be updated by the write).
One incompatibility between NEWDOS and TRSDOS is in setting the final EOF for a file that is written sector by sector but usually does not end on a sector boundary. However, if the program knows when it is about to write the last sector, whether partial or full, and can store the desired low EOF byte value in FCB+5 just before writing that last sector, both TRSDOS and NEWDOS will exit from that write with the same EOF. Thus, in this instance, the same program code will work for both TRSDOS and NEWDOS, and no compatibility exists.
This address is defined differently in TRSDOS.
This address is defined differently in TRSDOS.
This address is defined differently in TRSDOS.
4 bytes reserved for use by DOS only.
8 byte logical routine name field containing the 1 – 8 character name of the routine, padded on the right with blanks.
If a routine with the same name already exists in the queue, FILE ALREADY EXISTS error code is returned with NZ set. Otherwise the routine is enqueued, and exit taken with Z state set. HL, DE, BC and AF are altered by this function. This function is new with MEWDOS/80.
Subsequently, whenever a DOS command of the form *name1 or *name1, parameters is executed, DOS searches its queue for a routine named name1, sets HL pointing to the parameters, if any, and jumps to the routine’s 13th byte. When the routine concludes, it should exit via 402DH, 4409H, or 4030H. The routine may use all registers, and can use the two bytes at 4403H – 4404H to receive or pass back a parameter. If the logical routine name1 does not exist in the queue, FILE NOT IN DIRECTORY error code is returned with NZ set.
4. DOS FEATURES
This chapter discusses DEBUG, MINI-DOS, CHAINING, DOS-CALL, JKL and asynchronous execution. DEBUG, DOS-CALL and asynchronous execution are primarily of interest to machine language programmers and those interested in Z-80 code. Other users should make a quick reading of DEBUG and DOS-CALL as they are frequently referred to elsewhere in the manual. MINI-DOS and JKL can be used immediately by everyone. CHAINING can be very complex; novice users will want to test out the chaining concept by using the BASIC program CHAINBLD/BAS to first inspect the sample chain file CHAINTST/JCL and then to create some elementary chain files.
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:
7. S = minus sign
6. Z = zero
5. 1 = unused bit
4. H = half-carry
3. 1 = unused bit
2. P = even parity or overflow
1. N = subtraction
0. C = carry
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:
- SYSTEM option AB = N.
- SYSTEM option A? = Y.
- 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.
- The current executing program may decide to execute a CHAIN or CHNON command via DOS-CALL (CMD”doscmd” in BASIC).
- 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).
- 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.
- 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.
- 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.
- /./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. - /./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. - /./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.
- /./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. - 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). - 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.
- 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.
- DOS must not be currently using its overlay area (main memory locations 4D00H – 51FFH).
- 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.
Navigation
Go to …
Page 4 (Chapters 5-6 – DOS Modules and SYSTEM Programs)
Skip to …
Page 5 (Chapter 7 – Disk BASIC)
Page 6 (Chapter 8-End)
Go back to …
Page 1 (Introduction and DOS Library Commands Part 1: APPEND to CREATE)
Page 2 (Dos Library Commands Continued: DIR to WRDIRP)