NEWDOS/80 v2.0 Reference – Chapter 5-6

5. DOS MODULES, DATA STRUCTURES, AND MISCELLANEOUS INFORMATION

This chapter gives information about the modules on the NEWDOS/80 diskette, about diskette directories and about File Control Blocks. The novice user should read sections 5.1 and 5.4 and leave the other sections for another time.

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.

1. Respond to the query ‘FILESPEC?’ with the filespec of the load module to be disassembled.

2. Respond to the query ‘OFFSET OBJECT VIRTUAL ADDRESSES BY? (HEX)’ with either null (meaning 0) or a 1 to 4 digit hexadecimal number (without suffixed H) which when added to the load addresses within the load module will give the proper address where the instructions being disassembled would be during normal execution of that code. This parameter is needed when an object module loads to one place in main memory, but actually executes from another. Wraparound is allowed. Example:

If the object module loads into C000H – FFFFH but is to execute in 7000H – AFFFH, applying an offset of B000 will cause the disassembler to disassemble as if the load was actually done to 7000H – AFFFA.

3. Respond to the query ‘VIRTUAL RESTART LOCATION? (HEX)’ with either null (meaning start at the file beginning) or a 1 to 4 digit hexadecimal number (without the suffixed H) which is the listed location of any instruction of the disassembly. This allows restart of a large disassembly within the instruction print portion of the listing, and the location chosen is usually the location value for the first instruction on the page where printing was interrupted.

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:

1. 2 byte memory location value, 1st byte = low value, 2nd = high.

2. Control byte, bits 7 – 0 (7 is left most):

7-6 = 11. Dummy last entry in table. Ignore all other bits and bytes of the entry.

7-6 = 01. Referencee entry. Bits 5-0 = 0. The location is referenced by one or more of the subsequent referencer entries.

7-6 = 00. Referencor entry. The instruction at this location referenced the location of the previous reference entry. Bits 5-0 contain the references instruction type: 0 = S, 1 = T, 2 = U, 3 = V, 4 = W, 5 = X, 8 = P, 9 = L, and 10 = R. See a reference listing for definitions.

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:

RECORD AND THEN PERFORM THE FOLLOWING INSTRUCTIONS

1. HOLD DOWN BREAK KEY AND PRESS RESET TO ACTIVATE NON-DISK BASIC.

2. RELEASE BREAK KEY AND ENTER BASIC INITIALIZATION RESPONSES.

3. ENTER “SYSTEM”.

4. ENTER “.”

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.

Navigation

Go to …

Page 5 (Chapter 7 – Disk BASIC)

Skip to …

Page 6 (Chapter 8-End)

Go back to …

Page 1 (Introduction and DOS Library Commands Part 1: APPENDto CREATE)
Page 2 (Dos Library Commands Continued: DIRto WRDIRP)
Page 3 (Chapters 3-4 – DOS Routines and DOS Features)